mcp-ssh-tool

Un servidor cliente SSH basado en el Protocolo de Contexto de Modelo (MCP) que proporciona operaciones SSH autónomas para GitHub Copilot y VS Code. Habilita la automatización SSH mediante lenguaje natural sin necesidad de prompts manuales ni interacciones con la interfaz gráfica.

Entrada oficial en el registro MCP: io.github.oaslananka/mcp-ssh-tool
Metadatos del registro: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.oaslananka%2Fmcp-ssh-tool/versions/latest

Inicio rápido

Instalación

• Instalación global (recomendado): npm install -g mcp-ssh-tool

• Ejecución única: npx mcp-ssh-tool

Configuración del cliente MCP (VS Code / Claude Desktop / otros)

Añádelo a tu configuración de MCP (mcp.json, .vscode/mcp.json o la configuración de MCP de Claude Desktop):

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Ejemplos de uso

Una vez configurado, puedes usar lenguaje natural con tu cliente MCP:

• Conexión SSH: "Conéctate al servidor 192.168.1.100 como admin usando una clave SSH"

• Operaciones de archivo: "Lee el contenido de /etc/nginx/nginx.conf en el servidor"

• Ejecución de comandos: "Ejecuta 'systemctl status nginx' en el servidor remoto"

• Gestión de paquetes: "Instala el paquete htop en el servidor Ubuntu"

• Control de servicios: "Reinicia el servicio nginx"

• Claude Desktop: "conéctate a mi servidor y comprueba el uso del disco"

• Instalar un paquete/pila de servicios: "instala nginx en mi servidor remoto"

• Leer un archivo de configuración: "lee el archivo /etc/nginx/nginx.conf"

• Reiniciar un servicio: "reinicia el servicio nginx"

• Explorar registros: "lista los archivos en /var/log"

Herramientas disponibles

• ssh_open_session - Establece una conexión SSH con varios métodos de autenticación

• ssh_close_session - Cierra la sesión SSH

• ssh_list_sessions - Lista todas las sesiones SSH activas

• ssh_ping - Comprueba si una sesión está activa y responde

• ssh_list_configured_hosts - Lista los hosts desde ~/.ssh/config

• ssh_resolve_host - Resuelve el alias del host desde la configuración SSH

• proc_exec - Ejecuta comandos de forma remota (con tiempo de espera opcional)

• proc_sudo - Ejecuta comandos con privilegios sudo

• fs_read, fs_write, fs_list, fs_stat, fs_mkdirp, fs_rmrf, fs_rename - Operaciones del sistema de archivos

• ensure_package - Gestión de paquetes con estados present (presente) y absent (ausente)

• ensure_service - Control de servicios, incluyendo restarted (reiniciado)

• ensure_lines_in_file - Gestión de líneas en archivos con estados present y absent

• patch_apply - Aplica parches a archivos

• os_detect - Detección de información del sistema

• get_metrics - Métricas del servidor en formato JSON o Prometheus

• proc_exec_stream - Ejecución de comandos en streaming con salida fragmentada

• file_upload, file_download - Ayudantes para transferencia de archivos SFTP

• tunnel_local_forward, tunnel_remote_forward, tunnel_close, tunnel_list - Gestión de túneles

Recursos disponibles

• mcp-ssh-tool://sessions/active - Sesiones activas como JSON

• mcp-ssh-tool://metrics/json - Instantánea de métricas como JSON

• mcp-ssh-tool://metrics/prometheus - Exportación de métricas de Prometheus

• mcp-ssh-tool://ssh-config/hosts - Aliases de host SSH locales analizados

Descripción general

El servidor SSH MCP actúa como un puente entre GitHub Copilot y los sistemas remotos a través de SSH. Admite:

• Operaciones SSH no interactivas - Sin prompts ni interacciones de GUI

• Múltiples métodos de autenticación - Contraseña, claves SSH o agente SSH

• Gestión de sesiones - Agrupación de conexiones automática con TTL y desalojo LRU

• Operaciones del sistema de archivos - Leer, escribir, listar y gestionar archivos remotos mediante SFTP, con alternativas de shell SSH para hosts que no exponen un subsistema SFTP

• Ejecución de procesos - Ejecutar comandos y operaciones sudo de forma remota

• Automatización de alto nivel - Gestión de paquetes, control de servicios y gestión de configuración

• Seguridad - Redacción automática de datos confidenciales en los registros

Arquitectura

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  GitHub Copilot │────│  SSH MCP Server  │────│  Remote Systems │
│     / VS Code   │    │                  │    │   (via SSH)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │ MCP stdio protocol    │ Session management    │ SSH + optional SFTP
         │                       │ LRU cache + TTL       │
         │                       │ Auth strategies       │

Objetivos integrados / BusyBox

Algunos objetivos integrados exponen la ejecución de comandos SSH pero no incluyen un subsistema SFTP, lo cual es común en sistemas basados en Dropbear o BusyBox. En ese caso, ssh_open_session sigue teniendo éxito e informa sftpAvailable: false. Las herramientas de archivos principales como fs_read, fs_write, fs_stat, fs_list, fs_mkdirp, fs_rmrf y fs_rename recurren automáticamente a implementaciones basadas en shell.

Instalación

Requisitos previos

• Node.js ≥ 20 (LTS)

• Acceso SSH a los sistemas de destino

• Claves SSH o credenciales para la autenticación

Instalar desde npm

npm install -g mcp-ssh-tool

Construir desde el código fuente

git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install
npm run build
npm link

Flags de CLI

• --help / -h: Muestra el uso y ejemplos.

• --version / -v: Imprime la versión.

• --stdio: Fuerza el modo stdio (predeterminado).

Nota: Este es un servidor MCP stdio. El terminal no es un shell interactivo; utiliza un cliente MCP (Claude Desktop, VS Code MCP, etc.) o envía JSON-RPC a través de stdio.

Notas de plataforma

• Linux / macOS: Utiliza envoltorios de shell POSIX con comillas seguras. Directorio temporal predeterminado: /tmp.

• Objetivos Windows: Requiere servidor/agente OpenSSH; la detección de claves comprueba C:\Users\<you>\.ssh\. Los comandos se envuelven para una ejecución segura en PowerShell. Los ayudantes de paquetes/servicios están desactivados intencionalmente en los objetivos Windows.

• Claves de host: La comprobación de claves de host está relajada de forma predeterminada. Establece STRICT_HOST_KEY_CHECKING=true y opcionalmente KNOWN_HOSTS_PATH para forzar la verificación.

Integración con ChatGPT Desktop

Configuración rápida

npm run setup:chatgpt

Este comando configura automáticamente ChatGPT Desktop para usar mcp-ssh-tool.

Configuración manual

Añádelo a tu configuración de MCP de ChatGPT Desktop:

• macOS: ~/Library/Application Support/ChatGPT/mcp.json

• Windows: %APPDATA%\ChatGPT\mcp.json

• Linux: ~/.config/chatgpt/mcp.json

{
  "mcpServers": {
    "ssh-mcp-server": {
      "name": "ssh-mcp-server",
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

Para obtener información detallada sobre el uso, consulta docs/chatgpt-usage.md.

Integración con Codex

Configuración rápida

Instala el paquete globalmente y luego regístralo en Codex:

npm install -g mcp-ssh-tool
codex mcp add ssh-mcp -- mcp-ssh-tool

Si prefieres no instalarlo globalmente, puedes registrarlo a través de npx:

codex mcp add ssh-mcp -- npx -y mcp-ssh-tool

Verificación

Comprueba que Codex pueda ver el servidor MCP:

codex mcp list
codex mcp get ssh-mcp

Deberías ver un servidor stdio habilitado cuyo comando es mcp-ssh-tool o npx.

Refuerzo de seguridad opcional

Para forzar la verificación de la clave de host en el proceso del servidor gestionado por Codex:

codex mcp remove ssh-mcp
codex mcp add ssh-mcp \
  --env STRICT_HOST_KEY_CHECKING=true \
  --env KNOWN_HOSTS_PATH=/path/to/known_hosts \
  -- mcp-ssh-tool

Después de añadir el servidor, reinicia Codex o abre una sesión nueva, luego intenta una llamada de herramienta simple, como listar sesiones activas o abrir una conexión SSH.

Integración con VS Code Copilot

Configuración a nivel de usuario (Recomendado)

Abre VS Code y presiona Ctrl+Shift+P, luego ejecuta "MCP: Open User Configuration".

Añádelo a tu mcp.json:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Configuración a nivel de espacio de trabajo

Crea .vscode/mcp.json en tu espacio de trabajo:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Verificación

1. Reinicia VS Code

2. Abre Copilot Chat

3. Las herramientas SSH MCP deberían aparecer en la lista de herramientas disponibles

4. Prueba con: "Conéctate a 192.168.1.100 como admin y ejecuta 'uname -a'"

Claude Desktop, Antigravity y otros clientes MCP

Cualquier cliente compatible con MCP que pueda iniciar un servidor stdio puede usar mcp-ssh-tool. La pantalla de configuración exacta o el archivo de configuración varía según el cliente, pero el proceso es el mismo:

1. Instala el paquete:

npm install -g mcp-ssh-tool

2. Registra un servidor MCP stdio que inicie:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

3. Si el cliente utiliza un esquema de estilo mcpServers en lugar de servers, utiliza la entrada equivalente:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

Para Claude Desktop, utiliza el mismo patrón de comando stdio anterior en su configuración de MCP. Para Antigravity u otros clientes MCP, utiliza la propia interfaz de usuario de configuración de MCP del cliente o el formato de configuración, pero apúntalo al mismo comando ejecutable.

Ejemplos de uso

Conexión básica y ejecución de comandos

"Connect to 10.11.12.13 as deployer with password 'mypass' and run 'df -h'"

Operaciones de archivo

"Connect to server.example.com as admin, read /etc/nginx/nginx.conf and show me the server blocks"

Administración del sistema

"Connect to 192.168.1.50 as root, install htop package, start nginx service, and list /var/www contents"

Gestión de configuración

"Connect to web-server as admin, add these lines to /etc/hosts:
192.168.1.10 db-server
192.168.1.20 cache-server
Then restart networking service"

Ideas de prompts listas para usar

"connect to my server and check disk usage"

"install nginx on my remote server"

"read the file /etc/nginx/nginx.conf"

"restart the nginx service"

"list files in /var/log"

Consejos profesionales

• Sesiones múltiples: Abre una sesión por host o entorno y mantenlas activas con ssh_list_sessions y ssh_ping cuando cambies entre máquinas de producción, staging y desarrollo.

• Alternativa SFTP para BusyBox/Dropbear: En sistemas integrados que no exponen un subsistema SFTP, ssh_open_session aún puede tener éxito con sftpAvailable: false, y las herramientas principales fs_* recurren automáticamente a implementaciones basadas en shell.

• Verificación de clave de host: Establece STRICT_HOST_KEY_CHECKING=true en el entorno del servidor MCP y opcionalmente KNOWN_HOSTS_PATH para una verificación SSH de grado de producción más estricta.

Referencia de API

Arquitectura

src/
├── container.ts       - Dependency injection wiring
├── config.ts          - ConfigManager (env + programmatic overrides)
├── index.ts           - CLI entry point & graceful shutdown
├── mcp.ts             - MCP server (thin: delegates to ToolRegistry)
├── tools/
│   ├── registry.ts    - ToolRegistry (routes CallTool requests)
│   ├── types.ts       - ToolProvider interface
│   ├── session.provider.ts
│   ├── process.provider.ts
│   ├── fs.provider.ts
│   ├── ensure.provider.ts
│   ├── system.provider.ts
│   ├── transfer.provider.ts
│   └── tunnel.provider.ts
├── session.ts         - SessionManager (LRU cache + TTL)
├── resources.ts       - MCP resources for sessions, metrics, and SSH hosts
├── telemetry.ts       - Optional OpenTelemetry tracing
├── rate-limiter.ts    - Sliding window rate limiter
├── metrics.ts         - Prometheus-compatible metrics
├── safety.ts          - Command safety warnings (non-blocking)
└── ...                - fs-tools, process, ensure, detect, ...

Añadir un nuevo grupo de herramientas

1. Crea src/tools/<tu-namespace>.provider.ts implementando ToolProvider

2. Regístralo en src/tools/index.ts

3. Añade pruebas unitarias a test/unit/tools/<tu-namespace>.provider.test.ts

No se necesitan cambios en mcp.ts.

Herramientas de sesión

ssh_open_session

{
  "host": "example.com",
  "username": "admin",
  "port": 22,
  "auth": "auto",
  "password": "optional",
  "privateKey": "optional-inline-key",
  "privateKeyPath": "optional-path",
  "passphrase": "optional",
  "useAgent": false,
  "readyTimeoutMs": 20000,
  "ttlMs": 900000
}

Devuelve:

{
  "sessionId": "ssh-1645123456789-1",
  "host": "example.com",
  "username": "admin",
  "expiresInMs": 900000
}

ssh_close_session

{
  "sessionId": "ssh-1645123456789-1"
}

ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

• ssh_list_sessions devuelve sesiones activas con el TTL restante.

• ssh_ping comprueba la actividad y la latencia de una sesión.

• ssh_list_configured_hosts lee ~/.ssh/config.

• ssh_resolve_host expande un alias de host SSH en parámetros de conexión.

Herramientas de comando

proc_exec

{
  "sessionId": "ssh-1645123456789-1",
  "command": "ls -la /home",
  "cwd": "/tmp",
  "env": {
    "DEBUG": "1"
  },
  "timeoutMs": 30000
}

proc_sudo

{
  "sessionId": "ssh-1645123456789-1",
  "command": "systemctl restart nginx",
  "password": "sudo-password",
  "cwd": "/etc",
  "timeoutMs": 30000
}

Ambos devuelven:

{
  "code": 0,
  "stdout": "command output",
  "stderr": "",
  "durationMs": 245
}

Herramientas de archivo

• fs_read

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "encoding": "utf8"
}

• fs_write

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/tmp/config.txt",
  "data": "server_name example.com;\nlisten 80;",
  "mode": 420
}

• fs_stat devuelve size, mtime, mode y type.

• fs_list devuelve { "entries": [...], "nextToken": "optional" }.

• fs_mkdirp crea directorios de forma recursiva.

• fs_rmrf elimina archivos o directorios de forma recursiva.

• fs_rename renombra o mueve una ruta.

Herramientas de configuración y automatización

ensure_package

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "present",
  "sudoPassword": "optional"
}

state admite present y absent.

ensure_service

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "restarted",
  "sudoPassword": "optional"
}

state admite started, stopped, restarted, enabled y disabled.

ensure_lines_in_file

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "lines": [
    "192.168.1.10 db-server",
    "192.168.1.20 cache-server"
  ],
  "state": "present",
  "createIfMissing": true,
  "sudoPassword": "optional"
}

state admite present y absent.

patch_apply

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "diff": "@@ -1 +1 @@\n-old\n+new"
}

os_detect

Devuelve la plataforma remota, distribución, versión, gestor de paquetes, sistema de inicio, shell y directorio temporal.

get_metrics

Devuelve métricas del servidor. La salida predeterminada es JSON; { "format": "prometheus" } opcional emite el formato de texto de Prometheus.

Autenticación

El servidor admite múltiples métodos de autenticación con alternativa automática:

Prioridad de estrategia de autenticación

1. Contraseña (si se proporciona)

2. Clave SSH (en línea → ruta → detección automática)

3. Agente SSH (si está disponible)

Detección automática de claves SSH

El servidor busca automáticamente claves SSH en:

• ~/.ssh/id_ed25519

• ~/.ssh/id_rsa

• ~/.ssh/id_ecdsa

Nota: Las claves DSA (`id_