MCP Server SSH Client

Un servidor MCP local que se conecta de forma segura a servidores remotos a través de SSH, actuando como un proxy para comandos MCP.

GitHub
9
Prueba este MCPPatrocinado

Documentación

MCP Server SSH Client

PyPI version Python Versions License: MIT

Un servidor de Protocolo de Contexto de Modelo (cliente SSH remoto) que se conecta a servidores MCP remotos a través de SSH. Este cliente permite acceder y utilizar herramientas MCP alojadas en servidores remotos, proporcionando un canal seguro para la comunicación MCP.

Características

  • Conéctate a cualquier servidor MCP a través de SSH
  • Proxy de todos los comandos del protocolo MCP a través de un canal SSH seguro
  • Soporte para autenticación basada en claves
  • Soporte para capacidades MCP, incluyendo herramientas, prompts y recursos

Instalación

En un proyecto de Python gestionado por uv, añade a las dependencias:

uv add m2m-mcp-server-ssh-client

Alternativamente, para proyectos que usan pip para las dependencias:

pip install m2m-mcp-server-ssh-client

Para instalar directamente desde el código fuente:

git clone https://github.com/Machine-To-Machine/m2m-mcp-server-ssh-client.git
cd m2m-mcp-server-ssh-client
pip install -e .

Para ejecutar el servidor dentro de tu proyecto:

uv run m2m-mcp-server-ssh-client

Casos de Uso Comunes

1. Inicio Rápido con Servidor de Demostración

Mantenemos un servidor de demostración público con varias herramientas MCP ya configuradas y listas para usar. (Este servidor estará disponible hasta que lancemos nuestro registro abierto y descentralizado).

Este servidor de demostración tiene múltiples servidores MCP, incluyendo herramientas de HackerNews, MLB Stats API y Formula 1 API para que experimentes.

Claude

Para conectar Claude a este servidor, simplemente añade lo siguiente a la configuración de Claude Desktop.

"mcpServers": {
  "remote-mcp-tools": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "mcp-beta.machinetomachine.ai", 
      "--port", "8022", 
      "--use-key-server"
    ]
  }
}

Línea de comandos

# Connect to the M2M public demo server with automatic key exchange
uv run m2m-mcp-server-ssh-client --host mcp-beta.machinetomachine.ai --use-key-server

2. Pruebas de Desarrollo Local

Para configurar tu propio servidor SSH, consulta m2m-mcp-server-ssh-server.

Para pruebas locales con tus propias herramientas MCP:

# Connect to a local MCP SSH server
uv run m2m-mcp-server-ssh-client

El comando anterior intentará conectarse a un servidor SSH local que escucha en el puerto 8022.

Al probar localmente, puedes simplificar el intercambio de claves usando el servidor de claves:

# Use the key server for automatic key management (if server has --run-key-server enabled)
uv run m2m-mcp-server-ssh-client --use-key-server

El comando anterior intentará usar el servidor de claves que se ejecuta en el puerto 8000.

3. Conexión a Servidor Remoto

Conéctate a tu propio servidor MCP alojado:

# Using existing SSH keys
uv run m2m-mcp-server-ssh-client --host your-server.example.com --client-key ~/.ssh/your_key --known-hosts ~/.ssh/known_hosts

Puedes simplificar el intercambio de claves ejecutando el servidor de claves en tu servidor remoto y configurándolo en el cliente.

Uso con Plataformas de IA

Integración con Claude Desktop

Añade esto a la configuración de Claude Desktop:

"mcpServers": {
  "remote-mcp-tools": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "mcp-beta.machinetomachine.ai", 
      "--port", "8022", 
      "--use-key-server"
    ]
  }
}

MCP Inspector

Para depurar o explorar las herramientas disponibles:

npx @modelcontextprotocol/inspector -- uvx m2m-mcp-server-ssh-client --host mcp-beta.machinetomachine.ai --port 8022 --use-key-server

Uso

Opciones de Línea de Comandos

  • --host: Host del servidor SSH remoto (predeterminado: "localhost")
  • --port: Puerto del servidor SSH remoto (predeterminado: 8022)
  • --username: Nombre de usuario SSH (predeterminado: "mcp")
  • --client-key: Archivo de clave privada del cliente (predeterminado: "~/.ssh/m2m_mcp_server_ssh_client")
  • --known-hosts: Ruta al archivo de hosts conocidos (predeterminado: "~/.ssh/known_hosts")
  • --passphrase: Frase de contraseña para la clave privada (predeterminado: None)
  • --disable-host-key-checking: Omitir verificación de firma del servidor (predeterminado: False)
  • --log-level: Establecer nivel de registro (predeterminado: INFO)

Ejemplos Detallados

Conexión Básica a un Servidor Remoto

Conéctate a un servidor MCP remoto (servidor SSH) que se ejecuta en el puerto 8022:

uvx m2m-mcp-server-ssh-client --host mcp.example.com

Uso de una Clave SSH Personalizada

Especifica una clave SSH particular para la autenticación:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --client-key ~/.ssh/mcp_custom_key

Si tu clave está protegida con frase de contraseña:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --client-key ~/.ssh/mcp_custom_key --passphrase "your-passphrase"

Modo de Depuración para Solución de Problemas

Habilita el registro detallado para solucionar problemas de conexión:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --log-level DEBUG

Integración con Servidor de Claves

El Cliente SSH MCP puede usar un servidor de claves para el intercambio y verificación dinámica de claves:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --use-key-server

Al usar un servidor de claves:

  1. El cliente obtiene la clave pública del servidor desde http://host:key-server-port/server_pub_key
  2. El cliente registra su clave pública con el servidor en http://host:key-server-port/register
  3. Se crea un archivo temporal known_hosts para la conexión SSH

Esta función es mutuamente excluyente con --known-hosts y --disable-host-key-checking.

Deshabilitar la Verificación de Clave de Host

⚠️ Advertencia de Seguridad: Usar --disable-host-key-checking hace que tu conexión sea vulnerable a ataques de intermediario (man-in-the-middle). Solo usa esta opción en redes de confianza o con fines de desarrollo/pruebas.

uvx m2m-mcp-server-ssh-client --host localhost --disable-host-key-checking

Configurar para Claude Desktop

Añade a tu configuración de Claude:

"mcpServers": {
  "remote-servers": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "example.com", 
      "--port", "8022", 
      "--username", "mcp"
    ]
  }
}

Para una configuración más segura con una clave específica:

"mcpServers": {
  "remote-servers": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client",
      "--host", "mcp-server.example.com",
      "--port", "8022",
      "--username", "claude-mcp",
      "--client-key", "~/.ssh/claude_mcp_key",
      "--known-hosts", "~/.ssh/mcp_remote_server"
    ]
  }
}

Cómo Funciona

El Cliente SSH del Servidor MCP establece una conexión SSH a un servidor remoto que ejecuta el Servidor SSH del Servidor MCP para herramientas MCP, es decir, m2m-mcp-server-ssh-server. Luego:

  1. Crea un servidor proxy local que refleja las capacidades del servidor MCP remoto
  2. Reenvía todas las solicitudes MCP al servidor remoto a través de la conexión SSH
  3. Devuelve las respuestas del servidor remoto al cliente local

Esto te permite usar herramientas que se ejecutan en máquinas remotas como si estuvieran instaladas localmente.

Flujo de Autenticación

%%{init: {'theme':'default', 'themeVariables': { 'primaryColor': '#5D8AA8', 'primaryTextColor': '#fff', 'primaryBorderColor': '#1F456E', 'lineColor': '#5D8AA8', 'secondaryColor': '#006400', 'tertiaryColor': '#fff' }}}%%

sequenceDiagram
    participant Host as MCP Host<br>(Claude/Cursor)
    participant Client as MCP SSH Client
    participant KeySrv as Key Server<br>(HTTP API)
    participant SSHSrv as MCP SSH Server
    participant MCP as MCP Servers

    Note over Client,SSHSrv: Initial Key Exchange & Authentication
    
    Client->>Client: Generate SSH key pair<br>if does not exist
    Client->>KeySrv: GET /server_pub_key
    KeySrv->>Client: Return server's public key
    Client->>Client: Store server key in<br>temporary known_hosts
    Client->>KeySrv: POST /register<br>{client_pub_key: "ssh-ed25519 AAAA..."}
    KeySrv->>SSHSrv: Store client public key<br>in authorized keys
    KeySrv->>Client: {status: "success"}
    
    Note over Client,SSHSrv: Secure SSH Connection
    
    Client->>SSHSrv: SSH handshake with<br>client key authentication
    SSHSrv->>SSHSrv: Verify client key<br>against authorized keys
    SSHSrv->>Client: Authentication successful
    
    Note over Client,SSHSrv: MCP Communication
    
    Host->>Client: JSONRPC request
    Client->>SSHSrv: Forward request<br>over SSH tunnel
    SSHSrv->>MCP: Route request to<br>appropriate MCP server
    MCP->>SSHSrv: Process and return results
    SSHSrv->>Client: Send response over SSH
    Client->>Host: Return JSONRPC response
    
    Note over Client,SSHSrv: Session Management
    
    alt Session Termination
        Host->>Client: Close connection
        Client->>SSHSrv: Terminate SSH session
        SSHSrv->>SSHSrv: Clean up resources
    end

Consideraciones de Seguridad

  • Usa siempre la verificación de clave de host en entornos de producción
  • Usa claves SSH protegidas con frase de contraseña para mayor seguridad
  • Considera usar claves SSH dedicadas para conexiones MCP
  • Establece permisos apropiados (600) para tus archivos de clave SSH
  • Usa un usuario dedicado con privilegios limitados en el servidor remoto

Solución de Problemas Comunes

Conexión Rechazada

Error running MCP SSH client: [Errno 111] Connection refused

Solución: Verifica que el host y el puerto sean correctos y que el servicio SSH esté en ejecución.

Error de Autenticación

Error running MCP SSH client: Authentication failed

Solución: Comprueba la ruta del archivo de clave. Asegúrate de que el servidor remoto tenga instalada tu clave pública.

Falló la Verificación de Clave de Host

Error running MCP SSH client: Host key verification failed

Solución: Añade la clave de host a tu archivo known_hosts o usa --disable-host-key-checking (solo para pruebas).

Dependencias

  • anyio (>=4.5.0)
  • asyncssh (>=2.20.0)
  • mcp (>=1.1.3)
  • pydantic (>=2.0.0)

Desarrollo

Configurar Entorno de Desarrollo

git clone https://github.com/Machine-To-Machine/m2m-mcp-server-ssh-client.git
cd m2m-mcp-server-ssh-client
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Calidad de Código

# Run linting
uv run ruff check .

# Run formatting check
uv run ruff format --check .

# Run security checks
uv run bandit -r src/

Depuración

Puedes usar el inspector MCP para depurar el cliente:

npx @modelcontextprotocol/inspector uvx m2m-mcp-server-ssh-client --host example.com

Para depuración avanzada, usa el siguiente flujo de trabajo:

  1. Inicia el cliente con --log-level DEBUG
  2. Comprueba los parámetros de conexión SSH y el proceso de handshake
  3. Si usas claves personalizadas, verifica las rutas y permisos correctos
  4. Usa ssh -v directamente para probar primero la conectividad básica

Contribuciones

Damos la bienvenida a contribuciones para ayudar a expandir y mejorar m2m-mcp-server-ssh-client. Ya sea que quieras añadir nuevas funciones, mejorar la funcionalidad existente o mejorar la documentación, tu aportación es valiosa.

¡Las solicitudes de extracción (pull requests) son bienvenidas! No dudes en contribuir con nuevas ideas, correcciones de errores o mejoras.

Directrices de Contribución

  1. Haz un fork del repositorio
  2. Crea una rama de características: git checkout -b feature-name
  3. Haz commit de tus cambios: git commit -am 'Add some feature'
  4. Haz push a la rama: git push origin feature-name
  5. Envía una solicitud de extracción (pull request)

Licencia

Licencia MIT - Consulta el archivo LICENSE para más detalles.

Autores

  • Machine To Machine