@yawlabs/ssh-mcp

Operaciones SSH para agentes de IA. Servidor MCP con ejecución remota de comandos, transferencia de archivos y diagnósticos SSH integrados que te indican exactamente qué está mal y cómo solucionarlo.

Creado y mantenido por Yaw Labs.

¿Por qué esta herramienta?

Los agentes de IA que se conectan por SSH a servidores remotos se encuentran con los mismos problemas una y otra vez: ssh-agent inactivo, clave incorrecta cargada, claves de host obsoletas por instancias recreadas, acceso denegado sin contexto útil. La mayoría de los servidores MCP SSH simplemente envuelven ssh2 y dejan que el agente descifre errores crípticos.

Este incluye ssh_diagnose, una herramienta de diagnóstico que verifica todo tu entorno SSH (agente, claves, configuración, known_hosts, conectividad) y devuelve comandos de solución accionables. Úsala antes de conectarte o después de un fallo.

Inicio rápido

npm install -g @yawlabs/ssh-mcp

Añádelo a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "ssh": {
      "command": "ssh-mcp"
    }
  }
}

Herramientas

Operaciones principales

Diagnósticos

Autenticación

Todas las herramientas aceptan parámetros de conexión:

Orden de resolución de autenticación: clave explícita > contraseña explícita > ssh-agent (SSH_AUTH_SOCK) > rutas de clave predeterminadas (~/.ssh/id_ed25519, id_rsa, id_ecdsa).

Diagnósticos

ssh_diagnose ejecuta 5 comprobaciones y devuelve un informe estructurado:

1. Agente SSH — ¿Está ssh-agent en ejecución? ¿Están cargadas las claves?

2. Claves SSH — ¿Existen claves privadas en ~/.ssh/?

3. Configuración SSH — ¿Existe una entrada de configuración para este host? (admite comodines)

4. Hosts conocidos — ¿Está la clave del host en caché?

5. Conectividad — ¿Podemos conectarnos realmente?

Cada comprobación fallida incluye el comando exacto para solucionarlo. Ejemplo de salida:

SSH Diagnostic Report for dev-server:22
Overall: ERROR

[PASS] SSH Agent
  ssh-agent running with keys:
  256 SHA256:abc... user@host (ED25519)

[PASS] SSH Keys
  Found SSH keys: id_ed25519, gh_woods

[PASS] SSH Config
  SSH config for "dev-server":
  Host dev-server
    HostName 10.0.1.50
    User ec2-user

[FAIL] Known Hosts
  Host "dev-server" is not in known_hosts.

[FAIL] Connectivity
  Host key verification failed for dev-server. The host key changed (instance recreated?).

Suggested fixes:
  - Remove stale host key: ssh-keygen -R "dev-server"
  - Re-add host key: ssh-keyscan -H "dev-server" >> ~/.ssh/known_hosts

Uso programático

import { connect, exec, diagnose } from '@yawlabs/ssh-mcp';

// Run a command
const client = await connect({ host: 'my-server', username: 'deploy' });
const result = await exec(client, 'uptime');
console.log(result.stdout);
client.end();

// Diagnose connectivity issues
const report = diagnose('my-server');
console.log(report.overall); // "ok" | "warning" | "error"
for (const check of report.checks) {
  console.log(`[${check.status}] ${check.name}: ${check.message}`);
}

Requisitos

• Node.js 18+

• Cliente SSH instalado (para diagnósticos)

Licencia

MIT