Como funciona o Filesystem MCP server de referência: as 13 ferramentas, as pastas permitidas, Roots, montagens Docker somente leitura e um gerador que escreve o JSON de configuração para você.
O Filesystem MCP server é o programa Node.js de referência do projeto Model Context Protocol que permite a um assistente de IA ler, escrever, pesquisar e mover arquivos, mas só dentro das pastas que você autorizar. Você lista essas pastas ao iniciá-lo, ou o seu app as fornece por meio de Roots. Tudo fora delas é recusado.
Filesystem MCP server em resumo
Item
Valor
Pacote npm
@modelcontextprotocol/server-filesystem
Imagem Docker
mcp/filesystem
Onde roda
No seu próprio computador, iniciado pelo seu app MCP
Limite de acesso
Somente pastas permitidas, via argumentos ou Roots
Ferramentas
13, das quais 9 só leem
MCP (Model Context Protocol) é um padrão aberto que permite a um app assistente chamar pequenos programas auxiliares chamados servidores. O servidor de arquivos é o primeiro que a maioria das pessoas instala, porque transforma "dá uma olhada na minha pasta de descrições de produtos" em algo que o assistente consegue fazer de verdade. Esta página explica o que ele pode acessar, como funciona o limite de pastas e como mantê-lo somente leitura. Use o gerador abaixo para criar uma configuração que você cola nas configurações de MCP do seu app.
Digite as pastas que você quer que o assistente veja, uma por linha, com caminhos completos.
Escolha npx (precisa de Node.js) ou Docker. O Docker pode montar pastas como somente leitura.
Escolha o formato de configuração que o seu app espera: a maioria usa mcpServers, o VS Code usa servers.
Copie o JSON para o arquivo de configuração MCP do seu app e reinicie o app para ele iniciar o servidor.
Compartilhe a menor pasta que resolva o trabalho, como uma única pasta de conteúdo, nunca o seu diretório pessoal inteiro.
Rode via Docker com montagens somente leitura quando o assistente só precisar ler.
Peça ao assistente para rodar list_allowed_directories primeiro, assim você vê exatamente o que ele recebeu.
Use a opção de dry run do edit_file antes de deixar mudanças caírem em arquivos importantes.
Mantenha um backup ou histórico de versões de tudo em que o assistente puder escrever.
Perguntas frequentes
O filesystem MCP server consegue ler arquivos fora das pastas que eu listo?
Não. O README afirma que todas as operações de arquivo ficam restritas às pastas permitidas. Se o cliente envia Roots, elas substituem por completo as pastas da linha de comando, então a lista permitida é a última que o seu app forneceu.
O que acontece se eu iniciá-lo sem nenhuma pasta?
Se o seu app suporta Roots, o servidor espera o app enviá-las. Se o app não suporta Roots e você não informou pastas, o servidor registra o motivo, fecha a conexão e sai com status 1.
Como deixo ele somente leitura?
O README documenta um jeito: rode a imagem Docker e adicione ro a cada bind mount, o que torna aquela pasta readonly para o servidor. Alguns apps também permitem aprovar ou bloquear ferramentas individualmente, o que ajuda, mas a montagem é o limite mais firme.
Ele pode apagar arquivos?
A lista de ferramentas não tem nenhuma de exclusão. Mesmo assim ele pode destruir conteúdo: write_file sobrescreve arquivos existentes e move_file remove a origem, por isso as duas aparecem como destrutivas na tabela de anotações do README.
Ele precisa de acesso à internet?
Não para o trabalho dele. Todas as ferramentas definem openWorldHint como false, ou seja, só mexem no sistema de arquivos local dentro das pastas permitidas. O npx baixa o pacote na primeira execução.
Pastas permitidas e Roots, em palavras simples
Há duas formas de dizer ao servidor quais pastas ele pode usar. A primeira é colocar os caminhos depois do nome do pacote na configuração, o que fixa a lista até você reiniciar. A segunda é Roots, um recurso em que o app assistente informa ao servidor quais pastas estão em jogo e pode mudar essa lista durante a execução.
O README chama Roots de método recomendado. O detalhe que importa para a segurança: quando as Roots do seu app estão valendo, uma atualização sem roots válidas revoga todo o acesso, em vez de voltar para as pastas que você digitou.
Tarefas úteis para quem tem um site ou loja
Aponte para uma pasta com dados de produtos exportados e peça uma lista dos itens sem descrição. Aponte para os rascunhos do seu blog e peça um resumo de quais posts citam um preço antigo. Aponte para uma cópia baixada do seu site e procure nomes de imagens quebrados.
Em todos os casos a pasta é uma cópia, não o site no ar, então uma edição errada não custa nada. Esse hábito vale mais do que qualquer configuração.
As 13 ferramentas e o que cada uma pode alterar
Somente leitura significa que o README marca a ferramenta com readOnlyHint true. Destrutiva significa que ela pode sobrescrever ou remover conteúdo existente.
Ferramentas do Filesystem MCP server
Ferramenta
O que faz
Altera arquivos?
Lê um arquivo como texto UTF-8, opcionalmente só as primeiras ou últimas N linhas
Não
Lê uma imagem, um áudio ou outro arquivo como base64, com o tipo MIME
Não
Lê vários arquivos de uma vez; uma falha não interrompe os outros
Não
Lista uma pasta com os prefixos [FILE] e [DIR]
Não
A mesma listagem com tamanhos, ordenável por nome ou tamanho
Não
Retorna uma árvore JSON aninhada de uma pasta
Não
Busca no estilo glob com padrões de exclusão opcionais
Não
Tamanho, datas, tipo e permissões
Não
Mostra quais pastas o servidor pode usar
Não
Cria uma pasta e as pastas pai que faltarem
Sim, não destrutiva
Cria ou sobrescreve um arquivo
Sim, destrutiva
Substitui o texto encontrado, com uma opção de prévia dryRun
Sim, destrutiva
Move ou renomeia; falha se o destino já existe
Sim, destrutiva
Exemplos de configuração
Rodar com npx, duas pastas
As pastas depois do nome do pacote viram as pastas permitidas. Precisa de Node.js na sua máquina.
Rodar com Docker, uma pasta somente leitura
As pastas são montadas em /projects. A flag ro impede o servidor de escrever naquela pasta.
Configuração de workspace do VS Code (.vscode/mcp.json)
O VS Code usa a chave servers. ${workspaceFolder} limita o servidor ao projeto que você tem aberto.
Gerador de configuração do Filesystem MCP
Digite as suas pastas e escolha como rodar o servidor. O JSON se atualiza enquanto você digita e nada sai do seu navegador.
Pastas permitidas, um caminho completo por linha
Rodar com
Formato da configuração
Montar pastas como somente leitura (só Docker)
A montagem somente leitura está documentada para Docker. Com npx o servidor pode escrever dentro das pastas que você listar.
JSON de configuração
npx (Node.js)
Docker
mcpServers (maioria dos apps)
servers (VS Code)
Adicione pelo menos uma pasta. O servidor precisa de uma pasta permitida para funcionar.
{v} não é um caminho completo. Comece com / no Mac ou Linux, ou com uma letra de unidade no Windows.