SSH MCP Server

@nl4ever/sshmcp

Documentação em Chinês

Deixe a IA gerenciar seus servidores remotos. Um servidor Model Context Protocol (MCP) que dá aos assistentes de IA acesso SSH completo — execute comandos, transfira arquivos, gerencie múltiplos servidores simultaneamente, tudo por meio de conversa natural.

You:   "Deploy the latest build to production server"
AI:    connects → uploads build → restarts service → verifies status

Recursos

• 21 Ferramentas — Conecte, execute, envie, baixe, escreva arquivos e muito mais
• Pool de Conexões — Opere múltiplos servidores simultaneamente, cada comando marcado com server_id
• Transferência de Arquivos com Zero Token — Transferência baseada em caminho SFTP, o conteúdo do arquivo nunca entra no contexto da IA
• Upload de Diretório — Compressão automática tar.gz → upload → descompressão remota (rápido para muitos arquivos pequenos)
• Transferência Assíncrona + Progresso — Transferência em segundo plano para arquivos grandes com acompanhamento de progresso em tempo real
• Conexão Rápida — Conexões temporárias sem salvar configuração, retorna host:port como ID temporário
• Proxy SOCKS4/5 — Suporte a proxy por conexão
• Host de Salto — SSH ProxyJump para acesso a bastion/gateway
• Multi-Autenticação — Senha, chave privada, ssh-agent, keyboard-interactive (OTP/2FA)

Início Rápido

Instalar globalmente

npm install -g @nl4ever/sshmcp

Adicionar ao Claude Code

claude mcp add sshmcp sshmcp

Adicionar ao Claude Desktop

Edite claude_desktop_config.json:

{
  "mcpServers": {
    "sshmcp": {
      "command": "npx",
      "args": ["-y", "@nl4ever/sshmcp"]
    }
  }
}

Adicionar ao Cursor

Vá para Configurações → Servidores MCP → Adicionar:

{
  "sshmcp": {
    "command": "npx",
    "args": ["-y", "@nl4ever/sshmcp"]
  }
}

Visão Geral das Ferramentas

Gerenciamento de Conexões

Ferramenta	Descrição
list_servers	Lista todos os servidores configurados e conexões ativas
get_server	Exibe detalhes da configuração do servidor
add_server	Adiciona/atualiza configuração do servidor (senha, chave, agente, OTP)
update_server	Modifica configuração do servidor (passe apenas os campos que deseja alterar)
delete_server	Remove um servidor
rename_server	Renomeia um ID de servidor
connect	Conecta manualmente (geralmente não necessário, as ferramentas conectam automaticamente)
quick_connect	Conexão temporária, retorna host:port como ID
disconnect	Desconecta um servidor específico ou todas as conexões
test_connection	Testa a conectividade sem afetar conexões existentes

Execução de Comandos

Ferramenta	Descrição
execute	Executa comandos shell no servidor remoto (com timeout configurável)

Operações de Arquivo

Ferramenta	Descrição
read_file	Lê o conteúdo de arquivo remoto (com intervalo de linhas opcional)
write_file	Escreve conteúdo de texto em arquivo remoto
upload_file	Envia arquivo local para remoto (suporta modo assíncrono)
upload_directory	Envia diretório com compressão automática → transferência → descompressão
download_file	Baixa arquivo remoto para local (suporta modo assíncrono)
download_directory	Baixa diretório com compressão remota → transferência → descompressão local
transfer_status	Verifica o progresso de transferências assíncronas (tamanho/velocidade/ETA)

Gerenciamento de Proxy

Ferramenta	Descrição
list_proxies	Lista todos os presets de proxy SOCKS
add_proxy	Adiciona preset de proxy SOCKS4/5
delete_proxy	Remove um preset de proxy

Pool de Conexões: Operações Multi-Servidor

Todas as ferramentas de operação aceitam um parâmetro server_id. O pool de conexões gerencia as conexões automaticamente — sem necessidade de conectar/desconectar manualmente:

AI: execute(server_id="prod", command="nginx -s reload")         ← auto-connects to prod
AI: execute(server_id="dev", command="tail -f /var/log/app.log") ← auto-connects to dev, prod stays
AI: execute(server_id="prod", command="curl localhost")           ← reuses prod connection

Para servidores temporários, use quick_connect que retorna host:port como ID:

AI: quick_connect(host="1.2.3.4", username="root", password="***")
→ "Connected: root@1.2.3.4:22, use server_id="1.2.3.4:22""

AI: execute(server_id="1.2.3.4:22", command="df -h")
AI: disconnect(server_id="1.2.3.4:22")

Transferência Assíncrona (Arquivos Grandes)

Para arquivos grandes, ative o modo de transferência em segundo plano para evitar bloqueios:

AI: upload_file(server_id="prod", local_path="big.tar.gz", remote_path="/data/", async_transfer=true)
→ "Background upload started: tf_1"

AI: transfer_status("tf_1")
→ "🔄 Uploading: 638.2 MB / 1.2 GB (53.2%) — 12.4 MB/s, ETA 46s"

AI: transfer_status("tf_1")
→ "✅ Upload complete: 1.2 GB, 98s, 12.3 MB/s"

Arquivos pequenos usam modo síncrono por padrão — sem necessidade de configuração.

Exemplos de Conexão

Autenticação por senha

AI: add_server(server_id="prod", name="Production", host="10.0.0.1", username="deploy", password="***")
AI: execute(server_id="prod", command="systemctl status nginx")

Autenticação por chave privada

AI: add_server(server_id="aws", name="AWS EC2", host="ec2-xx.compute.amazonaws.com", username="ubuntu", private_key="~/.ssh/id_rsa")

Conexão rápida (sem salvar configuração)

AI: quick_connect(host="192.168.1.100", username="root", password="***")
→ server_id="192.168.1.100:22"

AI: execute(server_id="192.168.1.100:22", command="df -h")
AI: disconnect(server_id="192.168.1.100:22")

Via proxy SOCKS5

AI: add_proxy(proxy_id="tunnel", name="SSH Tunnel", host="127.0.0.1", port=1080, type="5")
AI: add_server(server_id="internal", ..., proxy="tunnel")

Via host de salto

AI: add_server(server_id="bastion", name="Bastion", host="bastion.example.com", username="admin", private_key="~/.ssh/id_rsa")
AI: add_server(server_id="internal", name="Internal DB", host="10.0.0.5", username="dbadmin", password="***", jump_host="bastion")

Localização da Configuração

As configurações de servidor e proxy são armazenadas em:

~/.ssh-mcp/config.json

As senhas são armazenadas em texto puro. Para uso em produção, prefira autenticação por chave privada.

Requisitos

• Node.js >= 18
• Um cliente compatível com MCP (Claude Code, Claude Desktop, Cursor, etc.)
• Servidor remoto com acesso SSH

Licença

MIT