SSH MCP Server

@nl4ever/sshmcp

中文文档

Permite que la IA gestione tus servidores remotos. Un servidor de Model Context Protocol (MCP) que brinda a los asistentes de IA acceso SSH completo: ejecutar comandos, transferir archivos, gestionar múltiples servidores simultáneamente, todo a través de conversación natural.

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

Características

• 21 Herramientas — Conectar, ejecutar, subir, descargar, escribir archivos y más
• Grupo de Conexiones — Opera múltiples servidores simultáneamente, cada comando etiquetado con server_id
• Transferencia de Archivos Sin Tokens — Transferencia basada en rutas SFTP, el contenido de los archivos nunca entra en el contexto de la IA
• Subida de Directorios — Compresión automática tar.gz → subida → descompresión remota (rápido para muchos archivos pequeños)
• Transferencia Asíncrona + Progreso — Transferencia en segundo plano para archivos grandes con seguimiento de progreso en tiempo real
• Conexión Rápida — Conexiones temporales sin guardar configuración, devuelve host:port como ID temporal
• Proxy SOCKS4/5 — Soporte de proxy por conexión
• Host de Salto — SSH ProxyJump para acceso a bastión/puerta de enlace
• Multi-Autenticación — Contraseña, clave privada, ssh-agent, teclado interactivo (OTP/2FA)

Inicio Rápido

Instalar globalmente

npm install -g @nl4ever/sshmcp

Añadir a Claude Code

claude mcp add sshmcp sshmcp

Añadir a Claude Desktop

Editar claude_desktop_config.json:

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

Añadir a Cursor

Ir a Configuración → Servidores MCP → Añadir:

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

Resumen de Herramientas

Gestión de Conexiones

Herramienta	Descripción
list_servers	Listar todos los servidores configurados y conexiones activas
get_server	Ver detalles de configuración del servidor
add_server	Añadir/actualizar configuración del servidor (contraseña, clave, agente, OTP)
update_server	Modificar configuración del servidor (solo pasar los campos que desees cambiar)
delete_server	Eliminar un servidor
rename_server	Renombrar un ID de servidor
connect	Conectar manualmente (normalmente no es necesario, las herramientas se conectan automáticamente)
quick_connect	Conexión temporal, devuelve host:port como ID
disconnect	Desconectar un servidor específico o todas las conexiones
test_connection	Probar conectividad sin afectar las conexiones existentes

Ejecución de Comandos

Herramienta	Descripción
execute	Ejecutar comandos de shell en el servidor remoto (con tiempo de espera configurable)

Operaciones de Archivos

Herramienta	Descripción
read_file	Leer contenido de archivo remoto (con rango de líneas opcional)
write_file	Escribir contenido de texto en archivo remoto
upload_file	Subir archivo local a remoto (soporta modo asíncrono)
upload_directory	Subir directorio con compresión automática → transferencia → descompresión
download_file	Descargar archivo remoto a local (soporta modo asíncrono)
download_directory	Descargar directorio con compresión remota → transferencia → descompresión local
transfer_status	Verificar progreso de transferencias asíncronas (tamaño/velocidad/tiempo estimado)

Gestión de Proxies

Herramienta	Descripción
list_proxies	Listar todos los ajustes preestablecidos de proxy SOCKS
add_proxy	Añadir ajuste preestablecido de proxy SOCKS4/5
delete_proxy	Eliminar un ajuste preestablecido de proxy

Grupo de Conexiones: Operaciones Multi-Servidor

Todas las herramientas de operación aceptan un parámetro server_id. El grupo de conexiones gestiona automáticamente las conexiones — no se necesita 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 temporales, usa quick_connect que devuelve 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")

Transferencia Asíncrona (Archivos Grandes)

Para archivos grandes, activa el modo de transferencia en segundo plano para evitar bloqueos:

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"

Los archivos pequeños usan modo síncrono por defecto — no se necesita configuración.

Ejemplos de Conexión

Autenticación con contraseña

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")

Autenticación con clave privada

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

Conexión rápida (sin guardar configuración)

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")

A través de 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")

A través de 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")

Ubicación de Configuración

Las configuraciones de servidor y proxy se almacenan en:

~/.ssh-mcp/config.json

Las contraseñas se almacenan en texto plano. Para uso en producción, prefiere la autenticación con clave privada.

Requisitos

• Node.js >= 18
• Un cliente compatible con MCP (Claude Code, Claude Desktop, Cursor, etc.)
• Servidor remoto con acceso SSH

Licencia

MIT