Filesystem MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Sandbox de caminho rígido — raízes configuradas na inicialização, sem escape via symlink ou ..
Ler, escrever, editar por linha, busca recursiva de conteúdo, árvore de diretórios
Reconhece binários — lê imagens, PDFs, áudio como blobs base64
Zero configuração — npx -y @modelcontextprotocol/server-filesystem <dir> e pronto
Publicado e assinado pela equipe de referência do MCP

Demo ao vivo

Como fica na prática

filesystem.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "filesystem": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/workspace"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Filesystem

Como refatorar uma função em toda a codebase sem quebrar nada

👤 Engenheiros renomeando/reformulando uma API que é usada em muitos arquivos ⏱ ~20 min intermediate

Quando usar: Você precisa renomear uma função, mudar sua assinatura ou inline um helper — e ela é usada em 30+ arquivos do repositório.

Pré-requisitos

Working tree do git limpo — git status não mostra nada staged — assim você pode usar git diff para revisar e git restore se necessário
Raiz do filesystem apontando para o repositório — Inicie com npx -y @modelcontextprotocol/server-filesystem /caminho/abs/do/repo

Fluxo

Encontrar todos os callsites

Busque na codebase cada uso de getUserProfile(. Agrupe os matches por arquivo e me dê a contagem por arquivo.✓ Copiado

→ Lista de arquivos com contagem de matches, separando tests de source
Simule a edição em um arquivo

Me mostre como ficaria a edição em src/api/users.ts — um diff, não o arquivo inteiro. Ainda não escreva.✓ Copiado

→ Patch de diff mínimo, não uma reescrita do arquivo todo
Aplicar em todos os arquivos e reportar

Aplique a mesma transformação em cada arquivo do passo 1. Use edit_file (nível de linha), não write_file (sobrescrita). Me diga qualquer arquivo onde o padrão não casou direito.✓ Copiado

→ Log de sucesso/skip por arquivo

Resultado: Um git diff focado e revisável no qual você pode rodar os testes — sem reescritas surpresa de arquivos inteiros.

Armadilhas

O Claude usa write_file e silenciosamente descarta metade do arquivo quando a edição é complexa — Exija explicitamente edit_file para mudanças in-place; só permita write_file para arquivos sendo criados do zero
O match atinge código não relacionado (ex.: getUserProfileAvatar) — Ancore a busca: getUserProfile( com o parêntese no final, ou use regex com word-boundary

Combine com: git · github

Triagem de um crash lendo arquivos de log de produção localmente

👤 Engenheiros on-call com logs em disco ⏱ ~15 min beginner

Quando usar: Você baixou um bundle de logs de um incidente de cliente e precisa achar a agulha no palheiro sem grep-fu.

Pré-requisitos

Logs em disco — Baixe/descompacte em uma pasta dedicada /incidents/<ticket>/

Fluxo

Tenha uma visão estrutural

Liste os arquivos em /incidents/TICKET-1234/. Para cada arquivo de log, mostre o tamanho e o primeiro + último timestamp dentro dele.✓ Copiado

→ Inventário delimitado por tempo
Encontre o cluster de erros

Busque em todos os .log pelo padrão ERROR|FATAL|panic. Me dê os 10 minutos com maior densidade de hits.✓ Copiado

→ Janela de tempo reduzida a minutos, não horas
Leia o contexto em volta do primeiro fatal

Leia 50 linhas de contexto em torno da primeira linha FATAL em app.log. Explique o que o sistema estava fazendo logo antes de quebrar.✓ Copiado

→ Reconstrução narrativa, não regurgitação do log

Resultado: Uma timeline de 5 frases que você pode colar no documento do incidente.

Armadilhas

Arquivos de log grandes (>50MB) estouram o contexto do modelo — Peça só extração tipo head/tail + grep; nunca peça pro Claude 'ler o arquivo inteiro' se for algo grande

Combine com: sentry · github

Faça perguntas sobre uma pasta de PDFs, Markdown e documentos

👤 Pesquisadores, analistas com uma pilha de material de referência ⏱ ~15 min beginner

Quando usar: Você tem 50 papers/contratos/relatórios em uma pasta e precisa extrair um fato específico ou comparar entre eles.

Pré-requisitos

Documentos organizados em uma pasta — Achate tudo em um diretório ou numa árvore rasa; o Claude percorre melhor estruturas mais planas

Fluxo

Indexe a pasta

Liste cada arquivo em /research/2026-market-study/. Para cada um, me diga o nome e os primeiros 200 caracteres.✓ Copiado

→ Inventário com previews rápidos
Faça a pergunta de verdade

Quais desses documentos mencionam 'contractual indemnity cap'? Para cada hit, cite a frase exata e me dê o nome do arquivo.✓ Copiado

→ Citações com nome do arquivo, não só vibe
Síntese entre documentos

Compare os indemnity caps nos 3 documentos que os têm. Qual é mais favorável para nós e por quê?✓ Copiado

→ Comparação lado a lado com citações diretas

Resultado: Respostas com citações no formato nome-do-arquivo+quote que você verifica em 30 segundos.

Armadilhas

PDFs escaneados são baseados em imagem — busca por conteúdo falha — Rode OCR antes (ex.: ocrmypdf) ou use um MCP dedicado a PDF; anote os arquivos 'não pesquisáveis' antes de começar
O Claude resume e perde a atribuição da fonte — Sempre exija nome do arquivo + quote exato no prompt; rejeite respostas sem isso

Combine com: memory

Faça o scaffold de um novo projeto a partir de uma spec em um único turno do chat

👤 Engenheiros começando um novo serviço/lib/protótipo ⏱ ~10 min beginner

Quando usar: Você tem uma spec de um parágrafo e quer o boilerplate (pastas, package.json, README, testes) materializado sem copiar de um repositório template.

Pré-requisitos

Diretório de destino vazio — mkdir /projects/newthing e aponte a raiz do filesystem para a pasta pai dele

Fluxo

Alinhe o layout antes de escrever

Quero uma ferramenta CLI em TypeScript/Node que faz X. Proponha a estrutura de pastas e liste cada arquivo que você criaria com um propósito em uma linha. Ainda não escreva.✓ Copiado

→ Plano arquivo-por-arquivo — você pode vetar antes de tocar no disco
Escreva os arquivos

Ficou bom. Crie todos esses arquivos em /projects/newthing/. Use conteúdo mínimo e idiomático — sem comentários de placeholder, sem stubs de 'TODO'.✓ Copiado

→ Arquivos no disco, compila/linta limpo de primeira
Verifique relendo

Leia cada arquivo que você acabou de criar e confirme que o projeto passaria em tsc --noEmit e npm test. Conserte qualquer coisa que não passaria.✓ Copiado

→ Self-check com correções concretas, sem enrolação

Resultado: Um esqueleto de projeto funcionando em 3 minutos em vez de 30.

Armadilhas

O Claude escreve arquivos e depois esquece o que escreveu no meio da sessão — Peça pra ele produzir o plano de arquivos primeiro, depois escrever; reler no fim pega desvios

Combine com: git · github

Combinações

Combine com outros MCPs para 10× de alavancagem

filesystem + github

Edite arquivos localmente, faça push de uma branch e abra um PR sem sair do chat

Conserte o typo em src/utils/format.ts:42, depois faça push em uma nova branch fix/typo-format e abra um PR com o título 'fix: typo in format.ts'.✓ Copiado

filesystem + git

Faça edições, revise o diff, commit — tudo dentro do Claude

Refatore os 3 helpers duplicados em src/ em um único util compartilhado. Me mostre o diff antes de commitar, depois commite com uma mensagem limpa.✓ Copiado

filesystem + sqlite

Leia um CSV do disco e carregue em uma tabela SQLite para análise

Leia /data/orders.csv, infira os tipos e carregue em /data/analysis.db como a tabela orders.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
read_text_file	path: str, head?: int, tail?: int	Ler um arquivo de texto; use head/tail para evitar carregar arquivos gigantes	free
read_media_file	path: str	Ler imagens, PDFs, áudio como base64 para input multimodal	free
read_multiple_files	paths: str[]	Ler em lote arquivos relacionados em um turno (mais rápido que N chamadas)	free
write_file	path: str, content: str	Criar um arquivo novo ou substituir completamente — destrutivo	free
edit_file	path: str, edits: [{oldText, newText}], dryRun?: bool	Edições em nível de linha mais seguras; sempre prefira sobre write_file para arquivos existentes	free
create_directory	path: str	Criar um diretório (recursivo, estilo mkdir -p)	free
list_directory	path: str	ls não recursivo	free
directory_tree	path: str	Visão geral da estrutura de um projeto de relance	free
move_file	source: str, destination: str	Renomear ou mover de lugar	free
search_files	path: str, pattern: str, excludePatterns?: str[]	Busca recursiva de conteúdo — tipo grep	free
get_file_info	path: str	Dar stat em um arquivo sem ler o conteúdo	free
list_allowed_directories	none	Confirmar com quais raízes o servidor foi iniciado	free

Custo e limites

O que custa rodar

Cota de API: Ilimitado — é I/O local
Tokens por chamada: Depende do tamanho do arquivo — orce ~1 token a cada 4 caracteres de conteúdo
Monetário: Grátis
Dica: Use search_files e head/tail em vez de ler arquivos inteiros. Um log de 2MB jogado no contexto custa ~500k tokens.

Segurança

Permissões, segredos, alcance

Escopos mínimos: filesystem-read filesystem-write (if mutating)

Armazenamento de credenciais: Sem credenciais — o acesso é feito via os diretórios raiz passados como argumentos

Saída de dados: Nenhuma pelo servidor — o conteúdo dos arquivos vai para o seu provedor de LLM pelo cliente MCP como contexto

Nunca conceda: root=/ root=$HOME root=/etc or /var

Nunca aponte a raiz para / ou $HOME — restrinja ao único diretório de projeto em que você está trabalhando.
O Claude sobrescreve sem pedir. Faça commit no git antes de qualquer sessão de edição multi-arquivo.

Solução de problemas

Erros comuns e correções

Error: Path is not within allowed directories

O arquivo está fora de todas as raízes passadas no launch. Reinicie o servidor com um argumento de raiz adicional, ou use list_allowed_directories para ver o que realmente está permitido.

Verificar: Peça ao Claude para chamar `list_allowed_directories`

ENOENT: no such file or directory

Typo no caminho ou suposição errada sobre o diretório de trabalho. Use directory_tree na raiz para ver o layout real.

edit_file: oldText not found

O padrão oldText precisa casar exatamente, incluindo whitespace. Peça ao Claude para read_text_file antes e copiar o substring exato.

Huge file freezes the client

Não leia arquivos completos maiores que poucos MB. Use os parâmetros head/tail em read_text_file, ou search_files para achar só as linhas relevantes.

Verificar: Cheque o tamanho do arquivo primeiro com `get_file_info`

Alternativas

Filesystem vs. outros

Alternativa	Quando usar	Troca
git MCP	Você precisa de operações cientes de versão (diff, blame, log) em vez de I/O de arquivo cru	Sem ferramentas de escrita; somente leitura através de uma lente git
GitHub MCP	Os arquivos vivem em um repositório remoto e você não quer um clone local	Exige um PAT; latência por arquivo é bem maior do que disco local
JetBrains MCP	Você quer que as edições apareçam na instância rodando da sua IDE com ferramentas de refactor	Exige uma IDE JetBrains aberta; mais pesado que o filesystem puro

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills