Servidor SSH MCP (paramiko)

Servidor SSH MCP basado en Paramiko, capaz de ejecutar comandos en máquinas remotas y mover archivos mediante SFTP. Está disponible con dos tipos de transporte, seleccionables mediante una variable de entorno / un parámetro:

• http – punto final MCP streamable-http en la ruta /mcp (al que se conecta Cherry Studio), además de una interfaz documentada OpenAPI/Swagger (/docs, /openapi.json).

• stdio – transporte clásico de MCP stdio (para arranque local o docker exec).

Importante sobre los puertos: el 2222 es el puerto del servidor MCP, al que se conecta Cherry Studio. NO es el puerto SSH de la máquina remota. El puerto SSH de la máquina remota suele ser el 22 (SSH_PORT). Por lo tanto: Cherry Studio → http://<host-IP>:2222/mcp → servidor MCP → paramiko → puerto SSH 22 de la máquina remota.

Herramientas MCP disponibles

Herramientas sin estado (stateless): operaciones simples y de una sola vez

Herramientas de sesión interactiva con estado: shell en vivo

Estas mantienen abierto un shell en vivo, donde el estado se conserva entre llamadas (cambio de directorio después de cd, variables exportadas y manejo de prompts interactivos: contraseña de sudo, [Y/n] de apt, etc.).

Las descripciones de las herramientas (docstrings) incluyen deliberadamente una guía muy detallada, en inglés sencillo, del tipo "USE THIS WHEN...", para que el modelo consumidor sepa claramente cuándo y cómo usar cada herramienta.

Todos los parámetros de las herramientas (host, port, username, password, private_key, private_key_path, passphrase, timeout) pueden especificarse:

• por llamada, por separado, o

• como valor predeterminado en el archivo .env (variables SSH_*). Lo que no se indique en la llamada se toma automáticamente de las variables de entorno SSH_*.

La autenticación admitida es: contraseña y clave (PEM en línea o ruta de archivo, con contraseña opcional). El servidor acepta automáticamente las claves de host desconocidas (AutoAddPolicy) para que la automatización sea fluida.

Related MCP server: SSH MCP Server

Uso sin estado vs. con estado (interactivo)

¿Cuándo usar cada uno?

• Un único comando independiente (p. ej. ls, uptime, df -h) → ssh_execute. Cada llamada abre una conexión nueva, ejecuta un comando y la cierra. No hay memoria: cd y export no sobreviven a la siguiente llamada y tampoco se puede responder a un prompt interactivo.

• Cualquier tarea interactiva o de varios pasos (conservar el estado después de cd/export, escribir la contraseña de sudo, responder [Y/n] a apt, comandos encadenados) → sesión interactiva: ssh_open_session → ssh_send → ssh_read → ssh_close_session.

Flujo de trabajo recomendado (sesión)

1. ssh_open_session – recibirás un session_id (y el banner de entrada / el primer prompt en initial_output).

2. ssh_send – escribe un comando o responde a un prompt. El session_id se debe proporcionar en todas las llamadas. Por defecto envía también Enter.

3. ssh_read (opcional) – para comandos lentos o de larga ejecución, recopila más salida sin enviar.

4. ssh_close_session – cuando termines, cierra la sesión.

Con ssh_list_sessions puedes ver en cualquier momento las sesiones abiertas (host, usuario, inactividad), si has perdido algún session_id.

Ejemplos (a través de los endpoints REST)

Apertura de una sesión:

curl -X POST http://localhost:2222/api/ssh/session/open \
  -H "Content-Type: application/json" \
  -d '{"host":"192.168.1.100","username":"user","password":"secret"}'
# -> {"ok":true,"session_id":"<ID>", "initial_output":"...prompt..."}

Cambio de directorio que se conserva (mantener el estado):

curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"cd /var/log && pwd"}'
# a következő ssh_send már a /var/log-ban futna

Comando sudo y respuesta al prompt de contraseña:

# 1) elindítod a sudo parancsot
curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"sudo apt-get update"}'
# 2) a kimenetben megjelenik a "[sudo] password for user:" prompt -> beküldöd a jelszót
curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"my_sudo_password"}'

Respuesta a la pregunta [Y/n] de apt:

curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"sudo apt-get install htop","read_timeout":5}'
# amikor jön a "Do you want to continue? [Y/n]" kérdés:
curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"Y"}'

Cierre de una sesión:

curl -X POST http://localhost:2222/api/ssh/session/close \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>"}'

Timeouts / inactividad / errores: cada operación de sesión cierra de forma oportunista las sesiones inactivas durante más de SSH_SESSION_IDLE_TIMEOUT (por defecto, 600 s), así como las que han perdido su canal. A la vez puede haber un máximo de SSH_MAX_SESSIONS sesiones abiertas (por defecto, 20); si se alcanza el límite, se devuelve un mensaje de error claro. Si un session_id ya no existe, la respuesta indica exactamente qué hay que hacer (abre una nueva o revisa ssh_list_sessions).

Estructura del proyecto

ssh-mcp-server/
├── app/
│   ├── __init__.py
│   ├── ssh_ops.py     # paramiko SSH/SFTP műveletek (közös logika)
│   └── server.py      # MCP tool-ok + FastAPI/OpenAPI + transport választás
├── requirements.txt
├── Dockerfile
├── docker-compose.yml # 2222:2222 publikálás
├── .env.example
└── README.md

1. Inicio rápido con Docker (recomendado)

Preparación

cd ssh-mcp-server
cp .env.example .env
# szerkeszd a .env-et: add meg a távoli gép adatait (SSH_HOST, SSH_USERNAME, stb.)

Build e inicio (modo HTTP)

docker compose up -d --build

Esto inicia el servidor en modo HTTP y publica el puerto 2222 en el host (ports: "2222:2222").

Comprobación

curl http://localhost:2222/health
# {"status":"ok","service":"ssh-mcp-server","mcp_endpoint":"/mcp"}

• Swagger UI (en el navegador): http://localhost:2222/docs

• OpenAPI JSON: http://localhost:2222/openapi.json

• Punto final MCP (Cherry Studio): http://<host-IP>:2222/mcp

Parada

docker compose down

2. Modo HTTP manual (sin Docker, para desarrollo)

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export TRANSPORT=http HOST=0.0.0.0 PORT=2222
python -m app.server

3. Modo stdio

Con el servidor ejecutándose en un contenedor, mediante docker exec:

docker exec -i -e TRANSPORT=stdio ssh-mcp-server python -m app.server

O directamente, sin Docker:

TRANSPORT=stdio python -m app.server

4. Integración con Cherry Studio

A) Modo HTTP (streamable-http) — recomendado, funciona también a través de la red

El contenedor se ejecuta en Docker en tu ordenador portátil, y Cherry Studio usa la IP del host y el puerto 2222.

1. Inicia el servidor: docker compose up -d --build.

2. Averigua la IP de la máquina (host) donde se ejecuta Docker:

   • Linux: hostname -I → p. ej. 192.168.1.50

   • Si Cherry Studio se ejecuta en la misma máquina, también sirve localhost / 127.0.0.1.

3. Cherry Studio → Configuración (Settings) → MCP Servers → Add / Nuevo servidor.

4. Introduce los siguientes datos:

   • Type / Tipo: Streamable HTTP (criba no aparece, SSE / HTTP)

   • URL / Endpoint: http://<host-IP>:2222/mcp

     • p. ej. http://192.168.1.50:2222/mcp

     • en la misma máquina: http://localhost:2222/mcp

5. Guárdalo y habilita el servidor. Cherry Studio cargará las herramientas ssh_test, ssh_execute, ssh_upload y ssh_download.

Si te conectas desde una máquina remota, asegúrate de que el puerto 2222 sea accesible (permítelo en el cortafuegos) y de que Docker escuche en 0.0.0.0 (así lo hace por defecto).

B) Modo stdio

Si Cherry Studio espera un servidor MCP por stdio (lanzando un comando):

• Command: docker

• Arguments:

  exec -i -e TRANSPORT=stdio ssh-mcp-server python -m app.server

(Para ello, el contenedor ssh-mcp-server debe estar en ejecución: docker compose up -d.)

5. Configuración de .env

Autenticación con clave en Docker

Monta las claves en el contenedor y configura la ruta que corresponde. En docker-compose.yml, quita el comentario de la línea volumes:

    volumes:
      - ./keys:/keys:ro

y luego en .env:

SSH_PRIVATE_KEY_PATH=/keys/id_ed25519

6. Endpoints REST para probar (OpenAPI)

El modo HTTP ofrece, junto al punto final MCP de Cherry Studio, también endpoints REST; estos realizan las mismas operaciones SSH y son muy útiles con curl o desde el Swagger UI:

Ejemplo (ejecución de un solo comando sin estado):

curl -X POST http://localhost:2222/api/ssh/execute \
  -H "Content-Type: application/json" \
  -d '{"host":"192.168.1.100","username":"user","password":"secret","command":"uname -a"}'

Notas de seguridad

• Los secretos nunca están en el código — todo se lee desde .env / parámetros de invocación.

• El archivo .env está excluido por .dockerignore y normalmente también por el .gitignore — no lo subas en el control version.

• El servidor usa AutoAddPolicy (aceptación automática de claves de host desconocidas).

  • En redes privadas es cómodo; en entornos más estrictos conviene usar claves de host conocidas.

  • El puerto MCP 2222 solo debe exponerse en redes de confianza.