ssh MCP server

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	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 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:

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

MIT