@yawlabs/ssh-mcp

👁 npm version
👁 License: MIT

Haz que SSH funcione para herramientas de IA. Servidor MCP que gestiona tu entorno SSH, diagnostica qué está roto, lo repara y le da a tu agente acceso remoto a cualquier cosa.

Creado y mantenido por Yaw Labs.

El problema

Las herramientas CLI de IA se ejecutan en subprocesos donde SSH falla constantemente. El agente intenta hacer git pull y obtiene Permission denied (publickey). Intenta conectarse por SSH a un servidor y el socket del agente está obsoleto. Intenta desplegar y la clave del host cambió porque la instancia fue recreada. Cada vez, la IA no tiene idea de qué está mal y entra en un bucle.

Esto sucede en todas las situaciones que requieren claves SSH:

• Git — clone, pull, push, fetch, submodules, LFS

• Gestores de paquetes — npm install, pip install, go get, cargo, composer desde repositorios privados

• Acceso al servidor — SSH, SCP, SFTP, rsync

• Túneles — reenvío de puertos a bases de datos, proxies SOCKS

• Despliegue — Ansible, Terraform, Capistrano, scripts de despliegue

• Nube — AWS EC2, GCP, Azure, DigitalOcean, cualquier VPS

ssh-mcp soluciona esto. Gestiona el agente SSH, carga claves, diagnostica fallos con comandos de reparación accionables y proporciona operaciones remotas, todo como herramientas MCP que tu agente de IA puede llamar.

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

Gestión del entorno SSH

Herramientas que reparan tu configuración SSH local para que todo lo demás (git, despliegues, túneles) deje de fallar.

Diagnósticos

Operaciones remotas

Operaciones de alto nivel

Herramientas que envuelven patrones comunes que los agentes construyen con ssh_exec, más rápidas y menos propensas a errores.

Autodiagnóstico

Cuando cualquier operación remota falla, ssh-mcp ejecuta automáticamente diagnósticos e incluye los resultados en la respuesta de error. Tu agente no necesita llamar a ssh_diagnose por separado; se le informa qué está mal y cómo solucionarlo directamente en el mensaje de error.

Agrupación de conexiones (Pooling)

Las operaciones remotas reutilizan las conexiones SSH automáticamente. Cuando tu agente realiza múltiples llamadas al mismo host, la primera llamada abre una conexión y las llamadas posteriores la reutilizan. Las conexiones se mantienen activas durante 60 segundos después del último uso y luego se cierran automáticamente.

Soporte de configuración SSH

Todas las conexiones respetan tu ~/.ssh/config. Los alias de host, puertos personalizados, nombres de usuario, archivos de identidad y configuraciones de ProxyJump se utilizan automáticamente. Si tienes Host myserver configurado en tu configuración SSH, simplemente pasa host: "myserver" y ssh-mcp resuelve todo.

ProxyJump / hosts bastión son compatibles automáticamente. Si tu configuración SSH tiene ProxyJump bastion para un host, ssh-mcp se conecta a través del bastión de forma transparente. Los proxies encadenados también funcionan.

Verificación de clave de host

Todas las operaciones remotas verifican la clave de host del servidor contra ~/.ssh/known_hosts:

• Host conocido, la clave coincide — aceptar.

• Host conocido, la clave cambió — rechazar (protección MITM).

• Host desconocido — aceptar en la primera conexión (TOFU). Usa ssh_known_hosts_fix para fijar la clave para futuras detecciones de discrepancias.

Para entornos más estrictos, establece SSH_MCP_STRICT_HOST_KEY=1 para rechazar hosts desconocidos. Agrégalos explícitamente con ssh_known_hosts_fix primero.

Las herramientas de diagnóstico (ssh_test, ssh_diagnose) usan StrictHostKeyChecking=no para sus comandos de sondeo. Esos sondeos solo ejecutan echo SSH_OK (no pasan credenciales ni datos), por lo que la configuración relajada es segura para probar la conectividad. Las operaciones reales siempre pasan por el hostVerifier.

Soporte para Windows

En Windows, ssh-mcp detecta el servicio OpenSSH Authentication Agent automáticamente (a través de la tubería con nombre \\.\pipe\openssh-ssh-agent). No se necesita SSH_AUTH_SOCK, solo asegúrate de que el servicio del agente OpenSSH esté ejecutándose.

Autenticación

Todas las operaciones remotas aceptan parámetros de conexión:

Orden de resolución de autenticación: ssh-mcp elige la primera coincidencia de esta lista y no pasa a las entradas posteriores; esto hace que el método de autenticación sea determinista y predecible.

1. privateKeyPath explícito

2. password explícito

3. ssh-agent (SSH_AUTH_SOCK en Unix, \\.\pipe\openssh-ssh-agent en Windows)

4. Archivos de identidad de ~/.ssh/config para el host

5. Rutas de clave predeterminadas (~/.ssh/id_ed25519, id_rsa, id_ecdsa)

Flujos de trabajo de ejemplo

El agente no puede hacer git pull

Agent calls ssh_git_check → "Permission denied. Your SSH key is not registered with github.com."
Agent calls ssh_key_list → finds id_ed25519 exists but is not loaded
Agent calls ssh_key_load("~/.ssh/id_ed25519") → "Key loaded"
Agent calls ssh_git_check → "Git SSH authentication to github.com succeeded as username"
Agent runs git pull → works

La clave de host cambió después de recrear la instancia

Agent calls ssh_exec on server → error: "Host key verification failed"
 (auto-diagnostics included in error: "Fix with ssh_known_hosts_fix")
Agent calls ssh_known_hosts_fix("my-server") → "Host key refreshed"
Agent calls ssh_exec → works

Conexión por primera vez a un nuevo servidor

Agent calls ssh_test("new-server") → "Connection refused at new-server:22"
Agent calls ssh_diagnose("new-server") → full report showing agent running, keys loaded, but host unreachable
Agent reports: "SSH server isn't running on new-server or port 22 is blocked"

Uso programático

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

// Fix SSH environment
const agent = ensureAgent();
console.log(agent.message);

// Check git access
const git = checkGitSsh('github.com');
console.log(git.message);

// List available keys
const keys = listSshKeys();
for (const key of keys) {
 console.log(`${key.name} (${key.type}) - ${key.loadedInAgent ? 'loaded' : 'not loaded'}`);
}

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

// Run multiple commands with connection pooling
const pool = new ConnectionPool();
await pool.withConnection({ host: 'my-server' }, async (client) => {
 const r1 = await exec(client, 'uptime');
 console.log(r1.stdout);
});
// Connection stays open for 60s — next call reuses it
await pool.withConnection({ host: 'my-server' }, async (client) => {
 const r2 = await exec(client, 'df -h');
 console.log(r2.stdout);
});
pool.drain(); // close all connections when done

// Diagnose 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 y gestión del entorno)

Licencia

MIT

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• ssh_agent_ensureA
• ssh_config_lookupA
• ssh_deleteA
• ssh_diagnoseA
• ssh_downloadB
• ssh_execA
• ssh_findB
• ssh_git_checkA