@txcxgzs/ssh-mcp

Haz que SSH funcione para las herramientas de IA. Servidor MCP que gestiona tu entorno SSH, diagnostica lo que falla, lo repara y le da a tu agente acceso remoto a cualquier cosa.

Relación con el fork: Este repositorio es un fork derivado de YawLabs/ssh-mcp. Mantiene la implementación SSH/MCP upstream, incorpora la resolución de alias de contraseña en el lado del servidor mediante SSH_CREDENTIALS_JSON, elimina las contraseñas en texto plano de los argumentos de las herramientas MCP y corrige la creación inicial de known_hosts cuando ~/.ssh aún no existe. El upstream sigue siendo el proyecto original; los cambios específicos del fork se mantienen por separado aquí.

El proyecto original está construido y mantenido por Yaw Labs.

Un clic añade esto a tu configuración local de Yaw MCP para que esté disponible en todas las sesiones de Yaw Terminal. O instálalo manualmente más abajo.

El problema

Las herramientas de CLI con IA se ejecutan en procesos donde SSH falla constantemente. Si el agente intenta git pull y recibe Permission denied (publickey). Si intenta conectarse por SSH a un servidor, el socket del agente está obsoleto. Si intenta desplegar, la clave de host ha cambiado porque la instancia fue recreada. En cada ocasión, la IA no sabe qué falla y entra en espiral.

Esto sucede en cualquier situación que requiere claves SSH:

• Git — clone, pull, push, fetch, submódulos, LFS

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

• Acceso a servidores — SSH, SCP, SFTP, rsync

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

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

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

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

Related MCP server: MCP SSH Server

Inicio rápido

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

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@txcxgzs/ssh-mcp@latest"],
      "env": {
        "SSH_CREDENTIALS_JSON": "{\"ssh1\":\"your-password\"}"
      }
    }
  }
}

En Windows envuélvelo con cmd /c, ya que Node 20+ no puede ejecutar archivos .cmd directamente:

{
  "mcpServers": {
    "ssh": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@txcxgzs/ssh-mcp@latest"]
    }
  }
}

La etiqueta @latest hace que npx vuelva a resolver contra el registro en cada ejecución, de modo que cada sesión MCP usa la versión publicada más reciente. O instálalo de forma global si prefieres fijar una versión (sin actualizaciones automáticas):

npm install -g @txcxgzs/ssh-mcp
# then in client config: "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úniles — deje de fallar.

Diagnósticos

Operaciones remotas

Operaciones avanzadas

Herramientas que envuelven patrones habituales que los agentes construyen con ssh_exec, de forma más rápida y con menos errores.

Auto-diagnóstico

Cuando cualquier operación remota fracaspera, ssh-mcp ejecuta automáticamente el diagnóstico e incluye los resultados en la respuesta de error. Tu agente no necesita llamar a ssh_diagnose por separado: el propio mensaje de error le dice qué está mal y cómo corregirlo.

Pool de conexiones

Las operaciones remotas reutilizan conexiones SSH automáticamente. Cuando tu agente hace varias llamadas al mismo host, la primera abre una conexión y las siguientes la aprovechan. Las conexiones se mantienen vivas durante 60 segundos después de la última utilización y luego se cierran automáticamente.

El pool está limitado a 100 conexiones activas de forma predeterminada. Establece con SSH_MCP_MAX_POOL_SIZE=<n> para aumentarlo en cargas de fan-out con muchos hosts distintos (por ejemplo, ssh_multi_exec sobre una gran flota). Cuando se alcanza el límite, el pool despide una entrada inactiva para desalojar espacio; si todas las entradas están en uso, descarta con Connection pool is full.

Soporte de configuración SSH

Todas las conexiones respetan tu archivo ~/.ssh/config. Los alias de host, puertos personalizados, nombres de usuario, identity files y los ajustes de ProxyJump se usan automáticamente. Si tienes Host myserver configurado en tu archivo SSH, es suficiente con enviar host: "myserver": ssh-mcp lo resuelve todo.

Adaptadores ProxyJump / bastion hosts están soportados automáticamente. Si tu config SSH tiene ProxyJump bastion para un host, ssh-mcp se conecta a través del agente intermedio de forma transparente. Los proxies encadenados también funcionan.

Verificación de la clave del host

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

• Host conocido, clave coincide — aceptar.

• Host conocido, clave cambiada — rechazar (protección contra MITM).

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

Para entornos más estrictos, define SSH_MCP_STRICT_HOST_KEY=1 para rechazar hosts desconocidos. Añádelos explícitamente con ssh_known_hosts_fix antes.

Los diagnósticos (ssh_test, ssh_diagnose) utilizan StrictHostKeyChecking=no para sus comandos de prueba. Estas pruebas solo ejecutan echo SSH_OK — tras envían credenciales ni datos — por lo que la opción relajada es segura para pruebas de conectividad. Las operaciones reales pasan siempre por el hostVerifier.

Command policy

ssh_exec y ssh_multi_exec aceptan comandos de shell de formato libre del agente. Para implementaciones conscientes de la seguridad, puedes restringir qué comandos se ejecutan mediante dos variables de entorno, cada una aceptando una lista separada por comas de patrones de regex:

• SSH_MCP_COMMAND_WHITELIST — si se establece, el comando debe coincidir con al menos un patrón; de lo contrario, se bloquea.

• SSH_MCP_COMMAND_BLACKLIST — si se establece, el comando no debe coincidir con ningún patrón; de lo contrario, se bloquea.

Cuando ambos están establecidos, el comando debe pasar ambas comprobaciones (primero la lista blanca, luego la lista negra). Cuando ninguno está establecido (el valor predeterminado), se permiten todos los comandos.

Los patrones son expresiones regulares de JavaScript. Usa ^ y $ para coincidencias ancladas; de lo contrario, los patrones se tratan como coincidencias de subcadena. Las comas son el delimitador, por lo que una coma literal en un patrón debe expresarse como \x2c o mediante una clase de caracteres.

# Read-only allowlist: only ls / df / cat / find / tail
SSH_MCP_COMMAND_WHITELIST="^ls( .*)?,^df( .*)?,^cat ,^find ,^tail "

# Block destructive ops even if your agent goes off-script
SSH_MCP_COMMAND_BLACKLIST="^rm ,^shutdown,^reboot,^mkfs,^dd if=,>\s*/dev/"

Los comandos bloqueados aparecen como un error claro que menciona qué patrón (o qué variable de entorno) rechazó la llamada, para que el agente pueda adaptarse en lugar de adivinar. La política se aplica antes de que se abra la conexión SSH: no se inicia ningún proceso remoto para un comando bloqueado.

Las herramientas estructuradas de nivel superior (ssh_find, ssh_tail, ssh_service_status, operaciones SFTP) están exentas de la política. Construyen comandos a partir de parámetros tipados, por lo que una lista blanca estricta como ^ls te obligaría a permitir ^find , ^tail , ^systemctl solo para mantener esas herramientas funcionando, lo que anularía el propósito de una lista blanca estricta.

Interacción de la política con el parámetro env de ssh_exec

Cuando se llama a ssh_exec con env: { KEY: "value" }, los valores se inyectan como un prefijo de shell KEY='value' ... antes del comando (consulta la descripción de ssh_exec). La política se comprueba contra el comando completo con prefijo, no contra el argumento command desnudo. Ese es el orden más seguro en la capa de protocolo, pero significa que los patrones de la lista blanca deben anticipar el prefijo y deben estar anclados, no ser coincidencias de subcadena:

# WRONG -- blocks any ssh_exec call that uses `env`, because the final command
# starts with `KEY='value' ` and never matches `^ls`.
SSH_MCP_COMMAND_WHITELIST="^ls "

# RIGHT -- allow zero or more `KEY='value' ` prefixes before the real command.
SSH_MCP_COMMAND_WHITELIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*ls( |$)"

Evita los patrones de coincidencia de subcadena como ls si te preocupa un agente hostil. Un agente podría pasar env: { ATTACK: " ls " } para hacer que el comando final sea ATTACK=' ls ' rm -rf /, que coincide con una subcadena ls y elude la lista blanca. Los patrones anclados de la forma anterior no tienen esta debilidad porque requieren que el nombre real del comando siga al bloque de prefijo de entorno, no que aparezca dentro de un valor de entorno entre comillas.

Las listas negras necesitan el mismo cuidado. ^rm bloquea una llamada rm simple, pero no bloquea FOO='bar' rm. Usa el mismo ancla tolerante al prefijo de entorno:

SSH_MCP_COMMAND_BLACKLIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*rm( |$)"

Si no confías en absoluto en los valores env del agente, la mitigación más simple es dejar env sin usar en la configuración de tu cliente y pasar todo a través de la cadena command tú mismo.

Soporte para Windows

En Windows, ssh-mcp detecta automáticamente el servicio OpenSSH Authentication Agent (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é en ejecución.

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. Contraseña resuelta desde credential_id

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)

Las contraseñas reales nunca son parámetros de herramientas MCP. Configura el mapa de alias a contraseña solo en el entorno del servidor MCP, y luego deja que el agente seleccione host, port, username y credential_id dinámicamente:

SSH_CREDENTIALS_JSON={"ssh1":"password1","ssh2":"password2"}

{
  "host": "bore.pub",
  "port": 45201,
  "username": "root",
  "credential_id": "ssh1",
  "command": "hostname"
}

Si se omite credential_id, la autenticación por clave y ssh-agent continúan funcionando. Un alias desconocido falla sin incluir ninguna contraseña configurada en el mensaje de error.

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 la recreación de 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 '@txcxgzs/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