sftp-mcp

Servidor MCP para acessar, pelo Claude Code, os servidores SFTP dos clientes. A leitura é livre. Toda escrita pede a sua aprovação, inclusive com --dangerously-skip-permissions.

O que ele faz

Não existe tool de apagar.

Related MCP server: claude-ssh-mcp

Travas

• Aprovação em toda escrita. As tools de escrita declaram _meta["anthropic/requiresUserInteraction"]: true, e o Claude Code mostra o prompt de permissão em toda chamada, sem "não perguntar de novo", em qualquer modo de permissão. Como segunda camada, cadastre as mesmas tools em permissions.ask (veja Instalação).

• Raízes de escrita. Cada perfil declara raizes_escrita. Sem raiz, o perfil não escreve. O caminho é resolvido pelo servidor (realpath) antes da checagem, então .. e symlink não saem da raiz. Escrever sobre um symlink é recusado.

• Host key fixada. A chave pública do servidor é gravada no cadastro, depois que você confere o fingerprint. Se o servidor apresentar outra, a conexão é recusada. O ~/.ssh/known_hosts, o ~/.ssh/config e o agente SSH não são usados.

• Segredo fora do modelo. Senha e passphrase ficam no keyring do sistema (Credential Manager no Windows) e nunca são parâmetro de tool.

• Tudo auditado. Cada operação gera uma linha JSON em audit.log, sem conteúdo de arquivo e sem segredo.

Pasta local do cliente

Cada perfil aponta para o repositório git do cliente na sua máquina. Downloads, backups e auditoria ficam em:

<repositório>/.claude/sftp/<perfil>/
├── downloads/   espelha o caminho remoto
├── backups/     <data-hora>/<caminho remoto>, versão anterior de cada arquivo sobrescrito
└── audit.log

A pasta .claude/ não pode entrar no git do cliente. Ao vincular, o servidor roda git check-ignore e avisa se ela não estiver ignorada.

Se o perfil não tiver repositório, as tools falham pedindo que o agente pergunte a pasta a você e chame sftp_vincular_repositorio.

Instalação

Requer Python 3.11 ou superior.

git clone https://github.com/guipegoraro/sftp-mcp
cd sftp-mcp
pip install -e .

Registre no Claude Code (escopo de usuário):

claude mcp add -s user sftp -- python -m sftp_mcp

Em ~/.claude/settings.json, acrescente a segunda camada de aprovação:

{
  "permissions": {
    "ask": [
      "mcp__sftp__sftp_enviar",
      "mcp__sftp__sftp_criar_pasta",
      "mcp__sftp__sftp_renomear",
      "mcp__sftp__sftp_vincular_repositorio"
    ]
  }
}

Cadastro de perfis

sftp-mcp-setup adicionar cliente-prod     # pergunta os dados, mostra o fingerprint e grava a senha
sftp-mcp-setup listar
sftp-mcp-setup testar cliente-prod
sftp-mcp-setup definir-senha cliente-prod
sftp-mcp-setup trocar-fingerprint cliente-prod
sftp-mcp-setup vincular-repositorio cliente-prod C:\caminho\do\repo
sftp-mcp-setup remover cliente-prod

Os perfis ficam em ~/.sftp-mcp/perfis.toml (ou na pasta de SFTP_MCP_HOME). Dá para editar à mão:

[perfis.cliente-prod]
host = "sftp.cliente.com.br"
porta = 22
usuario = "totvs"
host_key = "ssh-ed25519 AAAA..."
autenticacao = "senha"          # ou "chave", com chave_privada = "C:\\caminho\\id_ed25519"
chave_privada = ""
ambiente = "prod"               # prod, hml ou dev
tspace_cliente = ""
repositorio = "C:\\caminho\\do\\repo"
raizes_leitura = []             # vazio = servidor inteiro
raizes_escrita = ["/totvs/protheus/apo", "/totvs/protheus/bin/appserver"]
timeout_conexao = 15
ocioso_max_segundos = 300
max_leitura_bytes = 1048576
busca_profundidade = 5
busca_max_resultados = 2000

Chave privada no formato PuTTY (.ppk) não é aceita. No PuTTYgen: Load, depois Conversions > Export OpenSSH key.

Testes

pip install -e .[teste]
python -m pytest

Os testes sobem um servidor SFTP do asyncssh no próprio processo e usam um keyring em memória. Eles não acessam servidor real.

Limites conhecidos

• Só SFTP. FTP e FTPS não são suportados.

• Sem jump host. VPN fica por sua conta.

• Quem roda código como o seu usuário do Windows lê o Credential Manager. Veja SECURITY.md.