ssh-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 Naming Convention

All tools follow the pattern ssh_<verb>_<noun>:

• ssh_list_servers — list resources
• ssh_list_allowed_commands — list permissions
• ssh_execute_command — perform an action
• ssh_check_connection — verify connectivity
• ssh_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:

Full reference: docs/CONFIGURATION.md

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

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

MIT