Secure MCP Filesystem Server

Um servidor MCP seguro para acessar o sistema de arquivos local dentro de diretórios predefinidos.

Documentação

Secure MCP Filesystem Server

Um servidor seguro do Model Context Protocol (MCP) que fornece acesso ao sistema de arquivos dentro de diretórios predefinidos

:bookmark: Sobre

MCP Filesystem Server fornece acesso seguro ao sistema de arquivos para modelos de IA através do Model Context Protocol. Ele aplica validação rigorosa de caminhos e só permite acesso a diretórios predefinidos.

:computer: Tecnologias

TypeScript
Node.js
MCP SDK
Zod
Docker
pnpm

:wrench: Ferramentas

:package: Instalação

:heavy_check_mark: Pré-requisitos

O seguinte software deve estar instalado:

Node.js (>=18.0.0)
Git
pnpm (>=8.0.0)
Docker (opcional)
Docker Compose (opcional)

:arrow_down: Clonando o repositório

  $ git clone https://github.com/gabrielmaialva33/mcp-filesystem.git
  $ cd mcp-filesystem

:arrow_forward: Executando a aplicação

Desenvolvimento Local

  # Install dependencies
  $ pnpm install

  # Build the application
  $ pnpm build

  # Run the server (specify directory to allow access to)
  $ pnpm start /path/to/allowed/directory

  # Or use configuration file
  $ pnpm start --config=config.json

Usando Pacote NPM

  # Install globally
  $ npm install -g @gabrielmaialva33/mcp-filesystem

  # Run the server
  $ mcp-filesystem /path/to/allowed/directory

  # Or use with npx (no installation needed)
  $ npx @gabrielmaialva33/mcp-filesystem /path/to/allowed/directory

  # Create a sample configuration file
  $ npx @gabrielmaialva33/mcp-filesystem --create-config=config.json

Usando Docker

  # Build the Docker image
  $ docker build -t gabrielmaialva33/mcp-filesystem .

  # Run using Docker
  $ docker run -i --rm -v /path/to/data:/data:ro gabrielmaialva33/mcp-filesystem /data

  # Use with config file
  $ docker run -i --rm -v /path/to/config.json:/app/config.json -v /path/to/data:/data gabrielmaialva33/mcp-filesystem --config=/app/config.json

Usando Docker Compose

  # Create a data directory
  $ mkdir -p data

  # Start the server
  $ docker-compose up -d

:gear: Uso

Usando com Claude Desktop

O Claude Desktop pode ser configurado para usar este servidor MCP para acesso ao sistema de arquivos. Adicione o seguinte ao seu claude_desktop_config.json:

Usando Instalação Local (Recomendado)

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem",
      "args": [
        "/Users/gabrielmaia/Documents",
        "/Users/gabrielmaia/Desktop",
        "/Users/gabrielmaia/Downloads"
      ]
    }
  }
}

Certifique-se de disponibilizar o executável globalmente:

# Make the binary executable
chmod +x /Users/gabrielmaia/.nvm/versions/node/v22.14.0/bin/mcp-filesystem

Usando NPX

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

Usando Docker

Nota: Ao usar Docker, todos os diretórios devem ser montados em /projects por padrão. Adicionar a flag ro tornará o diretório somente leitura.

{
  "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",
        "gabrielmaialva33/mcp-filesystem",
        "/projects"
      ]
    }
  }
}

Ferramentas Disponíveis

O MCP Filesystem Server fornece estas ferramentas:

Operações de Sistema de Arquivos

read_file: Ler o conteúdo de um arquivo
read_multiple_files: Ler vários arquivos de uma vez
write_file: Criar ou sobrescrever um arquivo
edit_file: Fazer edições precisas com pré-visualização de diff
create_directory: Criar diretórios recursivamente
list_directory: Listar o conteúdo de um diretório
directory_tree: Obter uma visão em árvore recursiva
move_file: Mover ou renomear arquivos
search_files: Encontrar arquivos que correspondam a padrões
get_file_info: Obter metadados de arquivo
list_allowed_directories: Ver diretórios acessíveis

Operações de Sistema e Rede

get_metrics: Ver métricas de desempenho do servidor (v0.3.0+)
execute_command: Executar comandos do sistema com segurança (v0.3.1+)
curl_request: Executar requisições HTTP para APIs externas (disponível na v1.2.0)

Usando a Ferramenta curl_request (Disponível na v1.2.0)

A ferramenta curl_request permitirá que você faça requisições HTTP para APIs externas:

// Example: Making a GET request with authentication
curl_request({
  url: 'https://api.example.com/data',
  method: 'GET',
  headers: {
    Authorization: 'Bearer your_token_here',
  },
})

// Example: POST request with JSON data
curl_request({
  url: 'https://api.example.com/create',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  data: '{"name":"Example","value":123}',
})

Consulte o arquivo docs/curl-tool-examples.md para exemplos mais detalhados.

:sparkles: Recursos

Recursos Principais

Acesso Seguro: Validação rigorosa de caminhos impede acesso não autorizado
Operações de Arquivo: Ler, escrever, editar e mover arquivos
Operações de Diretório: Criar, listar, obter visões em árvore e pesquisar diretórios
Acesso a Metadados: Visualizar informações de arquivos e diretórios
Execução de Comandos: Executar comandos do sistema com segurança e validação rigorosa
Suporte a Docker: Implantação fácil com Docker e Docker Compose

Novos Recursos na v0.3.0

Registro Estruturado: Registro detalhado com diferentes níveis (debug, info, warn, error)
Métricas de Desempenho: Rastrear contagens de operações, erros e tempos de execução
Gerenciamento de Configuração: Suporte para arquivos de configuração JSON
Cache de Caminhos: Desempenho melhorado para caminhos acessados com frequência
Tratamento de Erros Aprimorado: Tipos de erro especializados com informações estruturadas
Validação de Tamanho de Arquivo: Evitar carregamento de arquivos excessivamente grandes
Melhorias na CLI: Comando de ajuda, informações de versão e geração de configuração

Opções de Configuração

Você pode criar um arquivo de configuração usando:

$ mcp-filesystem --create-config=config.json

Exemplo de configuração:

{
  "allowedDirectories": ["/path/to/allowed/dir1", "/path/to/allowed/dir2"],
  "logLevel": "info",
  "logFile": "/path/to/logs/mcp-filesystem.log",
  "serverName": "secure-filesystem-server",
  "serverVersion": "0.3.0",
  "cache": {
    "enabled": true,
    "maxSize": 1000,
    "ttlMs": 60000
  },
  "metrics": {
    "enabled": true,
    "reportIntervalMs": 60000
  },
  "security": {
    "maxFileSize": 10485760,
    "allowSymlinks": true,
    "validateRealPath": true
  }
}

:writing_hand: Autor


Gabriel Maia

Licença

Licença MIT