🔐 ssh-mcp-server

Servidor MCP (Model Context Protocol) basado en SSH que permite la ejecución remota de comandos SSH a través del protocolo MCP.

English Document | 中文文档

📝 Descripción general del proyecto

ssh-mcp-server es una herramienta puente que permite a los asistentes de IA y otras aplicaciones que admiten el protocolo MCP ejecutar comandos SSH remotos a través de una interfaz estandarizada. Esto permite a los asistentes de IA operar servidores remotos de forma segura, ejecutar comandos y recuperar resultados sin exponer directamente las credenciales SSH a los modelos de IA.

Bienvenido a unirse al grupo de WeChat:

✨ Características clave

• 🔒 Conexiones seguras: Admite múltiples métodos de conexión SSH seguros, incluyendo autenticación por contraseña y autenticación por clave privada (con soporte para frase de contraseña)

• 🛡️ Control de seguridad de comandos: Controle con precisión el rango de comandos permitidos a través de mecanismos flexibles de listas negras y listas blancas para evitar operaciones peligrosas

• 🔄 Interfaz estandarizada: Cumple con las especificaciones del protocolo MCP para una integración perfecta con asistentes de IA que admiten el protocolo

• 📂 Transferencia de archivos: Admite transferencias de archivos bidireccionales, cargando archivos locales a servidores o descargando archivos desde servidores

• 🔑 Aislamiento de credenciales: Las credenciales SSH se gestionan completamente de forma local y nunca se exponen a los modelos de IA, lo que mejora la seguridad

• 🚀 Listo para usar: Se puede ejecutar directamente usando NPX sin necesidad de instalación global, lo que lo hace conveniente y rápido de implementar

📦 Repositorio de código abierto

GitHub: https://github.com/classfang/ssh-mcp-server

NPM: https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server

🛠️ Lista de herramientas

📚 Uso

🔧 Ejemplos de configuración de MCP

⚠️ Importante: En los archivos de configuración de MCP, cada argumento de línea de comandos y su valor deben ser elementos separados en la matriz args. NO los combine con espacios. Por ejemplo, use "--host", "192.168.1.1" en lugar de "--host 192.168.1.1".

⚙️ Opciones de línea de comandos

Options:
  --config-file       JSON configuration file path (recommended for multiple servers)
  --ssh-config-file   SSH config file path (default: ~/.ssh/config)
  --ssh               SSH connection configuration (can be JSON string or legacy format)
  -h, --host          SSH server host address or alias from SSH config
  -p, --port          SSH server port
  -u, --username      SSH username
  -w, --password      SSH password
  -k, --privateKey    SSH private key file path
  -P, --passphrase    Private key passphrase (if any)
  -W, --whitelist     Command whitelist, comma-separated regular expressions
  -B, --blacklist     Command blacklist, comma-separated regular expressions
  -s, --socksProxy    SOCKS proxy server address (e.g., socks://user:password@host:port)
  --allowed-local-paths Additional allowed local paths for upload/download, comma-separated
  --pty               Allocate pseudo-tty for command execution (default: true)
  --pre-connect       Pre-connect to all configured SSH servers on startup

🔑 Uso de contraseña

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456"
      ]
    }
  }
}

🔐 Uso de clave privada

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa"
      ]
    }
  }
}

🔏 Uso de clave privada con frase de contraseña

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa",
        "--passphrase", "pwd123456"
      ]
    }
  }
}

📋 Uso de ~/.ssh/config

Puede usar alias de host definidos en su archivo ~/.ssh/config. El servidor leerá automáticamente los parámetros de conexión desde la configuración SSH:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver"
      ]
    }
  }
}

Suponiendo que su ~/.ssh/config contiene:

Host myserver
    HostName 192.168.1.1
    Port 22
    User root
    IdentityFile ~/.ssh/id_rsa

También puede especificar una ruta de archivo de configuración SSH personalizada:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver",
        "--ssh-config-file", "/path/to/custom/ssh_config"
      ]
    }
  }
}

Nota: Los parámetros de línea de comandos tienen prioridad sobre los valores de configuración SSH. Por ejemplo, si especifica --port 2222, anulará el puerto de la configuración SSH.

🌐 Uso de proxy SOCKS

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--socksProxy", "socks://username:password@proxy-host:proxy-port"
      ]
    }
  }
}

📝 Uso de lista blanca y lista negra de comandos

Use los parámetros --whitelist y --blacklist para restringir el rango de comandos ejecutables. Los patrones múltiples se separan por comas. Cada patrón es una expresión regular utilizada para hacer coincidir comandos.

Ejemplo: Uso de lista blanca de comandos

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--whitelist", "^ls( .*)?,^cat .*,^df.*"
      ]
    }
  }
}

Ejemplo: Uso de lista negra de comandos

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--blacklist", "^rm .*,^shutdown.*,^reboot.*"
      ]
    }
  }
}

Nota: Si se especifican tanto la lista blanca como la lista negra, el sistema primero verificará si el comando está en la lista blanca y luego verificará si está en la lista negra. El comando debe pasar ambas verificaciones para ser ejecutado.

🧩 Ejemplo de conexión multi-SSH

Hay tres formas de configurar múltiples conexiones SSH:

📄 Método 1: Uso de archivo de configuración (Recomendado)

Cree un archivo de configuración JSON (por ejemplo, ssh-config.json):

Formato de matriz:

[
  {
    "name": "dev",
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  {
    "name": "prod",
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  }
]

Formato de objeto:

{
  "dev": {
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  "prod": {
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  }
}

Luego use el parámetro --config-file:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--config-file", "ssh-config.json"
      ]
    }
  }
}

🔧 Método 2: Uso de formato JSON con el parámetro --ssh

Puede pasar cadenas de configuración con formato JSON directamente:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"{abc=P100s0}\",\"socksProxy\":\"socks://127.0.0.1:10808\"}",
        "--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"socksProxy\":\"socks://127.0.0.1:10808\"}"
      ]
    }
  }
}

📝 Método 3: Formato heredado separado por comas (Compatible con versiones anteriores)

Para casos simples sin caracteres especiales en las contraseñas, aún puede usar el formato heredado:

npx @fangjunjie/ssh-mcp-server \
  --ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx" \
  --ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy"

⚠️ Nota: El formato heredado puede tener problemas con contraseñas que contienen caracteres especiales como =, ,, {, }. Use el Método 1 o el Método 2 para contraseñas con caracteres especiales.

En las llamadas a herramientas MCP, especifique el nombre de la conexión a través del parámetro connectionName. Si se omite, se utiliza la conexión predeterminada.

Ejemplo (ejecutar comando en la conexión 'prod'):

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ls -al",
    "connectionName": "prod"
  }
}

Ejemplo (ejecutar comando con opciones de tiempo de espera):

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ping -c 10 127.0.0.1",
    "connectionName": "prod",
    "timeout": 5000
  }
}

⏱️ Tiempo de espera de ejecución de comandos

La herramienta execute-command admite opciones de tiempo de espera para evitar que los comandos se bloqueen indefinidamente:

• timeout: Tiempo de espera de ejecución del comando en milisegundos (opcional, el valor predeterminado es 30000ms)

• Las respuestas de error incluyen campos estables code, message y retriable para un manejo más fácil por parte del agente

Esto es particularmente útil para comandos como ping, tail -f u otros procesos de larga duración que podrían bloquear la ejecución.

🗂️ Listar todos los servidores SSH

Puede usar la herramienta MCP list-servers para obtener todas las configuraciones de servidores SSH disponibles:

Ejemplo de llamada:

{
  "tool": "list-servers",
  "params": {}
}

Ejemplo de respuesta:

[
  { "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" },
  { "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" }
]

🛡️ Consideraciones de seguridad

Este servidor proporciona capacidades potentes para ejecutar comandos y transferir archivos en servidores remotos. Para garantizar que se utilice de forma segura, tenga en cuenta lo siguiente:

• Lista blanca de comandos: Se recomienda encarecidamente utilizar la opción --whitelist para restringir el conjunto de comandos que se pueden ejecutar. Sin una lista blanca, cualquier comando puede ejecutarse en el servidor remoto, lo que puede representar un riesgo de seguridad importante.

• Seguridad de la clave privada: El servidor lee la clave privada SSH en la memoria. Asegúrese de que la máquina que ejecuta ssh-mcp-server sea segura. No exponga el servidor a redes no confiables.

• Denegación de servicio (DoS): El servidor no tiene limitación de velocidad incorporada. Un atacante podría potencialmente lanzar un ataque DoS inundando el servidor con solicitudes de conexión o transferencias de archivos grandes. Se recomienda ejecutar el servidor detrás de un firewall o proxy inverso con capacidades de limitación de velocidad.

• Recorrido de rutas (Path Traversal): El servidor tiene protección incorporada contra ataques de recorrido de rutas en el sistema de archivos local. Sin embargo, sigue siendo importante tener en cuenta las rutas utilizadas en los comandos upload y download.

• Alcance de transferencia local: De forma predeterminada, las transferencias de archivos locales están restringidas al directorio de trabajo actual. Use --allowed-local-paths o allowedLocalPaths en la configuración solo para directorios explícitamente confiables.

🌟 Historial de estrellas