Filesystem

Operações seguras de arquivos com controles de acesso configuráveis

GitHub
90.5k

Documentação

Servidor MCP Filesystem

Servidor Node.js que implementa o Model Context Protocol (MCP) para operações de sistema de arquivos.

Publicado no npm como @modelcontextprotocol/server-filesystem.

Recursos

  • Ler/gravar arquivos
  • Criar/listar/excluir diretórios
  • Mover arquivos/diretórios
  • Pesquisar arquivos
  • Obter metadados de arquivos
  • Controle dinâmico de acesso a diretórios via Roots

Controle de Acesso a Diretórios

O servidor usa um sistema flexível de controle de acesso a diretórios. Os diretórios podem ser especificados via argumentos de linha de comando ou dinamicamente via Roots.

Método 1: Argumentos de Linha de Comando

Especifique os diretórios permitidos ao iniciar o servidor:

mcp-server-filesystem /path/to/dir1 /path/to/dir2

Método 2: MCP Roots (Recomendado)

Clientes MCP que suportam Roots podem atualizar dinamicamente os diretórios permitidos.

Roots notificados pelo Cliente ao Servidor substituem completamente quaisquer diretórios permitidos no lado do servidor quando fornecidos.

Importante: Se o servidor iniciar sem argumentos de linha de comando E o cliente não suportar o protocolo roots (ou fornecer roots vazios), o servidor lançará um erro durante a inicialização.

Este é o método recomendado, pois permite atualizações de diretórios em tempo de execução via notificações roots/list_changed sem reiniciar o servidor, proporcionando uma experiência de integração mais flexível e moderna.

Como Funciona

O controle de acesso a diretórios do servidor segue este fluxo:

  1. Inicialização do Servidor

    • O servidor inicia com diretórios dos argumentos de linha de comando (se fornecidos)
    • Se nenhum argumento for fornecido, o servidor inicia com diretórios permitidos vazios

  2. Conexão e Inicialização do Cliente

    • O cliente se conecta e envia a solicitação initialize com capacidades
    • O servidor verifica se o cliente suporta o protocolo roots (capabilities.roots)

  3. Tratamento do Protocolo Roots (se o cliente suportar roots)

    • Na inicialização: O servidor solicita roots ao cliente via roots/list
    • O cliente responde com seus roots configurados
    • O servidor substitui TODOS os diretórios permitidos pelos roots do cliente
    • Em atualizações em tempo de execução: O cliente pode enviar notifications/roots/list_changed
    • O servidor solicita roots atualizados e substitui novamente os diretórios permitidos

  4. Comportamento de Fallback (se o cliente não suportar roots)

    • O servidor continua usando apenas os diretórios da linha de comando
    • Nenhuma atualização dinâmica possível

  5. Controle de Acesso

    • Todas as operações do sistema de arquivos são restritas aos diretórios permitidos
    • Use a ferramenta list_allowed_directories para ver os diretórios atuais
    • O servidor exige pelo menos UM diretório permitido para operar

Nota: O servidor só permitirá operações dentro de diretórios especificados via args ou via Roots.

API

Ferramentas

  • read_text_file

    • Lê o conteúdo completo de um arquivo como texto
    • Entradas:
      • path (string)
      • head (number, opcional): Primeiras N linhas
      • tail (number, opcional): Últimas N linhas
    • Sempre trata o arquivo como texto UTF-8, independentemente da extensão
    • Não é possível especificar head e tail simultaneamente

  • read_media_file

    • Lê um arquivo e o retorna como um bloco de conteúdo codificado em base64 com seu tipo MIME
    • Entradas:
      • path (string)
    • Transmite o arquivo e retorna dados base64 com o tipo MIME correspondente. Arquivos de imagem e áudio são retornados como conteúdo image/audio; qualquer outro tipo de arquivo é retornado como um resource incorporado (um bloco de conteúdo MCP válido para dados binários arbitrários)

  • read_multiple_files

    • Lê vários arquivos simultaneamente
    • Entrada: paths (string[])
    • Falhas de leitura não interrompem toda a operação

  • write_file

    • Cria um novo arquivo ou sobrescreve um existente (tenha cuidado com isso)
    • Entradas:
      • path (string): Localização do arquivo
      • content (string): Conteúdo do arquivo

  • edit_file

    • Faz edições seletivas usando correspondência avançada de padrões e formatação
    • Recursos:
      • Correspondência de conteúdo por linha e multilinha
      • Normalização de espaços em branco com preservação de indentação
      • Múltiplas edições simultâneas com posicionamento correto
      • Detecção e preservação do estilo de indentação
      • Saída de diff no estilo Git com contexto
      • Pré-visualização de alterações com modo de execução simulada (dry run)
    • Entradas:
      • path (string): Arquivo para editar
      • edits (array): Lista de operações de edição
        • oldText (string): Texto a ser pesquisado (pode ser substring)
        • newText (string): Texto para substituir
      • dryRun (boolean): Pré-visualizar alterações sem aplicar (padrão: false)
    • Retorna informações detalhadas de diff e correspondência para execuções simuladas; caso contrário, aplica as alterações
    • Melhor prática: sempre use dryRun primeiro para pré-visualizar as alterações antes de aplicá-las

  • create_directory

    • Cria um novo diretório ou garante que ele exista
    • Entrada: path (string)
    • Cria diretórios pai se necessário
    • Conclui silenciosamente se o diretório existir

  • list_directory

    • Lista o conteúdo do diretório com prefixos [FILE] ou [DIR]
    • Entrada: path (string)

  • list_directory_with_sizes

    • Lista o conteúdo do diretório com prefixos [FILE] ou [DIR], incluindo tamanhos de arquivo
    • Entradas:
      • path (string): Caminho do diretório para listar
      • sortBy (string, opcional): Ordenar entradas por "name" ou "size" (padrão: "name")
    • Retorna listagem detalhada com tamanhos de arquivo e estatísticas resumidas
    • Mostra total de arquivos, diretórios e tamanho combinado

  • move_file

    • Move ou renomeia arquivos e diretórios
    • Entradas:
      • source (string)
      • destination (string)
    • Falha se o destino existir

  • search_files

    • Pesquisa recursivamente arquivos/diretórios que correspondem ou não correspondem a padrões
    • Entradas:
      • path (string): Diretório inicial
      • pattern (string): Padrão de pesquisa
      • excludePatterns (string[]): Excluir quaisquer padrões.
    • Correspondência de padrões no estilo Glob
    • Retorna caminhos completos para as correspondências

  • directory_tree

    • Obtém estrutura de árvore JSON recursiva do conteúdo do diretório
    • Entradas:
      • path (string): Diretório inicial
      • excludePatterns (string[]): Excluir quaisquer padrões. Formatos Glob são suportados.
    • Retorna:
      • Array JSON onde cada entrada contém:
        • name (string): Nome do arquivo/diretório
        • type ('file'|'directory'): Tipo de entrada
        • children (array): Presente apenas para diretórios
          • Array vazio para diretórios vazios
          • Omitido para arquivos
    • A saída é formatada com indentação de 2 espaços para legibilidade

  • get_file_info

    • Obtém metadados detalhados de arquivo/diretório
    • Entrada: path (string)
    • Retorna:
      • Tamanho
      • Data de criação
      • Data de modificação
      • Data de acesso
      • Tipo (arquivo/diretório)
      • Permissões

  • list_allowed_directories

    • Lista todos os diretórios que o servidor tem permissão para acessar
    • Nenhuma entrada necessária
    • Retorna:
      • Diretórios dos quais este servidor pode ler/gravar

Anotações de ferramentas (dicas MCP)

Este servidor define MCP ToolAnnotations em cada ferramenta para que os clientes possam:

  • Distinguir ferramentas somente leitura de ferramentas com capacidade de gravação.
  • Entender quais operações de gravação são idempotentes (seguras para repetir com os mesmos argumentos).
  • Destacar operações que podem ser destrutivas (sobrescrever ou mutar dados intensamente).
  • Sinalizar que uma ferramenta não alcança um mundo aberto ou externo (cada ferramenta do sistema de arquivos define openWorldHint: false).

O mapeamento para ferramentas do sistema de arquivos é:

FerramentareadOnlyHintidempotentHintdestructiveHintNotas
read_text_filetrue––Leitura pura
read_media_filetrue––Leitura pura
read_multiple_filestrue––Leitura pura
list_directorytrue––Leitura pura
list_directory_with_sizestrue––Leitura pura
directory_treetrue––Leitura pura
search_filestrue––Leitura pura
get_file_infotrue––Leitura pura
list_allowed_directoriestrue––Leitura pura
create_directoryfalsetruefalseRecriar o mesmo diretório é uma operação sem efeito
write_filefalsetruetrueSobrescreve arquivos existentes
edit_filefalsefalsetrueReaplicar edições pode falhar ou aplicar em dobro
move_filefalsefalsetrueExclui o arquivo de origem

Nota: idempotentHint e destructiveHint são significativos apenas quando readOnlyHint é false, conforme definido pela especificação MCP. Cada ferramenta também define openWorldHint: false — este servidor acessa apenas o sistema de arquivos local dentro de seus diretórios permitidos, nunca um mundo aberto ou externo.

Uso com Claude Desktop

Adicione isto ao seu claude_desktop_config.json:

Nota: você pode fornecer diretórios em sandbox ao servidor montando-os em /projects. Adicionar a flag ro tornará o diretório somente leitura para o servidor.

Docker

Nota: todos os diretórios devem ser montados em /projects por padrão.

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

No Windows, use cmd /c para iniciar npx:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Uso com VS Code

Para instalação rápida, clique nos botões de instalação abaixo...

Install with NPX in VS Code Install with NPX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

Para instalação manual, você pode configurar o servidor MCP usando um destes métodos:

Método 1: Configuração do Usuário (Recomendado) Adicione a configuração ao seu arquivo de configuração MCP de nível de usuário. Abra a Paleta de Comandos (Ctrl + Shift + P) e execute MCP: Open User Configuration. Isso abrirá seu arquivo mcp.json de usuário onde você pode adicionar a configuração do servidor.

Método 2: Configuração do Workspace Alternativamente, você pode adicionar a configuração a um arquivo chamado .vscode/mcp.json no seu workspace. Isso permitirá que você compartilhe a configuração com outras pessoas.

Para mais detalhes sobre a configuração MCP no VS Code, consulte a documentação oficial do MCP do VS Code.

Você pode fornecer diretórios em sandbox ao servidor montando-os em /projects. Adicionar a flag ro tornará o diretório somente leitura para o servidor.

Docker

Nota: todos os diretórios devem ser montados em /projects por padrão.

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

No Windows, use:

{
  "servers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Build

Build Docker:

docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

Licença

Este servidor MCP é licenciado sob a Licença MIT. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.