Filesystem MCP Server

Filesystem MCP Server

Um servidor MCP de binário único e seguro para operações de sistema de arquivos. Sem dependências de runtime — baixe, configure os diretórios permitidos e conecte-se a qualquer cliente MCP.

Testado extensivamente com Claude Desktop e Claude Code em fluxos de trabalho reais de codificação, incluindo edição de arquivos, busca em código-base, refatoração e operações em lote com múltiplos arquivos.

Por que este servidor?

• Binário único — sem necessidade de Node.js, Python ou outro runtime. Baixe e execute
• Testado com fluxos reais de IA — testado em batalha com Claude Desktop e Claude Code para tarefas de codificação do dia a dia
• 18 ferramentas — vai além de leitura/escrita básica com busca por regex, substituição baseada em padrões, inserção de código com indentação automática e operações em lote
• Pré-visualização dry-run — pré-visualize alterações antes de aplicá-las nas ferramentas de substituição e inserção
• Seguro por padrão — isolado nos diretórios configurados com prevenção de ataques por symlink e proteção contra travessia de caminho
• Mensagens de erro detalhadas — quando o acesso é negado, os erros explicam o motivo e sugerem correções

Instalação

Baixar um binário de versão

Baixe o binário mais recente para sua plataforma na página Releases:

Plataforma	Binário
macOS (Apple Silicon)	filesystem-mcp-darwin-arm64
macOS (Intel)	filesystem-mcp-darwin-amd64
Linux (x86_64)	filesystem-mcp-linux-amd64
Linux (ARM64)	filesystem-mcp-linux-arm64
Windows	filesystem-mcp-windows-amd64.exe

Torne-o executável (macOS/Linux):

chmod +x filesystem-mcp-darwin-arm64

Compilar a partir do código-fonte

go build -ldflags="-s -w" -o bin/filesystem-mcp ./cmd

Configuração

Defina os diretórios permitidos usando a variável de ambiente:

export MCP_ALLOWED_DIRS="/path1,/path2,/path with spaces/dir3"

Ferramentas

Leitura

• read_file — Lê um único arquivo, com start_line/end_line opcionais para leituras parciais
• read_multiple_files — Lê vários arquivos simultaneamente em uma única chamada
• search_in_files — Busca recursiva por regex nos arquivos. Retorna caminhos de arquivo, números de linha e texto correspondente. Ignora arquivos binários automaticamente. Parâmetros: path, pattern, file_extensions, max_results, case_sensitive

Escrita

• write_file — Cria ou sobrescreve um arquivo. Cria diretórios pais automaticamente
• append_to_file — Adiciona conteúdo ao final do arquivo. Cria o arquivo se não existir
• prepend_to_file — Adiciona conteúdo ao início do arquivo. Cria o arquivo se não existir

Substituição de Texto

Todas as ferramentas de substituição suportam dry_run para pré-visualizar alterações sem aplicá-las.

• replace_in_file — Substitui ocorrências exatas de uma string em um arquivo. Parâmetros: path, search, replace, occurrence (0=todas), dry_run
• replace_in_file_regex — Substitui correspondências de padrão regex com suporte a grupos de captura ($1, $2). Parâmetros: path, pattern, replace, occurrence, case_sensitive, dry_run
• replace_in_files — Substitui em lote uma string em vários arquivos. Valida todos os caminhos antes de aplicar. Parâmetros: paths, search, replace, dry_run

Inserção Baseada em Regex

Todas as ferramentas de inserção suportam dry_run e autoIndent (corresponder indentação ao redor).

• insert_after_regex — Insere conteúdo após uma correspondência de padrão regex. Parâmetros: path, pattern, content, occurrence (0=todas, padrão 1), autoIndent, dry_run
• insert_before_regex — Insere conteúdo antes de uma correspondência de padrão regex. Mesmos parâmetros acima

Cópia de Linhas

• copy_lines — Copia um intervalo de linhas do arquivo de origem para o de destino diretamente no disco (sem sobrecarga de contexto). Parâmetros: source_path, destination_path, start_line, end_line, append

Operações de Diretório

• list_directory — Lista o conteúdo do diretório com filtragem por padrão, tipo de arquivo, profundidade de recursão, arquivos ocultos e metadados. Parâmetros: path, pattern, file_type, recursive, max_depth, max_results, include_hidden, include_metadata
• create_directory — Cria diretório e pais (idempotente)
• list_allowed_directories — Mostra diretórios acessíveis

Gerenciamento de Arquivos

• move_file — Move ou renomeia arquivos e diretórios
• get_file_info — Obtém metadados do arquivo (tamanho, permissões, hora da modificação)

Uso com Claude Desktop

Adicione em claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/filesystem-mcp-darwin-arm64",
      "env": {
        "MCP_ALLOWED_DIRS": "/path1,/path2,/path with spaces/dir3"
      }
    }
  }
}

Segurança

O servidor implementa segurança em profundidade para impedir acesso não autorizado a arquivos.

Validação de Caminho

• Resolução de links simbólicos: todos os caminhos são resolvidos para a forma canônica via filepath.EvalSymlinks() antes da validação
• Prevenção de travessia de caminho: bloqueia tentativas de escape por ../
• Proteção de correspondência por prefixo: valida com separadores de caminho para impedir que /allowed corresponda a /allowed_attacker

Tratamento de Links Simbólicos

• Links simbólicos dentro dos diretórios permitidos são aceitos se seu destino também estiver dentro dos diretórios permitidos
• Links simbólicos apontando para fora dos diretórios permitidos são bloqueados
• Links simbólicos quebrados são rejeitados
• Os próprios diretórios permitidos podem ser links simbólicos (resolvidos durante a inicialização)

Segurança de Operações de Escrita

• A cadeia de diretórios pais é validada para criação de novos arquivos
• A resolução e a validação de caminho ocorrem atomicamente

Registro de Segurança

• Todas as tentativas de acesso bloqueadas são registradas com o prefixo SECURITY:
• Os registros incluem tanto o caminho solicitado quanto sua resolução canônica

Melhores Práticas

• Configure MCP_ALLOWED_DIRS com os diretórios mínimos necessários
• Use caminhos absolutos para diretórios permitidos
• Monitore os registros para mensagens de SECURITY:

Licença

Licença MIT