Proporciona una pasarela HTTP centralizada para que los agentes de IA ejecuten comandos SSH y transferencias de archivos SFTP controlados, con registro de auditoría y políticas de comandos.
También conocido como gelse/ssh-mcp
- Stars
- 8
- Herramientas
- 6
- Descargas, 30 días
- —
- Última versión
- 0.3.0
- Último commit
- 16 sept 2026
- Licencia
- MIT
¿Qué es ssh MCP?
Proporciona una pasarela HTTP centralizada para que los agentes de IA ejecuten comandos SSH y transferencias de archivos SFTP controlados, con registro de auditoría y políticas de comandos. Expone 6 herramientas, como ssh_list_servers, ssh_list_allowed_commands, ssh_execute_command.
Resumen generado a partir del README del proyecto
Acerca del MCP server de ssh
Gestionar el acceso a servidores remotos para múltiples agentes de IA es más seguro gracias a una pasarela HTTP centralizada que ofrece capacidades controladas de SSH y SFTP. En lugar de ejecutar procesos locales individuales para cada cliente, este servidor actúa como un punto de entrada único que se conecta a tus objetivos SSH mientras aplica políticas de comandos estrictas y registros de auditoría. Está diseñado para equipos de operaciones que necesitan evitar la proliferación de llaves SSH y mantener visibilidad sobre qué comandos están ejecutando los agentes en su infraestructura.
Los usuarios despliegan el servidor mediante Docker y conectan sus clientes MCP usando Streamable HTTP, autenticándose con API keys. El sistema proporciona seis herramientas específicas: ssh_list_servers, ssh_list_allowed_commands, ssh_execute_command, ssh_check_connection, ssh_download_file y ssh_upload_file. Se distingue por una cadena de autorización de nueve capas, el uso de connection pooling para reutilizar sesiones y limitación de tasa (rate limiting) para evitar que agentes descontrolados saturen los hosts. La configuración se gestiona mediante archivos JSON que admiten hot-reloading para los objetivos y las listas de comandos permitidos.
Qué puedes hacer con él
- 1Auditar la actividad de agentes remotosUn desarrollador puede rastrear cada comando y decisión de autorización tomada por un agente de IA a través de logs estructurados en JSONL.
- 2Restringir permisos de agentesUn administrador puede definir comandos permitidos específicos para diferentes objetivos para asegurar que los agentes solo ejecuten operaciones seguras.
- 3Transferir archivos individuales vía SFTPUn cliente de IA puede mover archivos individuales hacia o desde un servidor remoto utilizando herramientas de transferencia de archivos seguras.
- 4Prevenir la sobrecarga del servidorLa pasarela utiliza rate limiting para garantizar que un solo agente no exceda un número establecido de solicitudes por minuto.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Cómo instalar ssh MCP
Formatos verificados el 10 nov 2026Añadir a CursorAñadir a GooseInstalar ssh MCP en Claude Code
$ claude mcp add --env 'CONFIG_API_TOKEN=<YOUR_CONFIG_API_TOKEN>' ssh-mcp -- docker run -i --rm ghcr.io/gelse/ssh-mcp:0.3.0Instalar ssh MCP en Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"ssh-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/gelse/ssh-mcp:0.3.0"
],
"env": {
"CONFIG_API_TOKEN": "<YOUR_CONFIG_API_TOKEN>"
}
}
}
}Instalar ssh MCP en VS Code
.vscode/mcp.json
{
"servers": {
"ssh-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/gelse/ssh-mcp:0.3.0"
],
"env": {
"CONFIG_API_TOKEN": "<YOUR_CONFIG_API_TOKEN>"
}
}
}
}Instalar ssh MCP en VS Code CLI
$ code --add-mcp '{"name":"ssh-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/gelse/ssh-mcp:0.3.0"],"env":{"CONFIG_API_TOKEN":"<YOUR_CONFIG_API_TOKEN>"}}'Instalar ssh MCP en Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"ssh-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/gelse/ssh-mcp:0.3.0"
],
"env": {
"CONFIG_API_TOKEN": "<YOUR_CONFIG_API_TOKEN>"
}
}
}
}Instalar ssh MCP en Codex
$ codex mcp add ssh-mcp --env 'CONFIG_API_TOKEN=<YOUR_CONFIG_API_TOKEN>' -- docker run -i --rm ghcr.io/gelse/ssh-mcp:0.3.0Instalar ssh MCP en Codex config.toml
~/.codex/config.toml
[mcp_servers.ssh-mcp] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/gelse/ssh-mcp:0.3.0"] [mcp_servers.ssh-mcp.env] CONFIG_API_TOKEN = "<YOUR_CONFIG_API_TOKEN>"
Instalar ssh MCP en Gemini CLI
$ gemini mcp add -s user -e 'CONFIG_API_TOKEN=<YOUR_CONFIG_API_TOKEN>' ssh-mcp docker -- run -i --rm ghcr.io/gelse/ssh-mcp:0.3.0Instalar ssh MCP en Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"ssh-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/gelse/ssh-mcp:0.3.0"
],
"env": {
"CONFIG_API_TOKEN": "<YOUR_CONFIG_API_TOKEN>"
}
}
}
}Herramientas de ssh MCP 6
Detectado desde el READMEssh_list_serversssh_list_allowed_commandsssh_execute_commandssh_check_connectionssh_download_filessh_upload_file
| ssh_list_servers | — | |
| ssh_list_allowed_commands | — | |
| ssh_execute_command | — | |
| ssh_check_connection | — | |
| ssh_download_file | — | |
| ssh_upload_file | — |
Configuración
CONFIG_API_TOKENSecretoBearer token for the configuration API
CONFIG_API_ENABLEDEnable the configuration REST API and web dashboard
CONFIG_DIRDirectory containing ssh-mcp-config.json
LOG_DIRDirectory for JSONL audit logs
| Nombre | Descripción | Tipo |
|---|---|---|
| CONFIG_API_TOKEN | Bearer token for the configuration API | Secreto |
| CONFIG_API_ENABLED | Enable the configuration REST API and web dashboard | |
| CONFIG_DIR | Directory containing ssh-mcp-config.json | |
| LOG_DIR | Directory for JSONL audit logs |
Verificaciones automáticas
Ejecutado 12 nov 2026Informe completo →Pasó nuestras verificaciones automáticas. Esto no es una auditoría de seguridad: lee el código y dale al servidor el acceso más limitado que necesite. Cómo funcionan las verificaciones
- Repositorio de origen vinculado y accesibleAprobado
- Licencia de código abierto (OSI)Aprobado
- Commit o lanzamiento en el último añoAprobado
- El nombre del paquete no es similar a un paquete popularNo verificado
- El endpoint remoto usa HTTPSNo verificado
- Las herramientas destructivas están etiquetadasAprobado
- Sin instrucciones ocultas para el modeloAprobado
- No hay avisos críticos en el paquete ni en sus dependenciasNo verificado
README
Ver en GitHubssh-mcp
A centralized MCP gateway that gives AI agents controlled SSH access over Streamable HTTP.
What problem does this solve?
Most MCP SSH servers run as local stdio processes — one per client, with no shared state, no centralized authorization, and no audit trail. When multiple AI agents need SSH access, each manages its own SSH keys and runs its own process. This creates:
- No centralized access control — every client decides what it can run
- No audit trail — commands are invisible to the ops team
- SSH key sprawl — keys scattered across every agent machine
- No rate limiting — a runaway agent can overwhelm a target
ssh-mcp solves this by deploying a single HTTP gateway. All clients connect to it; it connects to your SSH targets. Authorization, rate limiting, connection pooling, and audit logging happen in one place.
Quick Start
Using the pre-built image (recommended)
docker compose pull
docker compose up -d
The image is published at ghcr.io/gelse/ssh-mcp:latest.
The compose file maps host port 9080 to container port 8080.
Verify the server is running:
curl http://localhost:9080/health
# → {"status": "ok"}
Create a minimal config in config/ssh-mcp-config.json:
{
"version": 1,
"ssh_targets": {
"my-server": {
"host": "10.0.1.10",
"username": "deploy"
}
},
"allowed_commands": {
"default": [
{
"targets": ["*"],
"commands": ["hostname", "uptime", "free", "df"]
}
]
}
}
Generate an API key hash and add it to your config or
secrets.json (see Configuration).
make build
docker compose up -d --build
What you can do (tools)
Six MCP tools are available over Streamable HTTP:
| Tool | Description |
|---|---|
ssh_list_servers |
List configured SSH targets |
ssh_list_allowed_commands |
Show allowed commands for a target |
ssh_execute_command |
Execute a command on a remote server |
ssh_check_connection |
Test SSH connectivity to a target |
ssh_download_file |
Download a file via SFTP |
ssh_upload_file |
Upload a file via SFTP |
Tool Naming Convention
All tools follow the pattern ssh_<verb>_<noun>:
ssh_list_servers— list resourcesssh_list_allowed_commands— list permissionsssh_execute_command— perform an actionssh_check_connection— verify connectivityssh_download_file/ssh_upload_file— file transfer
See examples/README.md for usage examples
including curl commands and Python client code.
What's configurable
ssh-mcp is configured via JSON files with hot-reload (15 s poll, 2 s debounce). Key areas:
| Area | Details |
|---|---|
| SSH targets | Host, port, username, key, password |
| Command policies | Block patterns, per-key/network allowlists |
| Connection pool | Max connections, idle timeout, concurrency |
| Rate limiting | Per-IP sliding window (default 60 req/min) |
| Logging | JSONL with rotation, gzip, multiple targets |
| SFTP | Sandbox root, path length limits |
Full reference: docs/CONFIGURATION.md
| File | Purpose |
|---|---|
ssh-mcp-config.json |
Main config |
config.schema.json |
JSON Schema for validation |
secrets.json |
Passwords and API key hashes |
MCP_SSH_* env vars |
Overrides for any setting |
Why not just raw SSH / other MCP servers?
ssh-mcp adds a layered authorization chain (9 ordered layers) between every client request and every SSH command. Per-API-key and per-network rules let different agents get different permissions on different servers — without touching the underlying SSH accounts.
Additional protections:
- Circuit breakers isolate failing targets with exponential backoff
- Rate limiting prevents runaway agents from overwhelming hosts
- Structured audit logs trace every command, client, IP, and authorization decision
- Connection pooling reuses SSH sessions across requests
- Input sanitization and dangerous-pattern detection block shell injection attempts
Architecture: ARCHITECTURE.md
Security model: docs/SECURITY.md
What it is NOT
- Not an interactive shell — commands are executed individually with structured output
- Not a file manager — SFTP supports single-file download and upload only (no directory listing or recursive transfer)
- Not a firewall / network ACL — authorization is command-level, not network-level
- Does not reduce SSH account privileges — if a command is allowed, the SSH user executes it with whatever privileges that account has
Not yet / known gaps
Fixable with contribution:
- SFTP is single-file only — no directory listing or recursive transfer
- No TLS termination — run Traefik or nginx in front
- No OAuth or mTLS app-layer authentication
- Rate limiter settings are not hot-reloadable (set at boot)
Architectural:
- Config API dashboard login sessions are in-memory only — they don't survive restarts and the API is single-instance (config changes themselves persist to the config file normally)
- No tamper protection for audit logs
Observability
- Health:
GET /health— returns{"status": "ok"} - Metrics:
GET /metrics— Prometheus exposition format - Logging: Structured JSONL with request correlation
Full reference: docs/OBSERVABILITY.md
Config API & Dashboard
An optional web dashboard for managing configuration without
editing JSON files. Enable with CONFIG_API_ENABLED=true.
Full reference: docs/CONFIG-API.md
FAQ
Dashboard returns 401 over HTTP
The session cookie defaults to Secure (HTTPS only). For local
HTTP testing, set:
environment:
- CONFIG_API_SESSION_COOKIE_SECURE=false
Then restart the container.
How do MCP clients connect?
Connect to http://host:9080/mcp using the Streamable HTTP
transport. Pass your API key via X-API-Key or
Authorization: Bearer header.
How do I generate an API key hash?
docker compose exec mcp-ssh python -c \
"from lib.crypto import hash_api_key; print(hash_api_key('your-key'))"
# → pbkdf2:sha256:100000$<salt>$<hash>
Or use the hash utility in the Config API dashboard.
How does hot reload work?
The config file is polled every 15 seconds with a 2-second debounce. Changes to targets, commands, and settings take effect without restart. Rate limiter and log target settings require a restart.
Why was my command denied?
Commands are evaluated through a 9-layer authorization chain.
The matched_via field in logs shows which layer denied.
See Security Model for the full chain.
How does rate limiting work?
Per-IP sliding window, default 60 requests per 60 seconds.
Exceeding the limit returns HTTP 503. Configure via
settings.rate_limit in the config file.
Where do logs go?
Logs are written to the /logs volume (mapped from ./logs).
The active log file is ssh-mcp.log in JSONL format with
optional gzip rotation.
Troubleshooting basics
# Check server health
curl http://localhost:9080/health
# Validate config
make config-test
# Check logs
docker compose logs mcp-ssh
Documentation
| Document | Description |
|---|---|
ARCHITECTURE.md |
System design and data flow |
docs/SECURITY.md |
Security model and threat analysis |
docs/CONFIGURATION.md |
Full config reference |
docs/CONFIG-API.md |
Config API & dashboard |
docs/OBSERVABILITY.md |
Health, metrics, logging |
CONTRIBUTING.md |
Development and contribution guide |
CHANGELOG.md |
Release history |
examples/ |
Config examples and client code |
Development
# Unit tests
make test
# Integration tests (builds Docker image)
make integrationtest
See CONTRIBUTING.md for the full development
guide, coding conventions, and PR workflow.
Roadmap
No public roadmap. See Not yet / known gaps for current limitations and opportunities.
License
Preguntas sobre ssh MCP
¿Cómo agrego ssh MCP a Claude Code?
Ejecuta claude mcp add --env 'CONFIG_API_TOKEN=<YOUR_CONFIG_API_TOKEN>' ssh-mcp -- docker run -i --rm ghcr.io/gelse/ssh-mcp:0.3.0 en tu terminal. Añade --scope user para que esté disponible en todos los proyectos.
¿Cómo agrego ssh MCP a Cursor?
Abre ~/.cursor/mcp.json y añade el servidor en mcpServers, usando la configuración de Cursor que se muestra en la sección de instalación de arriba.
¿Qué herramientas proporciona ssh MCP?
Expone 6 herramientas, incluidas ssh_list_servers, ssh_list_allowed_commands, ssh_execute_command, ssh_check_connection, ssh_download_file.
¿Cómo se conectan los clientes MCP?
Los clientes se conectan al servidor utilizando el transporte Streamable HTTP en el host y puerto especificados, pasando una API key en el header.
¿Soporta shells interactivas?
No, el servidor no es una shell interactiva; los comandos se ejecutan individualmente con salida estructurada.
¿Cómo funciona el hot reload?
El archivo de configuración se consulta cada 15 segundos con un debounce de 2 segundos, lo que permite que los cambios surtan efecto sin necesidad de reiniciar.