Remote File Server

Um servidor MCP que concede a qualquer cliente MCP acesso de leitura a servidores de compartilhamento de arquivos SMB/CIFS

GitHub

Experimente este MCPPatrocinado

Documentação

remote-file-server-mcp

Dê a qualquer assistente de IA acesso de leitura aos seus compartilhamentos de arquivos SMB/CIFS — com segurança, em minutos.

O que é isso?

Um servidor MCP (Model Context Protocol) que conecta o Claude Desktop (ou qualquer cliente MCP) ao seu compartilhamento de rede SMB/CIFS — servidores de arquivos Windows, unidades NAS, compartilhamentos Samba, qualquer coisa que use SMB.

Peça ao Claude para ler relatórios, pesquisar planilhas ou resumir documentos que estão na sua rede — sem mover um único arquivo, colar credenciais em um chat ou conceder acesso de escrita.

flowchart LR
    A("🤖 Claude Desktop\nor any MCP client"):::client
    B("🔌 file-server-mcp\n<i>this server</i>"):::server
    C("🗄️ SMB File Server\nWindows · NAS · Samba"):::storage

    A -- "MCP / stdio" --> B
    B -- "SMB 445 · encrypted" --> C

    classDef client  fill:#7c3aed,color:#fff,stroke:none
    classDef server  fill:#2563eb,color:#fff,stroke:none
    classDef storage fill:#0f766e,color:#fff,stroke:none

Recursos de relance


Somente leitura por design	O servidor expõe zero operações de escrita — seus arquivos estão seguros
Credenciais permanecem locais	Passadas como variáveis de ambiente, nunca aparecem em chamadas de ferramentas ou no histórico do chat
Criptografia e assinatura SMB	Assinatura de pacotes e criptografia estão ambas ativadas por padrão; defina `SMB_ENCRYPT=false` para desativar apenas a criptografia
Bloqueio de traversal de caminho	Segmentos `..` são rejeitados antes de qualquer chamada SMB ser feita
Lista de bloqueio de arquivos sensíveis	`.env`, `.key`, `.pem`, `id_rsa`, keystores e outros nunca são listados ou lidos
Log de auditoria	Cada chamada de ferramenta é gravada como uma entrada JSON (operação, caminho, resultado e metadados específicos da ferramenta) — nunca o conteúdo dos arquivos
Parsing de Office e PDF	Arquivos Excel, Word, PowerPoint e PDF são convertidos em texto legível — requer os extras opcionais `[docs]`
Lista de permissão de subdiretórios	Bloqueie o servidor apenas nos diretórios que o modelo realmente precisa

Ferramentas

Ferramenta	Argumentos	Descrição
`list_files`	`path` (opcional)	Lista arquivos e diretórios. Caminho vazio = raiz do compartilhamento. Retorna JSON.
`read_file`	`path`	Retorna conteúdo de texto. Arquivos muito grandes retornam uma prévia ou erro grave. Arquivos Office/PDF são convertidos.
`get_file_info`	`path`	Retorna metadados (tamanho, tipo, timestamps) sem ler o arquivo.
`search_files`	`pattern`, `path` (opcional), `max_depth` (opcional)	Busca glob (ex.: `*.csv`). Recursivo até `max_depth` (padrão `5`, máximo `10`), retorna até 200 correspondências.

Todos os caminhos são relativos à raiz do compartilhamento — ex.: reports/2024/q1.xlsx.

Início rápido

Opção A — instalação via pip

pip install -e /path/to/remote-file-server

Em seguida, use "command": "file-server-mcp" na configuração do seu cliente MCP.

Opção B — uv (sem instalação)

uv run --directory /path/to/remote-file-server file-server-mcp

Opção C — executar a partir do código-fonte

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python server.py

Opção D — Docker

docker build -t file-server-mcp .

Consulte Dockerfile para uso em tempo de execução.

Configuração do Cliente MCP

Adicione uma entrada em mcpServers no arquivo de configuração do seu cliente.

uv (executar a partir do código-fonte, sem instalação prévia):

{
  "mcpServers": {
    "file-server": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/remote-file-server", "file-server-mcp"],
      "env": {
        "SMB_HOST": "192.168.1.100",
        "SMB_SHARE": "my_share",
        "SMB_USERNAME": "my_user",
        "SMB_PASSWORD": "my_password"
      }
    }
  }
}

pip/uv pip (ponto de entrada de script de console):

{
  "mcpServers": {
    "file-server": {
      "command": "file-server-mcp",
      "env": {
        "SMB_HOST": "192.168.1.100",
        "SMB_SHARE": "my_share",
        "SMB_USERNAME": "my_user",
        "SMB_PASSWORD": "my_password",
        "SMB_PORT": "445",
        "ALLOWED_PATHS": "reports,finance",
        "AUDIT_LOG_PATH": "/var/log/file-server-mcp/audit.jsonl"
      }
    }
  }
}

Nota de segurança: Este arquivo de configuração contém credenciais — restrinja suas permissões (chmod 600 no macOS/Linux).

Reinicie seu cliente MCP após salvar.

Conectando a vários servidores

{
  "mcpServers": {
    "file-server-prod": {
      "command": "file-server-mcp",
      "env": { "SMB_HOST": "10.0.0.10", "SMB_SHARE": "Production", "...": "..." }
    },
    "file-server-dev": {
      "command": "file-server-mcp",
      "env": { "SMB_HOST": "10.0.0.20", "SMB_SHARE": "Development", "...": "..." }
    }
  }
}

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`SMB_HOST`	Sim	—	Endereço IP ou nome de host do servidor SMB
`SMB_SHARE`	Sim	—	Nome do compartilhamento no servidor
`SMB_USERNAME`	Sim	—	Nome de usuário para autenticação SMB
`SMB_PASSWORD`	Sim	—	Senha para autenticação SMB
`SMB_PORT`	Não	`445`	Porta SMB
`SMB_ENCRYPT`	Não	`true`	Defina como `false` para desativar a criptografia SMB (não recomendado)
`SMB_TIMEOUT`	Não	`30`	Segundos antes de uma conexão ou operação SMB expirar
`MAX_FILE_SIZE_MB`	Não	`10`	Tamanho máximo de arquivo em MB que `read_file` lerá
`READ_PREVIEW_LINES`	Não	`100`	Linhas a retornar para arquivos muito grandes. Defina como `0` para gerar erro grave
`ALLOWED_PATHS`	Não	—	Lista de permissão de subdiretórios separada por vírgulas, ex.: `reports,finance/2024`
`AUDIT_LOG_PATH`	Não	stderr	Caminho do arquivo para logs de auditoria JSON. Usa stderr se não definido

Segurança

Assinatura de pacotes SMB é obrigatória em todas as conexões.
Traversal de caminho é bloqueado — segmentos .. são rejeitados antes de qualquer chamada SMB.
Lista de bloqueio de arquivos sensíveis cobre .env, *.key, *.pem, *.bak, id_rsa, *.pfx, *.p12, *.token, .netrc, .htpasswd, arquivos keystore e mais. Para produção, combine isso com ALLOWED_PATHS para restringir o acesso apenas aos diretórios que o modelo precisa.
Limite de tamanho de arquivo impede a leitura de arquivos que estourariam a janela de contexto.
Log de auditoria registra cada chamada de ferramenta em JSON (operação, caminho, resultado, metadados específicos da ferramenta) — nunca o conteúdo dos arquivos.
Mensagens de erro são sanitizadas — nomes de host internos, caminhos UNC e credenciais nunca são expostos ao cliente.

Requisitos

Python 3.11+
Acesso de rede ao servidor SMB (porta 445 por padrão)
Credenciais SMB com permissões de leitura no compartilhamento