MCP Filesystem

O que faz

O MCP Filesystem dá ao Claude Code acesso a arquivos por meio de um servidor

MCP (Model Context Protocol) que opera dentro de uma sandbox: o agente só pode

ler e escrever dentro das pastas que você explicitamente autorizou. Nada fora desse

"jardim cercado" é alcançável, o que torna as operações de arquivo previsíveis,

seguras e fáceis de auditar.

Diferente de mandar o agente rodar comandos de shell soltos, aqui as operações passam

por ferramentas estruturadas (listar, ler, escrever, mover, criar pasta), com caminhos

validados contra a raiz permitida. Isso evita acidentes clássicos como apagar arquivos

fora do projeto ou seguir um caminho relativo perigoso.

Casos de uso típicos:

• Organizar uma pasta bagunçada de downloads ou de assets de um projeto.
• Gerar, mover e renomear arquivos de conteúdo (posts, roteiros, exports) em lote.
• Inspecionar uma árvore de diretórios e produzir um inventário/relatório.
• Criar estruturas de pastas padronizadas para novos projetos ou aulas.

Instalação

1. Copie a pasta mcp-filesystem/ para o diretório de plugins do Claude Code.
2. Garanta Node.js 18+ (o servidor é baixado via npx).
3. Defina FS_ALLOWED_DIR apontando para a pasta que o agente pode acessar.
4. Reinicie o Claude Code. O .mcp.json registra o servidor filesystem

automaticamente, limitado ao diretório informado.

Comandos disponíveis

• /fs-organizar — analisa uma pasta e reorganiza arquivos em subpastas por tipo,

data ou tema, sempre pedindo confirmação antes de mover.

• /fs-inventario — percorre a árvore de diretórios e gera um relatório legível

(quantidade, tamanhos, tipos e possíveis duplicados aparentes).

Configuração

Sempre por nome de variável de ambiente — nunca cole caminhos sensíveis fixos no

código compartilhado.

• FS_ALLOWED_DIR — obrigatória. Caminho absoluto da pasta autorizada, por

exemplo /home/voce/projetos/conteudo. Tudo fora dela é inacessível ao agente.

• FS_READONLY — opcional; se você quiser um modo de leitura, aponte o servidor para

uma cópia e trate-a como descartável (o servidor padrão permite escrita dentro da

raiz autorizada).

Dica: para tarefas só de leitura, autorize uma pasta de cópia em vez da original.

Assim, qualquer escrita acidental não afeta seus dados de verdade.

Exemplo de uso

/fs-inventario

O Claude lista a árvore de FS_ALLOWED_DIR, mostra quantos arquivos existem por

extensão, os maiores arquivos e pastas vazias. Em seguida:

/fs-organizar Separe por tipo: imagens, documentos, vídeos e outros.

Ele propõe um plano de movimentação (origem → destino), espera seu "ok" e só então

executa as operações via MCP, relatando cada arquivo movido.

Segurança e limites

• Sandbox é a defesa principal. O agente nunca acessa nada fora de

FS_ALLOWED_DIR. Escolha esse diretório com cuidado e evite apontar para a raiz do

sistema ou para $HOME inteiro.

• Confirmação antes de mover/apagar. Os comandos deste plugin sempre apresentam o

plano e pedem aprovação antes de qualquer operação destrutiva.

• Faça backup do que importa. Operações em lote são rápidas; um backup ou um

commit Git antes de organizar evita arrependimentos.

• Auditabilidade: prefira trabalhar em pastas versionadas (Git) para que toda

mudança fique registrada e possa ser revertida.

• Sem comandos de shell arbitrários: este plugin usa apenas operações de arquivo

estruturadas, reduzindo a superfície de risco.