mcp-ssh-tool

👁 npm version
👁 CI
👁 Security
👁 Official MCP Registry
👁 License: MIT
👁 npm downloads

Automatización SSH MCP de nivel de producción para operadores, desarrolladores y clientes de IA. mcp-ssh-tool abre sesiones SSH persistentes y expone herramientas seguras y estructuradas para la ejecución de comandos, operaciones de archivos, transferencias, túneles, gestión de paquetes/servicios, métricas, recursos y prompts guiados.

La v2 es segura por defecto: la verificación estricta de la clave de host está activada, el inicio de sesión root está desactivado, el uso de sudo sin procesar está restringido por políticas, los comandos destructivos y las mutaciones del sistema de archivos están denegados a menos que la política lo permita, y el HTTP remoto solo se inicia en loopback a menos que se configuren la autenticación bearer y los orígenes permitidos.

Por qué este servidor

• Confianza: motor de políticas central, eventos de auditoría estructurados, registros redactados, claves de host estrictas y errores legibles por máquina.

• Calidad MCP: stdio para clientes locales, HTTP transmitible (Streamable) para clientes remotos, SSE heredado solo detrás de una bandera de compatibilidad explícita.

• Herramientas amigables para IA: esquemas de salida estables, structuredContent, anotaciones para comportamiento de solo lectura/destructivo/idempotente, recursos y prompts seleccionados.

• Operaciones: TTL/evicción de sesión, tiempos de espera de comandos, verificación de suma de comprobación de transferencia, reenvío SSH real, métricas de Prometheus y ganchos de OpenTelemetry.

• Portabilidad: SFTP primero, alternativas de shell compatibles con POSIX/BusyBox para operaciones básicas de archivos y límites de soporte explícitos.

Inicio rápido

Ejecutar sin instalar:

npx -y mcp-ssh-tool --version

O instalar globalmente:

npm install -g mcp-ssh-tool

Añadir un servidor MCP stdio a su cliente:

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

Usarlo desde su cliente MCP:

Open a safe SSH session to prod-1 as deploy, inspect host capabilities, then show disk usage.

Requisitos

• Node.js 22.22.2+ o 24.14.1+ (solo LTS)

• Acceso SSH a los hosts de destino

• Un archivo known_hosts poblado para la verificación estricta de hosts, o una política de clave de host explícita por sesión

Transportes

El inicio de HTTP fuera de loopback se rechaza a menos que se configuren tanto --bearer-token-file como los orígenes permitidos.

Valores predeterminados seguros

El policyMode: "explain" por sesión devuelve un plan/veredicto sin ejecutar. Úselo antes de las mutaciones cuando un cliente de IA necesite resumir el riesgo.

Ejemplo de política

Establezca SSH_MCP_POLICY_FILE=/etc/mcp-ssh-tool/policy.json:

{
 "mode": "enforce",
 "allowRootLogin": false,
 "allowRawSudo": false,
 "allowDestructiveCommands": false,
 "allowDestructiveFs": false,
 "allowedHosts": ["^prod-[0-9]+\\.example\\.com$"],
 "commandAllow": ["^(uname|df|uptime|systemctl status)\\b"],
 "commandDeny": ["rm\\s+-rf\\s+/", "shutdown", "reboot"],
 "pathAllowPrefixes": ["/tmp", "/var/tmp", "/home/deploy"],
 "pathDenyPrefixes": ["/etc/shadow", "/etc/sudoers", "/boot", "/dev", "/proc"]
}

Las implementaciones simples pueden usar anulaciones de entorno como SSH_MCP_ALLOW_RAW_SUDO=true, SSH_MCP_ALLOWED_HOSTS=prod-1.example.com o SSH_MCP_PATH_ALLOW_PREFIXES=/tmp,/home/deploy.

Herramientas principales

• ssh_open_session, ssh_close_session, ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

• proc_exec, proc_sudo, proc_exec_stream

• fs_read, fs_write, fs_list, fs_stat, fs_mkdirp, fs_rmrf, fs_rename

• file_upload, file_download

• ensure_package, ensure_service, ensure_lines_in_file, patch_apply

• os_detect, get_metrics

• tunnel_local_forward, tunnel_remote_forward, tunnel_list, tunnel_close

Todas las herramientas devuelven texto más structuredContent estable. Los metadatos de la herramienta incluyen títulos, esquemas de salida y anotaciones que revelan el comportamiento de solo lectura, destructivo, idempotente y de efectos secundarios externos.

Recursos y Prompts

Recursos:

• mcp-ssh-tool://sessions/active

• mcp-ssh-tool://metrics/json

• mcp-ssh-tool://metrics/prometheus

• mcp-ssh-tool://ssh-config/hosts

• mcp-ssh-tool://policy/effective

• mcp-ssh-tool://audit/recent

• mcp-ssh-tool://capabilities/support-matrix

Prompts:

• safe-connect

• inspect-host-capabilities

• plan-mutation

• managed-config-change

Matriz de soporte

Ejemplos de cliente

ChatGPT o Claude Desktop:

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

VS Code o Cursor:

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

MCP Inspector sobre HTTP:

printf '%s' 'super-secret-token' > .mcp-token
mcp-ssh-tool --transport=http --host 127.0.0.1 --port 3000 --bearer-token-file .mcp-token

Configuración

Variables de entorno de alto valor:

Los alias obsoletos STRICT_HOST_KEY_CHECKING y SSH_MCP_STRICT_HOST_KEY todavía se aceptan para un ciclo de compatibilidad de la v2. Prefiera SSH_MCP_HOST_KEY_POLICY.

Desarrollo

Use el tiempo de ejecución local exacto de .nvmrc / .node-version, luego ejecute:

npm ci
npm run check

Las suites SSH en vivo son opcionales:

RUN_SSH_INTEGRATION=1 npm run test:integration
RUN_SSH_E2E=1 npm run test:e2e

Las puertas de calidad locales están estratificadas:

• pre-commit: formatea archivos preparados y analiza solo TypeScript preparado

• pre-push: ejecuta npm run check:push

• task hooks: ejecuta ganchos npm rastreados más ganchos de .pre-commit-config.yaml cuando pre-commit está instalado

• paridad manual/completa: task ci o npm run check

Propiedad de CI/CD

El repositorio personal https://github.com/oaslananka/mcp-ssh-tool es el repositorio fuente canónico. La CI/CD automática, las comprobaciones de seguridad de la cadena de suministro, la publicación confiable de npm y la publicación en el Registro MCP se ejecutan solo desde https://github.com/oaslananka-lab/mcp-ssh-tool. El repositorio de la organización extrae de la fuente canónica; los flujos de trabajo de inserción y publicación del repositorio personal están deshabilitados.

El repository.url del paquete npm apunta intencionalmente al repositorio de la organización para que la procedencia de npm pueda verificar que el artefacto publicado provino del mismo repositorio de GitHub Actions que lo construyó.

Consulte docs/ci-cd-topology.md para obtener orientación sobre la sincronización de la organización, el flujo de lanzamiento y la alternativa manual.

Documentación

• ARCHITECTURE.md

• SECURITY_DECISIONS.md

• MIGRATION.md

• docs/ci-cd-topology.md

• docs/development.md

• docs/release.md

• docs/doppler.md

• docs/operations.md

• docs/branch-protection.md

• docs/maintenance-policy.md

• docs/api-stability.md

• docs/threat-model.md

• docs/configuration.md

• docs/security-model.md

• docs/troubleshooting.md

• docs/enterprise-deployment.md

Licencia

Licencia MIT. Consulte LICENSE.

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• connector_statusA
• ensure_lines_in_fileA
• ensure_packageC
• ensure_serviceB
• file_downloadA
• file_uploadB
• fs_listC
• fs_mkdirpA