Filesystem MCP

Servidor MCP de sistema de arquivos seguro para ler, escrever, pesquisar, comparar e aplicar patches em arquivos.

Documentação

Servidor Filesystem MCP

Visão geral

Filesystem-MCP é um servidor Model Context Protocol que permite que assistentes de IA leiam e escrevam arquivos dentro de diretórios explicitamente permitidos. Padrões de arquivos sensíveis (.env, *.pem, *id_rsa*) são bloqueados por padrão. Ele expõe ferramentas, recursos e prompts de sistema de arquivos via transporte stdio ou Streamable HTTP.

Aspecto	Detalhes
Status	Ativo (veja o selo npm para a versão atual)
Linguagem	TypeScript (estrito)
Runtime	Node.js >= 24
Pacote	npm
Licença	MIT

Recursos

Recurso	Descrição
Proteção de caminho	Cada caminho é validado contra raízes permitidas; `.env`, `.pem`, `id_rsa*` e padrões semelhantes são negados
Ferramentas de sistema de arquivos	Navegue, inspecione, leia e escreva em todas as principais operações de arquivo
Operações em lote	A maioria das ferramentas aceita `path`, `paths[]`, ou `files[]` para execução paralela
Transporte duplo	stdio por padrão; `--port` habilita Streamable HTTP para clientes da era 2025 e 2026-07-28
Assinaturas de arquivo	Assinaturas de recursos enviam notificações de alteração quando arquivos monitorados são atualizados
Segurança de regex	RE2 em todas as ferramentas de busca: correspondência em tempo linear, então nenhum padrão pode causar ReDoS no servidor

Comparação com o servidor de referência

Como este servidor difere de @modelcontextprotocol/server-filesystem, verificado em seu README e código-fonte em 2026-09-24:

Capacidade	filesystem-mcp	Servidor de referência
Busca dentro de arquivos	`search_text`: regex RE2 ou literal, tempo linear	Nenhum; `search_files` corresponde apenas a nomes
Arquivos secretos	`.env`, `.pem`, `id_rsa*` negados por padrão	Não bloqueados
Modo somente leitura	`--read-only` remove toda ferramenta de mutação	Docker `ro` apenas montagens
Aplicar um diff unificado	`patch`	Nenhum
Comparar dois arquivos	`diff`	Nenhum
Substituir em muitos arquivos	`replace_text` sobre um glob	Nenhum
Monitorar arquivos	Assinaturas de recursos enviam notificações de alteração	Sem recursos
Transporte	stdio, ou Streamable HTTP com `--port`	stdio

Construído com

Camada	Tecnologia
Protocolo	MCP SDK v2 (`@modelcontextprotocol/server`)
Runtime	Node.js >= 24 · TypeScript 6 · ESM
Transporte	stdio (padrão) · Streamable HTTP (`--port`)
Regex	RE2 (`re2-wasm`) — tempo linear, sem lookahead/lookbehind/backreferences
Contêiner	Docker alpine · build multi-estágio · usuário não-root

Início rápido

[!NOTA] Requer Node.js ≥ 24.

Pré-requisitos

Requisito	Versão / Notas
Node.js	≥ 24
npm	Incluído com Node.js
Docker	Opcional — para uso em contêiner

Instalar via npx

npx -y @j0hanz/filesystem-mcp /path/to/allowed/dir

Ou instale globalmente:

npm install -g @j0hanz/filesystem-mcp
filesystem-mcp /path/to/allowed/dir

Instalar via Docker

docker run -i --rm \
  -v /path/to/project:/workspace:ro \
  ghcr.io/j0hanz/filesystem-mcp:latest \
  --read-only /workspace

Configurar no VS Code

Adicione a .vscode/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Ou instale via CLI:

code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'

Configurar no Visual Studio

Adicione a .vs\mcp.json no diretório da sua solução, ou %USERPROFILE%\.mcp.json para uma configuração global:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Configurar no Claude Desktop

Um clique: baixe filesystem-mcp.mcpb, abra com o Claude Desktop e escolha os diretórios a permitir. O Node.js integrado do Claude Desktop o executa.

Ou configure manualmente. Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Instalar no Cursor

Adicione a .cursor/mcp.json na raiz do seu projeto (escopo do projeto), ou ~/.cursor/mcp.json para uma configuração global:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Instalar como plugin

O plugin filesystem-mcp conecta o servidor com padrões de escopo do projeto:

Cliente	Instalação
Claude Code	`/plugin marketplace add j0hanz/j0hanz-marketplace`, depois `/plugin install filesystem-mcp@j0hanz-marketplace`
Copilot CLI	`copilot plugin marketplace add j0hanz/j0hanz-marketplace`, depois `copilot plugin install filesystem-mcp@j0hanz-marketplace`
Antigravity CLI	`git clone https://github.com/j0hanz/j0hanz-marketplace`, depois `agy plugin install ./j0hanz-marketplace/plugins/filesystem-mcp`

O README do plugin cobre os padrões e como cada cliente escolhe o diretório do projeto.

Configuração do Docker

VS Code (.vscode/mcp.json) e Visual Studio (.vs\mcp.json):

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/workspace",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "/workspace"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json) e Cursor (mcp.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/workspace",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "/workspace"
      ]
    }
  }
}

[!NOTA] Para privilégio mínimo, use ambos os controles: :ro torna a montagem do contêiner somente leitura na fronteira do sistema operacional, enquanto o sinalizador --read-only do servidor remove ferramentas de mutação (create, edit, move, delete, patch, replace_text) de tools/list.

Uso

Ferramentas

Todas as ferramentas são limitadas às raízes configuradas. Chame list_roots primeiro para descobrir o que é permitido.

Navegar

Ferramenta	Descrição
`list_roots`	Lista as raízes de workspace permitidas. Chame primeiro — todas as outras ferramentas são limitadas a elas.
`list`	Lista o conteúdo do diretório. Retorna entradas (diretórios primeiro, alfabético) e uma árvore ASCII.
`find_files`	Encontra arquivos por padrão glob (ex.: `*/.ts`). Retorna arquivos correspondentes com metadados.

Inspecionar

Ferramenta	Descrição
`stat`	Obtém metadados de arquivo/diretório: tamanho, hora de modificação, permissões, tipo MIME, estimativa de tokens.
`search_text`	Busca conteúdo de arquivos por texto (semelhante a grep). Retorna linhas correspondentes com contexto.
`diff`	Compara dois arquivos e retorna um diff unificado com contagens de linhas adicionadas/removidas.

Ler

Ferramenta	Descrição
`read`	Lê um arquivo de texto. Suporta intervalos de head/tail e de linhas. Aceita `paths[]` para lotes.

Escrever

Ferramenta	Descrição
`create`	Cria um ou mais arquivos, criando diretórios pai conforme necessário. Um arquivo existente solicita ao usuário confirmar a sobrescrita; `overwrite: true` em uma entrada pula o prompt, `append: true` adiciona ao final.
`edit`	Aplica substituições de strings literais sequenciais a um ou mais arquivos (até 5 arquivos por chamada, 100 edições por arquivo).
`move`	Move, renomeia ou copia (`copy: true`) um ou mais arquivos/diretórios para destinos explícitos.
`delete`	Exclui permanentemente um ou mais arquivos ou diretórios. Esta ação é irreversível.
`replace_text`	Busca e substitui em massa em arquivos que correspondem a um padrão glob.
`patch`	Aplica um diff unificado de arquivo único e grava o resultado.

Recursos

URI	Descrição
`internal://instructions`	Guia de navegação do servidor — visão geral das ferramentas, restrições e recuperação de erros.
`filesystem-mcp://file/{+path}`	Lê um arquivo do workspace. Assine para receber notificações push em alterações.
`filesystem-mcp://result/{id}`	Saída de ferramenta em cache efêmera. Expira após ~60 segundos, remoção ou reinício do servidor.

Prompts

Prompt	Descrição
`get-help`	Retorna instruções de uso, opcionalmente filtradas para uma seção específica.

Estrutura do projeto

filesystem-mcp/
├── __tests__/          Test suites (node --test) and shared helpers
├── docs/adr/           Architecture decision records
├── mcpb/manifest.json  Claude Desktop extension manifest
├── scripts/            Release-path scripts (MCPB pack, Smithery publish)
├── src/
│   ├── core/           Path guarding, filesystem facade, search, stores, watchers
│   ├── tools/          One file per tool, plus define.ts (registration) and batch.ts
│   ├── transport/      stdio.ts, http.ts, http-policy.ts (auth, Origin, rate limit), shared.ts
│   ├── cli.ts          Argument parsing and --print-config
│   ├── cli-help.ts     --help / --version text
│   ├── index.ts        Process entrypoint, shutdown, transport selection
│   ├── instructions.ts Server instructions sent to every client
│   ├── prompts.ts      Prompt definitions and registration
│   ├── resources.ts    Resource definitions, subscriptions, completion
│   ├── server.ts       Server factory and registrar composition
│   └── transport.ts    Facade re-exporting startServer / startHttpServer
└── Dockerfile          Multi-stage alpine build, non-root user

A composição do runtime flui de src/index.ts para src/transport/ (stdio ou HTTP), depois para src/server.ts, os registradores e, finalmente, src/core/. Cada registrador possui o contrato de dependência estreito que consome.

Caminho	Finalidade
`src/core/path.ts`	`PathGuard` — valida cada caminho contra as raízes permitidas
`src/core/fs.ts`	`GuardedFileSystem` — fachada de sistema de arquivos protegida
`src/tools/define.ts`	Estrutura de registro e execução de ferramentas
`src/tools/batch.ts`	Auxiliares de lote (runOverPaths, isTotalFailure)
`src/server.ts`	Constrói dependências compartilhadas e invoca os três registradores
`src/transport/`	stdio (`stdio.ts`), Streamable HTTP (`http.ts`), política HTTP (`http-policy.ts`)

Configuração

O servidor inicia com diretórios permitidos a partir da configuração explícita de inicialização:

Diretórios posicionais passados para filesystem-mcp.
Variável de ambiente FS_ALLOWED_DIRS (separada por : no POSIX ou ; no Windows).
Diretório de trabalho atual quando --allow-cwd está habilitado.

Conexões MCP legadas podem adicionalmente semear raízes através do fluxo roots/list obsoleto. Conexões modernas de 2026-07-28 não enviam automaticamente raízes do espaço de trabalho. Elas podem adicionar acesso após a inicialização chamando uma ferramenta com um caminho concreto e aprovando a concessão baseada em elicitação. list_roots relata as raízes já configuradas ou aceitas; não pode descobrir um espaço de trabalho desconhecido por si só.

Sobre HTTP, clientes da era 2025 são atendidos sem estado: ferramentas, recursos e prompts funcionam. Confirmações (exclusão recursiva, sobrescrita, concessões de acesso) precisam de um cliente 2026-07-28 ou stdio e respondem com um erro de ferramenta dizendo isso; assinaturas de arquivos não são anunciadas nessa perna, e um resources/subscribe enviado mesmo assim é recusado com método não encontrado.

Receitas globais recomendadas

VS Code / Cursor / Claude Code (receita principal)

Configure o diretório do projeto explicitamente:

Adicione à sua configuração global ou de escopo do projeto:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Claude Desktop (receita alternativa via variável de ambiente)

Claude Desktop e clientes similares não suportam o protocolo MCP Roots. Use a variável de ambiente FS_ALLOWED_DIRS para configurar as pastas permitidas.

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"],
      "env": {
        "FS_ALLOWED_DIRS": "/path/to/project1:/path/to/project2"
      }
    }
  }
}

(No Windows, separe os diretórios com ponto e vírgula ; em vez de dois pontos :).

Argumentos posicionais avançados / por projeto

Você também pode restringir o acesso a diretórios específicos passando argumentos posicionais diretamente:

# Start with explicit positional paths
filesystem-mcp /path/to/project1 /path/to/project2

Referência de configuração

Flags de CLI

Flag	Padrão	Finalidade
`[dirs...]`	—	Um ou mais diretórios raiz permitidos (posicional). Um argumento inteiro `${NAME}` é lido do ambiente e descartado quando não definido
`--allow-cwd`	`false`	Também permitir o diretório de trabalho atual como raiz
`--walk-cwd`	`false`	Subir a partir do CWD para encontrar uma raiz de projeto; implica `--allow-cwd`
`--allow-missing-roots`	`false`	Iniciar mesmo se os diretórios permitidos configurados não existirem
`--port <n>`	—	Habilitar transporte Streamable HTTP na porta fornecida (env: `FS_PORT`)
`--http-host <host>`	—	Endereço de bind do servidor HTTP (env: `FS_HTTP_HOST`)
`--api-key <key>`	—	Exigir esta chave de API em solicitações HTTP (env: `FS_API_KEY`)
`--read-only`	`false`	Desabilitar ferramentas de escrita: `create`, `edit`, `delete`, `move`, `patch`, `replace_text`
`--deny <pattern>`	—	Bloquear caminhos que correspondam a este padrão; repetível
`--allow <pattern>`	—	Isentar um padrão da lista de bloqueio sensível embutida; repetível (env: `FS_ALLOWLIST`). Não remove entradas `--deny`/`FS_DENYLIST`
`--allow-sensitive`	`false`	Permitir acesso a caminhos de sistema sensíveis (env: `FS_ALLOW_SENSITIVE`)
`--root-boundary <path>`	—	Exigir que todas as raízes permitidas estejam sob este caminho (env: `FS_ROOT_BOUNDARY`)
`--max-file-size <bytes>`	—	Tamanho máximo de arquivo para leituras em bytes (env: `FS_MAX_FILE_SIZE`)
`--log-level <level>`	`info`	Nível de log RFC 5424, `debug` até `emergency` (env: `FS_LOG_LEVEL`)
`--print-config`	`false`	Imprimir a configuração ativa como JSON e sair

Padrões --deny e --allow suportam * (qualquer execução dentro de um segmento), ** (qualquer execução de segmentos), ?, classes [...] e alternância {a,b}. Nomes com ponto inicial (ocultos) correspondem como qualquer outro — secrets/** nega secrets/.env, *id_rsa* nega .id_rsa.

Variáveis de ambiente

Todas as variáveis booleanas aceitam true ou 1 para habilitar e false, 0, ou não definido para desabilitar; qualquer outro valor registra um aviso e é lido como desabilitado. Flags têm precedência quando ambas estão definidas.

Variável	Finalidade
`FS_ALLOWED_DIRS`	Lista de diretórios permitidos, separada por dois-pontos (POSIX) ou ponto e vírgula (Windows).
`FS_ROOT_BOUNDARY`	Prefixo de caminho sob o qual todas as raízes permitidas devem estar (espelha `--root-boundary`).
`FS_ALLOW_CWD_WALK`	Sobe a partir do diretório de trabalho atual para encontrar uma raiz de projeto (espelha `--walk-cwd`).
`FS_ALLOW_MISSING_ROOTS`	Inicia mesmo se os diretórios configurados não existirem (espelha `--allow-missing-roots`).
`FS_ALLOW_SENSITIVE`	Permite acesso a caminhos sensíveis do sistema (espelha `--allow-sensitive`).
`FS_DENYLIST`	Lista separada por vírgulas de caminhos ou padrões a bloquear (espelha `--deny`).
`FS_ALLOWLIST`	Padrões separados por vírgulas isentos da lista de bloqueio sensível integrada (espelha `--allow`). Nunca remove entradas de `FS_DENYLIST`/`--deny`.
`FS_MAX_FILE_SIZE`	Tamanho máximo de arquivo para leituras em bytes (espelha `--max-file-size`).
`FS_LOG_LEVEL`	Nível de log RFC 5424: `debug`, `info`, `notice`, `warn`/`warning`, `error`, `critical`, `alert` ou `emergency` (espelha `--log-level`).
`FS_PORT`	Inicia o transporte HTTP Streamable nesta porta; não definido = stdio (espelha `--port`).
`FS_HTTP_HOST`	Endereço de bind do servidor HTTP (espelha `--http-host`).
`FS_API_KEY`	Chave de API exigida em requisições HTTP (espelha `--api-key`).
`FS_TRUST_PROXY`	Configuração Express `trust proxy`: contagem de saltos ou expressão. Não definido = não confiar em `X-Forwarded-*`.
`FS_ALLOWED_HOSTS`	Valores de cabeçalho Host separados por vírgulas a aceitar (transporte HTTP).
`FS_ALLOWED_ORIGINS`	Nomes de host de origem separados por vírgulas autorizados a chamar `/mcp` a partir de um navegador. Substitui o padrão localhost, então também liste `localhost`, `127.0.0.1` ou `[::1]` se clientes de navegador locais ainda precisarem de acesso.
`FS_ALLOW_UNRESTRICTED_HOSTS`	Faz bind de um host curinga sem validação de Host (aceita o risco).
`FS_PUBLIC_URL`	URL de identificador de recurso para descoberta RFC 9728.
`FS_RATE_LIMIT_RPM`	Requisições/minuto por IP de cliente (padrão 120 com autenticação por chave de API, 6.000 para loopback sem chave; intervalo 1–100000).
`FS_MAX_WATCHERS`	Máximo de observadores de arquivo simultâneos (padrão 256, 1–4096).
`NO_COLOR`	Qualquer valor desativa a saída de cores ANSI.
`FS_REQUEST_STATE_KEY`	Chave HMAC que sela `input_required` requestState entre rodadas de repetição. Opcional (aleatória a cada inicialização se não definida); defina-a, com pelo menos 32 bytes UTF-8, para manter rodadas em andamento ativas após uma reinicialização.

Exemplos

# Allow current working directory
filesystem-mcp --allow-cwd

# HTTP transport on port 3000
filesystem-mcp --port 3000

Scripts

Modo	Comando	Descrição
Verificação completa	`npm run check`	Executa build, verificação de tipos, lint, formatação, knip e testes
Correção automática + verificação	`npm run fix`	Corrige automaticamente formatação/lint e executa a verificação completa
Somente estático	`npm run check:static`	Executa análise estática sem testes
Somente testes	`npm test`	Executa testes; aceita opções nativas do `node --test`

Segurança

[!IMPORTANT] Reporte vulnerabilidades de forma privada via GitHub Security Advisories. Não abra issues públicas para relatos de segurança.

Tópico	Detalhe
Path traversal	Todo caminho é resolvido e validado contra as raízes permitidas antes de qualquer operação
Arquivos sensíveis	`.env`, `.pem`, `id_rsa*` e padrões semelhantes são negados por padrão
Segurança de regex	RE2 não pode fazer backtracking, então um padrão hostil não pode travar o servidor (ReDoS)
Contêiner	Executa como usuário não-root `mcp`; mounts bind controlam o que é exposto

Contribuindo

Faça um fork do repositório.
Crie um branch de funcionalidade: git checkout -b feat/your-feature.
Faça commit das suas alterações com uma mensagem clara.
Execute npm run check para confirmar que testes, tipos, lint, formatação e knip passam.
Abra um pull request.

Política de Privacidade

filesystem-mcp é executado inteiramente na sua máquina. Esta política cobre o pacote npm, a imagem Docker e a extensão de desktop .mcpb.

Coleta de dados: nenhuma. O servidor não tem telemetria, análise ou relatórios de falhas, e não faz requisições de rede de saída.
Uso e armazenamento: arquivos são lidos e gravados apenas dentro dos diretórios que você permite, e somente quando seu cliente MCP chama uma ferramenta. Os resultados das ferramentas vão para esse cliente e para nenhum outro lugar. Caches de resultados de curta duração ficam em memória e desaparecem quando o servidor é encerrado.
Compartilhamento com terceiros: nenhum por este servidor. Seu cliente MCP pode enviar resultados de ferramentas ao provedor de modelo sob a política de privacidade do próprio cliente.
Retenção: nada é mantido após o processo ser encerrado. Logs de diagnóstico vão para stderr na sua máquina; seu cliente MCP pode salvá-los em seus próprios arquivos de log.
Contato: abra uma issue em https://github.com/j0hanz/filesystem-mcp/issues, ou reporte problemas de segurança de forma privada através de GitHub Security Advisories.

Licença

Lançado sob a Licença MIT. Consulte LICENSE para detalhes.