ssh-mcp v4.0

Servidor MCP para trabajo SSH persistente en hosts Linux y dispositivos de red.

Características

• Conexiones SSH persistentes con reconexión automática

• Almacenamiento seguro de credenciales mediante Windows Credential Manager

• Soporte para dispositivos de red: Cisco IOS/IOS-XE/XR, MikroTik, FortiGate, Juniper

• Gestión de configuración: copia de seguridad, restauración y diff para dispositivos de red

• SFTP: subir, descargar y listar archivos remotos

• Túneles SSH: reenvío de puertos persistente

• Limitación de velocidad: evita la saturación del dispositivo (mínimo de 100ms entre comandos)

• Conexión inteligente: usa ssh_connect(alias='vps') para cargar las credenciales guardadas automáticamente

Related MCP server: SSH MCP Server

Inicio rápido

1. Guardar un servidor (una vez)

ssh_save_server(
    alias='vps',
    host='192.168.10.1',
    username='sassogba',
    password='your-password',
    auto_connect=True  # Auto-connect on startup
)

2. Conectar (modo simple)

ssh_connect(alias='vps')  # Loads credentials from servers.json

3. Ejecutar comandos

ssh_exec(alias='vps', command='df -h')
ssh_exec_sudo(alias='vps', command='systemctl restart nginx', sudo_password='...')

Novedades en v4.0

Modo de conexión inteligente

• ssh_connect ahora acepta solo un alias para cargar credenciales automáticamente

• No es necesario proporcionar host, usuario y contraseña cada vez

• Corrige problemas de integración con Claude Code

Correcciones críticas

• Gestión de tiempo de espera: ahora lanza TimeoutError en lugar de devolver silenciosamente buffers incompletos

• Limitación de velocidad: mínimo de 100ms entre comandos de red para evitar la saturación del dispositivo

• Números mágicos eliminados: constantes con nombre para las dimensiones de la shell

Documentación

• Nuevo CLAUDE_CODE_USAGE.md con ejemplos de uso completos

• Nuevo CLAUDE_CODE_SETUP.md para la configuración

• Nuevo CHANGELOG.md con el historial completo de versiones

Modelo de seguridad

servers.json solo guarda metadatos no sensibles. Los secretos residen en Windows Credential Manager bajo destinos como:

• ssh-mcp:<alias>:password

• ssh-mcp:<alias>:key_passphrase

Política de claves de host

• strict: predeterminada, rechaza claves de host desconocidas (producción)

• auto_add: acepta claves de host desconocidas (solo laboratorio)

Dispositivos de red

Tipos de dispositivos compatibles:

• cisco - Cisco IOS/IOS-XE

• cisco_xr - Cisco IOS-XR

• mikrotik - MikroTik RouterOS

• fortigate - FortiGate FortiOS

• juniper - Juniper JunOS

• generic - Linux/Unix (predeterminado)

Ejemplo: copia de seguridad de Cisco

# Save once
ssh_save_server(
    alias='cisco-core',
    host='10.0.0.1',
    username='admin',
    password='...',
    device_type='cisco',
    auto_connect=True
)

# Connect
ssh_connect(alias='cisco-core')

# Backup config
ssh_backup_config(alias='cisco-core', device_type='cisco')
# Saved to: backups/cisco-core/cisco-core_2026-05-31_14-30-00.txt

# Execute commands
ssh_exec_network(
    alias='cisco-core',
    commands=['show version', 'show ip interface brief'],
    device_type='cisco'
)

# Push config
ssh_push_config(
    alias='cisco-core',
    config='''
interface GigabitEthernet0/1
 description Uplink to Core
 ip address 10.0.1.1 255.255.255.0
 no shutdown
''',
    device_type='cisco',
    save_config=True
)

Uso con Claude Code

Consulta CLAUDE_CODE_USAGE.md para ver ejemplos detallados.

En resumen:

1. Save: ssh_save_server(alias='vps', host='192.168.10.1', username='sassogba', password='...')
2. Connect: ssh_connect(alias='vps')
3. Execute: ssh_exec(alias='vps', command='df -h')

18 herramientas disponibles

Gestión de conexiones

• ssh_connect - Establecer conexión SSH persistente (modo inteligente: solo proporcionar el alias)

• ssh_disconnect - Cerrar conexión y túneles

• ssh_list - Listar conexiones activas con estado

Configuración persistente

• ssh_save_server - Guardar servidor en servers.json (secretos en Credential Manager)

• ssh_remove_server - Eliminar servidor guardado

• ssh_list_servers - Listar todos los servidores guardados

Ejecución en Linux/Unix

• ssh_exec - Ejecutar comando de shell

• ssh_exec_sudo - Ejecutar con sudo (inyección automática de contraseña)

Ejecución en dispositivos de red

• ssh_exec_network - Ejecutar comandos en dispositivos de red (gestionar paginación y prompts)

• ssh_push_config - Implementar bloque de configuración

• ssh_backup_config - Hacer copia de seguridad de la configuración activa en un archivo local

• ssh_restore_config - Restaurar configuración desde archivo de respaldo

• ssh_diff_config - Comparar configuraciones (diff estilo git)

SFTP

• ssh_upload - Subir archivo al servidor remoto

• ssh_download - Descargar archivo del servidor remoto

• ssh_list_remote - Listar contenido del directorio remoto

Túneles

• ssh_tunnel - Crear túnel SSH persistente (reenvío de puertos)

• ssh_close_tunnel - Cerrar túnel por etiqueta

Arquitectura

• SSHPool: grupo de conexiones seguro para hilos con reconexión automática

• SSHConnection: estado por conexión con RLock para la seguridad entre hilos

• ThreadPoolExecutor: envoltorio async/await para Paramiko (que es síncrono)

• Limitador de frecuencia: mínimo de 100ms entre comandos para evitar la saturación del dispositivo

• Gestión de tiempo de espera: múltiples niveles (por comando, total, absoluto) con propagación adecuada de errores

Requisitos

paramiko>=3.0.0
mcp>=1.0.0
pywin32>=306

Instalar con:

pip install -r requirements.txt

Ejecutar pruebas

python -m pytest tests -v

Documentación

• CLAUDE_CODE_USAGE.md - Ejemplos de uso para Claude Code

• CLAUDE_CODE_SETUP.md - Guía de configuración

• CHANGELOG.md - Historial de versiones y guía de migración

Licencia

MIT