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:

what it can run

• No centralized access control — every client decides

• 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).

Build locally instead

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

• sshlistservers — list resources
• sshlistallowed_commands — list permissions
• sshexecutecommand — perform an action
• sshcheckconnection — verify connectivity
• sshdownloadfile / sshuploadfile — 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

Shortened. The full README is on GitHub.