ssh-mcp

A centralized MCP gateway that gives AI agents controlled access to SSH infrastructure over Streamable HTTP.

ssh-mcp runs as a single HTTP service. Multiple AI clients — agents, CI pipelines, dashboards — connect to one gateway. SSH credentials stay on the gateway. Authorization policies, audit logging, and rate limiting are applied centrally before any SSH command executes.

Table of Contents

• Architecture
• Why ssh-mcp?
• Multi-agent access control
• The Problem
• Use Cases
• Security Model
• Quick Start
• MCP Client Configuration
• Tools
• Configuration
• Observability
• Configuration API
• Deployment
• Limitations and Threat Model
• Development
• Roadmap
• License

Architecture

Local stdio MCP (common pattern)

AI client
   │
   ▼
local MCP process ──► SSH target

Each agent runs its own process. SSH credentials live on every machine. No centralized control.

ssh-mcp (centralized HTTP gateway)

AI clients ───────┐
CI agents ────────┼──► ssh-mcp ──► SSH targets
Dashboards ───────┘      │
                         ├─ API-key authentication
                         ├─ per-client authorization
                         ├─ rate limiting
                         ├─ audit logging
                         └─ connection pooling

A single deployment serves all clients. Credentials, policies, and logs live in one place.

Why ssh-mcp?

• Centralized HTTP gateway — One deployment serves all AI agents, CI pipelines, and dashboards over Streamable HTTP
• Per-client authorization — Different API keys grant different command sets on different servers
• Layered command policies — Block patterns, dangerous-shell detection, and per-target allowlists work together
• Centralized SSH access — SSH credentials live on the gateway, not on every agent's machine
• Audit trail — Every command, every client, every result — structured JSONL logs with request tracing
• Operational resilience — Connection pooling, circuit breakers, and retry with exponential backoff
• Observability — Prometheus metrics and health endpoints for monitoring

Multi-agent access control

Different agents need different permissions. ssh-mcp enforces this at the gateway:

monitoring agent  →  API key A  →  read-only commands  →  all servers
deployment agent  →  API key B  →  deploy commands      →  web servers only
database agent    →  API key C  →  db commands           →  database server only

                  ┌─ monitoring agent (read-only, all servers)
                  ├─ deployment agent (deploy commands, web only)
MCP clients ──────┼─ database agent (db commands, db server only)
                  └─ ...
                         │
                         ▼
                      ssh-mcp
                         │
                  centralized policies
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
             web         db      monitoring
           servers    servers     servers

A minimal config demonstrating this setup:

{
  "version": 1,
  "ssh_targets": {
    "web-1": { "host": "10.0.1.10", "username": "deploy" },
    "db-1":  { "host": "10.0.1.20", "username": "dbadmin" }
  },
  "allowed_commands": {
    "default": {
      "web-1": { "allow": ["uptime", "df -h", "free -m"] }
    },
    "api_keys": {
      "deploy-key": {
        "web-1": { "allow": ["systemctl restart app", "deploy *"] }
      },
      "db-key": {
        "db-1": { "allow": ["systemctl restart postgres", "pg_dump *"] }
      }
    }
  }
}

The Problem

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, CI pipelines, or dashboards need SSH access, each one independently manages its own SSH keys and runs its own MCP 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 machine running an agent
• No rate limiting — a runaway agent can overwhelm a target
• No connection pooling — each client opens and closes SSH sessions independently

ssh-mcp solves this by deploying a single MCP server as an HTTP gateway. All clients connect to it; it connects to your SSH targets. Authorization, authentication, rate limiting, connection pooling, and audit logging happen in one place.

Use Cases

Multi-Agent Server Management

Run a team of AI agents with different access levels. The deployment agent can systemctl restart nginx on web servers; the monitoring agent can journalctl everywhere; the database agent can only run psql on the DB server. Each agent authenticates with its own API key; each key has its own permission set.

CI/CD Pipeline Integration

Point your CI pipeline at ssh-mcp instead of managing SSH keys on every runner. A single API key per pipeline, network-based rules for your CI subnet, and command allowlists ensure your deployment scripts run exactly what they should — nothing more.

Centralized Log and Config Retrieval

Use ssh_download_file to pull logs, config files, or database dumps from remote servers without leaving your MCP client. The 8-layer path validation and sandbox root settings ensure file transfers stay within safe boundaries.

Server Health Dashboards

Build an MCP-powered dashboard that queries uptime, free, df, and ps across your fleet. The connection pool reuses SSH sessions, the circuit breaker isolates failing targets, and Prometheus metrics at /metrics feed your existing monitoring stack.

Compliance and Audit

Every command is logged with structured JSONL: who ran what, on which server, from which IP, whether it was allowed, and how long it took. The matched_via field traces exactly which authorization layer made the decision. Config changes are logged separately with before/after state.

Security Model

ssh-mcp applies defense-in-depth at every layer. The full security model is documented in docs/SECURITY.md.

Security boundary: ssh-mcp adds an authorization, authentication, and auditing layer in front of SSH. It does not replace the permissions of the underlying SSH accounts. If a command is allowed, the SSH user executes it with whatever privileges that account has. The gateway itself should be protected with TLS and network access controls. Logs may contain command output and should be treated accordingly.

Command Authorization Chain

Commands are evaluated through an ordered, layered chain. If any layer denies, the request stops there:

Authentication

API keys are sent via X-API-Key or Authorization: Bearer headers. Keys are hashed with PBKDF2-HMAC-SHA256 (100,000 iterations, random 16-byte salt) and verified with constant-time comparison. Raw keys are never stored.

Input Sanitization

Commands, target names, and log strings are sanitized before processing: null bytes stripped, control characters removed, NFKC-normalized, and run through ReDoS protection for block_patterns.

Path Traversal Prevention

SFTP transfers go through 8-layer path validation including null-byte checks, control-character stripping, dot-segment normalization, symlink resolution, and sandbox-root enforcement.

Rate Limiting

Sliding-window rate limiter per client IP (60 requests / 60 seconds, /health exempt). Violations return HTTP 429 with Retry-After.

Rate limiting is configurable under settings.rate_limit:

"settings": {
  "rate_limit": {
    "enabled": true,                        // set false to disable entirely
    "max_requests_per_minute": 60,          // max requests per client IP in the window
    "window_seconds": 60.0,                 // sliding-window duration
    "cleanup_interval_seconds": 300.0       // expired-entry GC interval
  }
}

Note: the rate limiter is built once at container startup from the initial config and is not rebuilt on config hot-reload. To disable rate limiting you must set settings.rate_limit.enabled to false in the config present at boot (e.g. config/ssh-mcp-config.json in the mounted volume). This is useful for high-volume clients or test suites that issue many requests from a single IP.

Quick Start

Prerequisites

• Docker with Docker Compose
• An SSH key pair (or per-target passwords) for the servers you want to reach

1. Set up the directory

mkdir -p config logs
ssh-keygen -t ed25519 -f ssh_key -N ""
cp default-config.json config/ssh-mcp-config.json

2. Add an SSH target

Open config/ssh-mcp-config.json and add one target:

{
  "version": 1,
  "ssh_targets": {
    "web-server": {
      "host": "192.168.1.10",
      "port": 22,
      "username": "deploy",
      "private_key": "/app/ssh_key"
    }
  },
  "block_patterns": [ "\\brm\\s+-rf\\b", "\\bdd\\s+if=" ],
  "allowed_commands": {
    "default": [
      { "targets": ["*"], "commands": ["hostname", "uptime", "free", "df", "ps", "ls", "cat"] }
    ]
  },
  "settings": {}
}

3. Start the server

docker compose up -d --build

4. Verify it's running

curl http://localhost:9080/health
# {"status": "ok", "connection_pool": {...}}

5. Connect an MCP client

Any MCP client supporting Streamable HTTP can connect. Point it at http://localhost:9080/mcp with an API key header. See MCP Client Configuration for details.

6. List servers and run a command

curl -X POST http://localhost:9080/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ssh_list_servers",
      "arguments": {}
    }
  }'

curl -X POST http://localhost:9080/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "ssh_execute_command",
      "arguments": {"server_name": "web-server", "command": "uptime"}
    }
  }'

MCP Client Configuration

Any MCP client supporting Streamable HTTP transport can connect. The configuration format varies by client — use the URL and headers below.

Generic Streamable HTTP Configuration

{
  "mcpServers": {
    "ssh": {
      "url": "http://localhost:9080/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Python Client

import requests

MCP_URL = "https://ssh-mcp.example.com/mcp"
API_KEY = "your-api-key"


def call_tool(name: str, arguments: dict) -> dict:
    response = requests.post(
        MCP_URL,
        headers={
            "Content-Type": "application/json",
            "X-API-Key": API_KEY,
        },
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {"name": name, "arguments": arguments},
        },
    )
    response.raise_for_status()
    return response.json()


print(call_tool("ssh_list_servers", {}))
print(call_tool("ssh_execute_command", {
    "server_name": "web-server",
    "command": "uptime",
}))

Raw JSON-RPC

Send tool calls as JSON-RPC tools/call requests to /mcp:

curl -X POST http://localhost:9080/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ssh_execute_command",
      "arguments": {"server_name": "web-server", "command": "uptime"}
    }
  }'

Tools

All tool calls are JSON-RPC tools/call requests to /mcp. All tools return a string (JSON or plain text).

Tool Naming Convention

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

The ssh_ prefix is redundant across all tools but is intentionally preserved for MCP API contract stability — renaming tools would break existing MCP client integrations that reference tool names by string. New tools added in the future must follow this same convention.

Examples

# List available servers
call_tool("ssh_list_servers", {})
# {"web-server": {"host": "192.168.1.10", "port": 22, "username": "deploy"}}

# List what this client can run on web-server
call_tool("ssh_list_allowed_commands", {"server_name": "web-server"})
# ["cat", "df", "du", "free", "grep", "head", "hostname", ...]

# Execute a command
call_tool("ssh_execute_command", {
    "server_name": "web-server",
    "command": "uptime",
})
# " 07:12:33 up 10 days,  2:15,  1 user,  load average: 0.08, 0.03, 0.01"

# Download a file
call_tool("ssh_download_file", {
    "server_name": "web-server",
    "remote_path": "/etc/hostname",
})
# "web-server\n"

# Upload a file
call_tool("ssh_upload_file", {
    "server_name": "web-server",
    "remote_path": "/tmp/backup.sql",
    "content": "CREATE TABLE ...;\n",
    "permissions": "0640",
})
# "OK: Uploaded 19 bytes to /tmp/backup.sql"

# Check SSH connectivity
call_tool("ssh_check_connection", {"server_name": "web-server"})
# {"success": true, "output": "ping", "error": null, "exit_code": 0, "checkcommand": "echo ping"}

# Check with custom timeout
call_tool("ssh_check_connection", {"server_name": "web-server", "timeout": 5})

Note on sudo: There is no sudo_password parameter. If sudo requires a password, it comes from the target's password field in the config. The sudo flag wraps with sudo -S -p '' (password from config) or sudo -n (passwordless).

Error Responses

On failure a tool returns:

{
  "error": true,
  "error_type": "AuthorizationError",
  "message": "Command rejected: target 'foo' not found",
  "retryable": false,
  "request_id": "abc-123"
}

Common error_type values: AuthorizationError, PathValidationError, FileTransferError, SSHAuthenticationError, SSHTimeoutError, MCPSSHError. The retryable flag is true for SSHTimeoutError. Rate-limit violations return HTTP 429 instead.

Configuration

Config File Location

The server reads <config_dir>/ssh-mcp-config.json. Set config_dir via --config CLI flag or MCP_SSH_CONFIG_PATH environment variable (default: /config). If the file doesn't exist, the server writes a bundled default-config.json.

Top-Level Structure

{
  "version": 1,
  "ssh_targets": { ... },
  "block_patterns": [ ... ],
  "allowed_commands": {
    "default": [ ... ],
    "api_keys": [ ... ],
    "networks": [ ... ]
  },
  "settings": { ... }
}

The config is validated against config.schema.json (JSON Schema Draft 2020-12) at load time. Unknown keys cause a hard error.

ssh_targets

An object keyed by server identifier. Each target requires host, port, username, and at least one of private_key or password.

"ssh_targets": {
  "web-server": {
    "host": "192.168.1.10",
    "port": 22,
    "username": "deploy",
    "private_key": "/app/ssh_key",
    "checkcommand": "echo ping"
  }
}

* At least one of private_key or password is required.

private_key is a path on the server's filesystem (in Docker, mounted into the container), not an inline key.

block_patterns

A list of regex patterns. Any command matching a pattern is denied regardless of other allow-list layers. Patterns are screened for catastrophic-backtracking constructs at load time (ReDoS protection) and compiled with timeout guards at runtime.

allowed_commands

Three sub-objects control which commands each client may run:

• default — rules for all clients (unless a more specific layer decides first)
• api_keys — per-key rules, matched by key_hash
• networks — per-CIDR rules, matched by client source IP

Each rule has a targets list (server ids or "*" for all) and a commands list (base command names or "*" for any command).

"allowed_commands": {
  "default": [
    { "targets": ["*"], "commands": ["hostname", "uptime", "free", "df", "ps"] }
  ],
  "api_keys": [
    {
      "name": "ci-bot",
      "key_hash": "pbkdf2:sha256:100000$<salt>$<hash>",
      "rules": [
        { "targets": ["web-server"], "commands": ["systemctl", "journalctl"] }
      ]
    }
  ],
  "networks": [
    {
      "name": "home-lan",
      "range": "192.168.1.0/24",
      "rules": [
        { "targets": ["*"], "commands": ["*"] }
      ]
    }
  ]
}

settings

SFTP Settings (settings.sftp)

Secrets

SSH target passwords and API-key hashes can be separated from the main config into <config_dir>/secrets.json or MCP_SSH_SECRET_* environment variables. Precedence:

environment variables  >  secrets.json  >  ssh-mcp-config.json

<TARGET_ID> and <KEY_NAME> are upper-cased with - → _. API-key values must be hash strings, not raw keys.

Environment Variables and CLI Flags

CLI flags take precedence over environment variables. Any settings key can be overridden at runtime with MCP_SSH_SETTING_<KEY> (upper-cased, - → _).

Hot Reload

The server polls the config file for changes (15 s interval, 2 s debounce). When a change is detected, it reloads, validates, and atomically swaps in the new configuration. Config-change callbacks (authorization rules rebuild, connection pool refresh) run after the swap succeeds. Watchdog-based file monitoring is used when available.

Observability

Health Check

GET /health returns {"status": "ok"} plus connection pool stats. The container's HEALTHCHECK uses this endpoint.

Prometheus Metrics

GET /metrics exposes metrics on a dedicated registry, all prefixed mcpssh_:

Structured Logging

The mcp-ssh server supports pluggable log targets configured via settings.logging.log_targets in the config file. Each target is an independent driver that receives all log entries.

Default Behavior

By default, log entries are written to stdout in human-readable text format. This is suitable for Docker environments where container logs are captured by the runtime.

Log Target Types

Configuration

{
  "settings": {
    "log_level": "INFO",
    "logging": {
      "log_targets": [
        { "target": "stdout" },
        { "target": "jsonfile", "filepath": "logs/ssh-mcp.log" }
      ],
      "max_log_output": 4096,
      "compress_rotated": true
    }
  }
}

Log Level

• Config file: Set settings.log_level to control the default level.
• Environment variable: Set MCP_SSH_LOG_LEVEL to override the config-file default (e.g., MCP_SSH_LOG_LEVEL=DEBUG).
• Per-target: Each log target can have its own log_level that overrides the default.

Legacy Configuration

If settings.logging is absent, the server falls back to a single JSONL file target in the log directory (/logs by default). This maintains backward compatibility with existing configurations.

Text Format

Stdout and text-file targets use the format:

2025-01-15 10:30:00 INFO ssh_execute_command: Command executed on server1

JSON Format

JSON-file targets write one JSON object per line:

{"timestamp": "2025-01-15T10:30:00+00:00", "event": "ssh_execute_command", "level": "INFO", "message": "Command executed on server1", "request_id": "abc-123", "log_level": "INFO", "log_format_version": 1}

File Rotation

File-based targets rotate when they exceed max_file_size_mb (default: 10 MiB), keeping backup_count backups (default: 5). Rotated files are gzip-compressed when compress_rotated is true.

Configuration Change Events

Configuration API & Web Dashboard

The unified container includes an optional Configuration API and Web Dashboard — a full management plane for your SSH policy, targets, command rules, and backups. No config-file editing required. This feature is disabled by default.

What You Get

• Web Dashboard — a responsive single-page application with 5 pages: SSH Targets, Block Patterns, Command Rules, Settings, and Backups. Login with your API token and manage everything from the browser.
• REST API — full CRUD for every config section, plus config validation, API key hashing, backup management, and inline SSH connectivity testing.
• API Key Hashing Utility — hash plaintext API keys into PBKDF2 strings ready for config. No more guessing the hash format.
• Backup & Restore — automatic config backups on every write; list, restore, or delete backups from the dashboard or API.
• Atomic, Thread-Safe Writes — all config writes are validated, serialized with a threading lock, and atomically written to disk.
• Swagger UI & ReDoc — auto-generated interactive API documentation at /api/docs and /api/redoc.

Enabling the Configuration API

Set these environment variables in your compose.yaml or .env file:

services:
  mcp-ssh:
    environment:
      CONFIG_API_ENABLED: "true"
      CONFIG_API_TOKEN: "your-secret-token-here"

API Endpoints

All endpoints are mounted at /api on the same Starlette ASGI application as the MCP server.

Health & Utilities

Configuration

SSH Targets

Command Rules

Block Patterns

Backups

Authentication

All API requests (except /api/health and /api/config/schema) require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer your-secret-token-here" http://localhost:9080/api/config

Web Dashboard

When enabled, a responsive single-page application is available at http://localhost:9080/ui/ — a full management UI built with Tailwind CSS. No page reloads, toast notifications for every operation, and modal dialogs for editing.

Additional features:

• Token-based login with session management (stored in sessionStorage)
• Config validation — changes are validated before writing
• API key hashing — hash plaintext keys directly from the dashboard
• Responsive design — works on desktop and mobile
• Toast notifications — success/error feedback for every operation

Swagger / ReDoc

Interactive API documentation is auto-generated by FastAPI:

• Swagger UI: http://localhost:9080/api/docs
• ReDoc: http://localhost:9080/api/redoc

Deployment

Docker Compose

The compose.yaml defines a single mcp-ssh service that hosts both the MCP server and, optionally, the Configuration API & Web Dashboard. The config API is enabled via the CONFIG_API_ENABLED environment variable (default: false).

mcp-ssh — MCP SSH Gateway + Config API

Exposed on host port 9080 (maps to container port 8080). The runtime image is python:3.13-alpine with a hash-pinned digest. A non-root mcpssh user runs the process. A CycloneDX SBOM is generated at build time in the sbom stage.

Configuration API & Web Dashboard (optional)

Enable the config API by setting CONFIG_API_ENABLED=true in your .env file or environment:

# Generate an auth token
openssl rand -hex 32

CONFIG_API_ENABLED=true
CONFIG_API_TOKEN=<your-token>

When enabled, the config API is mounted at /api on the same HTTP server as the MCP gateway. It provides:

• REST API at http://localhost:9080/api/... — full CRUD for SSH targets, block patterns, command rules, backups, and settings
• Web Dashboard (GUI) at http://localhost:9080/ui/ — a single-page application for visual policy management (SSH targets, block patterns, command rules, settings, backups)
• API docs at http://localhost:9080/api/docs (Swagger UI) and http://localhost:9080/api/redoc (ReDoc)

Makefile

Pull from GHCR

The Docker image is automatically built and published to GitHub Container Registry:

docker pull ghcr.io/gelse/ssh-mcp:latest

Limitations and Threat Model

What ssh-mcp Is Not

• Not a shell. You cannot get an interactive terminal session. All execution is one-shot command calls.
• Not a file manager. SFTP is limited to single-file upload/download with path validation and sandbox enforcement. No directory listing, no recursive operations.
• Not a network firewall. Rate limiting is per-IP with fixed defaults. It protects against runaway clients, not determined attackers.

Threat Model

Not In Scope

• TLS termination (handled by your reverse proxy)
• User authentication beyond API keys (no OAuth, no mTLS at the application layer)
• SSH session multiplexing (no tmux/screen passthrough)
• Audit log tamper protection (logs are local files; use your own log shipping for immutability)

Development

Project Structure

• server.py — FastMCP app factory + CLI entry point
• lib/ — 30 single-responsibility modules (auth, config, SSH client, file transfer, logging, etc.)
• config-api/ — Configuration API + Web Dashboard (FastAPI, mounted at /api when CONFIG_API_ENABLED=true)
• tests/ — 36 unit-test files + integration tests with real Docker containers

Tech Stack

Python 3.13, FastMCP 3.4.x, paramiko 5.0, Starlette 1.4, FastAPI 0.115+, Pydantic 2.10+, httpx 0.28+, uvicorn 0.34+

Running Tests

# Unit tests (fast inner loop)
source .venv/bin/activate
python -m pytest tests/test_<module>.py -x

# Full unit test suite
make test

# Integration tests (requires Docker)
make integrationtest

Adding a New Tool

The worked example in AGENTS.md walks through adding a new @mcp.tool() handler end-to-end: constants, types, re-exports, handler, tests, commit.

No Lint/Type-Check Tooling

The project has no ruff, mypy, pyright, or flake8 configuration. Formatting follows .editorconfig defaults (4 spaces for Python, 88-char lines).

Roadmap

• Configuration GUI for visual policy management

License

MIT License — see LICENSE for details.

FAQ

The config-api Web Dashboard won't stay logged in over HTTP — /api/auth/session returns 401

Symptom: Login with the API key succeeds, but after redirect the dashboard immediately shows the login screen and the browser reports GET /api/auth/session 401 (Unauthorized).

Cause: The config-api session cookie is created with the Secure flag on by default. When you access the dashboard over plain http:// (no TLS), modern browsers refuse to store or send a Secure cookie over non-HTTPS connections. The cookie is never persisted, so the next request carries no session and /api/auth/session returns 401.

If you access the dashboard over http://, make sure the Secure flag is disabled by setting the environment variable in your .env file and restarting the container:

CONFIG_API_SESSION_COOKIE_SECURE=false

Because compose.yaml defaults the value to true (${CONFIG_API_SESSION_COOKIE_SECURE:-true}), the variable must be present in .env — adding it only to your shell does not apply. A container restart is required for the change to take effect.

Note: Disabling Secure weakens cookie security and should be limited to local / HTTP-only development. When the dashboard is served behind TLS (HTTPS), keep CONFIG_API_SESSION_COOKIE_SECURE=true (the default).