ssh MCP server

ssh-mcp

SSH MCP server that lets AI assistants execute commands on remote servers.

What is this

ssh-mcp is a Model Context Protocol server that gives AI assistants like Claude direct access to your SSH infrastructure. Once configured, Claude can run commands, transfer files, and query server groups across your fleet without leaving the conversation.

Connection details are read from your existing ~/.ssh/config. No credentials are stored in the MCP configuration.

Features

• Run shell commands on individual servers or across entire groups in parallel
• SFTP file upload and download over the existing SSH session
• Connection pooling — reuses SSH connections across tool calls
• Dangerous command detection — warns before executing destructive operations
• Server groups for organizing hosts (production, staging, per-service)
• SSH config integration — reads host, port, user, and identity from ~/.ssh/config
• Custom config path via SSH_MCP_CONFIG environment variable
• dry_run previews — see which server, command, working directory and timeout would be used, without connecting
• SFTP local-path confinement — every local path stays inside a configured transfer_root
• stdio or streamable-HTTP transport, with bearer-token auth for network deployments
• Built-in ssh-mcp healthcheck subcommand for Docker's HEALTHCHECK
• Optional OpenTelemetry tracing — the API ships with the MCP SDK; add an SDK and exporter to record anything

Quick Start

Install

# Run directly with uvx (no install required)
uvx blc-ssh-mcp

# Or install with pip
pip install blc-ssh-mcp

Requires Python 3.11+. Install uv to use uvx.

The PyPI package is blc-ssh-mcp, not ssh-mcp. The name ssh-mcp on PyPI belongs to an unrelated project by a different author. Installing it will not give you this server. Releases before 0.6.1 documented the wrong name — if you followed those instructions, uninstall ssh-mcp and install blc-ssh-mcp.

Docker

A prebuilt image is published to GitHub Container Registry for linux/amd64 and linux/arm64 (0.8.1 and newer — 0.8.0 and earlier are amd64-only and will not run on Apple Silicon or AWS Graviton):

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

Or run with Docker Compose:

services:
  ssh-mcp:
    image: ghcr.io/blackaxgit/ssh-mcp:latest
    stdin_open: true
    restart: unless-stopped
    environment:
      SSH_MCP_CONFIG: /config/servers.toml
    volumes:
      - ./servers.toml:/config/servers.toml:ro
      - ~/.ssh:/home/sshmcp/.ssh:ro

The image uses a non-root sshmcp user (uid 1000). Mount your SSH keys and config file read-only. compose.yaml in the repo carries a fuller example — it builds from the local Dockerfile rather than pulling the published image, and includes the HTTP-transport service, ulimits and healthcheck guidance omitted above.

Create a config file

mkdir -p ~/.config/ssh-mcp
cp config/servers.example.toml ~/.config/ssh-mcp/servers.toml

Edit ~/.config/ssh-mcp/servers.toml and add your servers. Server names must match Host entries in ~/.ssh/config.

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": ["blc-ssh-mcp"]
    }
  }
}

To use a non-default config path, pass the environment variable:

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": ["blc-ssh-mcp"],
      "env": {
        "SSH_MCP_CONFIG": "/path/to/servers.toml"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Add to Claude Code

If you use Claude Code instead of Claude Desktop, you can set everything up from the terminal:

# 1. Add the MCP server
claude mcp add ssh-mcp -- uvx blc-ssh-mcp

# 2. Create the config directory and copy the example
mkdir -p ~/.config/ssh-mcp
curl -sL https://raw.githubusercontent.com/blackaxgit/ssh-mcp/main/config/servers.example.toml \
  > ~/.config/ssh-mcp/servers.toml

# 3. Edit with your servers (server names must match ~/.ssh/config Host entries)
${EDITOR:-nano} ~/.config/ssh-mcp/servers.toml

# 4. Restrict permissions
chmod 600 ~/.config/ssh-mcp/servers.toml

To use a custom config path:

claude mcp add ssh-mcp -e SSH_MCP_CONFIG=/path/to/servers.toml -- uvx blc-ssh-mcp

Configuration

Environment variables

Variable	Default	Purpose
SSH_MCP_CONFIG	—	Absolute path to a TOML config file. Overrides the default search path.
SSH_MCP_LOG_FORMAT	console	Log output format. Set to json to emit single-line JSON events (timestamp, level, event, contextvars) suitable for log aggregators like Loki, Datadog, or Splunk. Any other value falls back to the colorized console renderer.
SSH_MCP_TRANSPORT	stdio	MCP transport. stdio = classic subprocess transport (default, used by Claude Desktop / Claude Code via uvx blc-ssh-mcp). http or streamable-http = run as a network service over MCP streamable HTTP.
SSH_MCP_HTTP_HOST	127.0.0.1	Bind address for HTTP transport. Binding to any non-localhost value (e.g. 0.0.0.0) REQUIRES SSH_MCP_HTTP_TOKEN — startup aborts otherwise.
SSH_MCP_HTTP_PORT	8000	TCP port for HTTP transport.
SSH_MCP_HTTP_TOKEN	—	Shared bearer secret. When set, every request must carry Authorization: Bearer <token> (scheme case-insensitive per RFC 7235) or receive HTTP 401. Mandatory for non-localhost binds (unless SSH_MCP_HTTP_AUTH=none). Minimum length 16 characters, and the value must be printable ASCII with no whitespace — a token containing a control character, an interior space or non-ASCII text cannot be sent in an HTTP header, so it is rejected at startup rather than returning 401 to every client forever. Leading/trailing whitespace is stripped so .env files with trailing newlines work as expected; a value that is present but strips to nothing aborts startup, since silently falling back to no authentication is never what an operator configuring a token meant.
SSH_MCP_HTTP_TOKEN_FILE	—	Path to a file containing the bearer token (alternative to SSH_MCP_HTTP_TOKEN). Read at startup, stripped of whitespace, and a UTF-8 BOM is removed (Windows editors add one by default). Preferred for Docker/Kubernetes secrets: mount the secret file and point this env var at it. Validated at startup. Aborts on: a non-regular file (directory, fifo, device); more than 64 KiB, enforced on the size snapshot and on the bytes actually read; a file writable by group or other, since whoever can write it chooses the token that authorises remote command execution; content that is not valid UTF-8; and a file that exists but is empty or whitespace-only. Warns on: a mode readable beyond its owner, and an owner that is neither this process nor root — those two only warn because Docker (0444) and Kubernetes (0644) secret mounts are world-readable and commonly root-owned, so refusing would break them. Prefer 0600 on a shared host. Symlinks are followed, so Kubernetes' ..data projection works. Permission and ownership checks are POSIX-only and skipped on Windows, where the mode bits are synthesised.
SSH_MCP_HTTP_AUTH	bearer	Authentication mode. bearer (default) enables the built-in middleware. none disables it entirely — useful when ssh-mcp sits behind a trusted reverse proxy that handles auth at the edge. Combining none with a non-localhost bind REQUIRES the explicit acknowledgement env var below.
SSH_MCP_HTTP_NETWORK_NO_AUTH	—	Magic-string escape hatch. Must equal literal I_ACCEPT_RCE_RISK to allow SSH_MCP_HTTP_AUTH=none + non-localhost bind. Intentionally verbose so nobody sets it by accident.
SSH_MCP_HTTP_KEEPALIVE_TIMEOUT	2	uvicorn timeout_keep_alive in seconds. Idle HTTP/1.1 connections are closed after this many seconds. v0.4.0 default (5s) accumulated enough concurrent connections under bursty n8n traffic to exhaust the container's 1024 fd limit — v0.4.1 default 2s is safer for spiky clients. Increase to 5–10 for long-polling MCP clients behind a load balancer.
SSH_MCP_HTTP_LIMIT_CONCURRENCY	256	uvicorn limit_concurrency. Max simultaneous in-flight requests before returning HTTP 503. Prevents unbounded growth under burst load. Tune up for high-QPS deployments; tune down on small containers.
SSH_MCP_HTTP_BACKLOG	128	uvicorn backlog — TCP listen backlog for the accept queue. Smaller caps SYN-flood exposure.
SSH_MCP_HTTP_STATELESS	false	Set to true for stateless sessions (recommended for load-balanced or serverless deployments). Default is stateful with server-side sessions.
SSH_MCP_HTTP_ALLOWED_HOSTS	—	Comma-separated extra Host-header values the SDK's DNS-rebinding protection should permit (e.g. ssh-mcp.internal:*,api.example.com:8000). Localhost aliases are always permitted. Only a trailing :* port wildcard is supported: any other wildcard — including a *.subdomain suffix — aborts startup, because the MCP SDK matches such an entry literally and would reject every request. List concrete hostnames.
SSH_MCP_TRANSFER_ROOT	$XDG_DATA_HOME/ssh-mcp/transfers	Directory SFTP transfers are confined to. Takes precedence over transfer_root in [settings]. See Local path confinement.
XDG_CONFIG_HOME	~/.config	Honoured when searching for ssh-mcp/servers.toml (see Config file location).
XDG_DATA_HOME	~/.local/share	Base directory for the default transfer root.
HYPOTHESIS_PROFILE	dev	For local development / CI only. Set to ci to run property-based tests with max_examples=200 instead of 50.

fd exhaustion mitigation: the Docker base image inherits a 1024 fd limit by default. Under sustained burst traffic that can run out quickly. Raise it in your compose file:

ssh-mcp:
  # ...
  ulimits:
    nofile:
      soft: 65536
      hard: 65536

Pair that with the SSH_MCP_HTTP_KEEPALIVE_TIMEOUT / SSH_MCP_HTTP_LIMIT_CONCURRENCY knobs above for a full fix.

Running over HTTP

ssh-mcp exposes the MCP streamable HTTP transport as an alternative to stdio. This lets MCP-aware clients connect over the network instead of launching a subprocess, which is useful for containerized deployments, shared-team servers, or anything that needs to survive a client restart.

WARNING: ssh-mcp serves plain HTTP, not HTTPS. The bearer token is transmitted in cleartext on every request. Deploying on a public IP without a TLS-terminating reverse proxy (Caddy, nginx, Traefik) exposes the token to any network observer — equivalent to publishing a root shell. Always terminate TLS before ssh-mcp reaches the network.

Security first. ssh-mcp runs shell commands on remote servers. Exposing the HTTP endpoint without authentication is equivalent to exposing a root shell. The startup code enforces this:

• Binding to 127.0.0.1 / localhost / ::1 without a token is allowed — this matches the single-user workstation model.
• Binding to ANY other address without SSH_MCP_HTTP_TOKEN raises RuntimeError at startup and the process exits.
• The MCP SDK's DNS-rebinding protection is enabled by default. Remote clients connecting via a hostname must have it listed in SSH_MCP_HTTP_ALLOWED_HOSTS.
• Streamable HTTP requests are capped at 4 MiB by the MCP SDK — an oversized request gets HTTP 413 before its JSON is parsed or a session is created. This sits comfortably above max_command_bytes' 1 MiB ceiling, so no operator action is needed.
• serverInfo in the MCP initialize response now reports ssh-mcp's own version (previously it reported the SDK's version instead).
• Bearer-token comparison uses hmac.compare_digest to prevent timing attacks.

Local loopback (no auth needed):

SSH_MCP_TRANSPORT=http ssh-mcp
# → listening on http://127.0.0.1:8000/mcp

Container deployment with bearer auth:

TOKEN=$(openssl rand -hex 32)
docker run -d \
  -p 8000:8000 \
  -e SSH_MCP_TRANSPORT=http \
  -e SSH_MCP_HTTP_HOST=0.0.0.0 \
  -e SSH_MCP_HTTP_TOKEN="$TOKEN" \
  -e SSH_MCP_HTTP_STATELESS=true \
  -e SSH_MCP_HTTP_ALLOWED_HOSTS='ssh-mcp.internal:*' \
  -v ~/.ssh:/home/sshmcp/.ssh:ro \
  -v ./servers.toml:/config/servers.toml:ro \
  -e SSH_MCP_CONFIG=/config/servers.toml \
  ghcr.io/blackaxgit/ssh-mcp:latest

Clients connect with:

Authorization: Bearer <TOKEN>
Host: ssh-mcp.internal

For stateful sessions (default), MCPServer maintains per-client context across requests. Since mcp 2.2.0, stateful sessions on the legacy (2025-11-25 and earlier) protocol are limited: one with no request in flight and no open GET stream is closed after 30 minutes (its next request gets 404 and must initialize again), and at most 10,000 are held at once (503 beyond that; an open GET stream still counts). Stateless mode avoids both limits. For stateless deployments behind a load balancer, set SSH_MCP_HTTP_STATELESS=true — each request is handled independently with no server-side session.

Healthcheck

The Docker image includes a built-in ssh-mcp healthcheck CLI subcommand that Docker's HEALTHCHECK directive invokes automatically. No inline Python, no curl, no manual compose surgery required. The subcommand:

• Auto-detects the transport via SSH_MCP_TRANSPORT:
  • stdio mode: verifies the package imports and servers.toml parses
  • http mode: sends a real MCP initialize JSON-RPC POST and checks for any non-5xx response
• Reads the same auth env vars as the server (SSH_MCP_HTTP_TOKEN, SSH_MCP_HTTP_TOKEN_FILE, SSH_MCP_HTTP_AUTH) — never logs the token
• Exits 0 if healthy, 1 otherwise
• Uses Python stdlib only (no curl/wget dependency)
• Applies a 3-second timeout to the HTTP probe. The stdio probe has no timeout of its own and relies on Docker's --timeout=5s (importing the server costs ~0.3s)

Run manually for debugging:

docker exec ssh-mcp ssh-mcp healthcheck && echo "healthy"

Check current status:

docker inspect ssh-mcp --format '{{.State.Health.Status}}'

To override the baked-in settings in your compose file:

healthcheck:
  test: ["CMD", "ssh-mcp", "healthcheck"]
  interval: 15s
  timeout: 5s
  retries: 3
  start_period: 10s

Tracing (OpenTelemetry)

Tracing uses the OpenTelemetry API, which ships as a required dependency of the MCP SDK — there is nothing to opt into at the ssh-mcp layer:

uv pip install opentelemetry-sdk opentelemetry-exporter-otlp   # or your exporter of choice

ssh-mcp's own spans and the MCP SDK's own request-handling spans are both created unconditionally; without an SDK and exporter installed, span creation is a no-op and nothing is recorded or exported.

Spans produced:

• mcp.tool.<name> — one per MCP tool call, tagged mcp.tool.name. Exceptions are recorded with StatusCode.ERROR.
• ssh.execute, ssh.upload, ssh.download — the SSH/SFTP operation inside the tool call.

Span attributes go through the same credential redaction as the audit log (see Security).

Reverse proxy deployment (auth at the edge)

If your reverse proxy (Caddy, nginx, Traefik, Envoy, Cloudflare Access, etc.) already authenticates requests before they reach ssh-mcp, you can disable the built-in bearer middleware with SSH_MCP_HTTP_AUTH=none. This mode is deliberately hard to enable on a public bind — you must also set a verbose acknowledgement env var:

docker run -d \
  --network internal \
  -e SSH_MCP_TRANSPORT=http \
  -e SSH_MCP_HTTP_HOST=0.0.0.0 \
  -e SSH_MCP_HTTP_AUTH=none \
  -e SSH_MCP_HTTP_NETWORK_NO_AUTH=I_ACCEPT_RCE_RISK \
  -e SSH_MCP_HTTP_ALLOWED_HOSTS='ssh-mcp.internal:*' \
  -v ~/.ssh:/home/sshmcp/.ssh:ro \
  -v ./servers.toml:/config/servers.toml:ro \
  -e SSH_MCP_CONFIG=/config/servers.toml \
  ghcr.io/blackaxgit/ssh-mcp:latest

WARNING: SSH_MCP_HTTP_AUTH=none + SSH_MCP_HTTP_NETWORK_NO_AUTH=I_ACCEPT_RCE_RISK is a remote code execution surface. The magic-string acknowledgement exists so operators physically type the words "I ACCEPT RCE RISK" before opting in. Every tool call reaches a shell on every managed SSH server. Use this only when:

1. ssh-mcp is on a private Docker network not reachable from the host's public interface, AND
2. The reverse proxy fronting it enforces authentication (basic auth, OAuth, mTLS, Cloudflare Access, etc.), AND
3. You have audit logging on the proxy that's immutable to the ssh-mcp process.

For localhost binds without auth, no acknowledgement is needed — that matches the historical stdio deployment model.

Config file location

Checked in order:

1. $SSH_MCP_CONFIG environment variable
2. $XDG_CONFIG_HOME/ssh-mcp/servers.toml, falling back to ~/.config/ssh-mcp/servers.toml (default)
3. config/servers.toml relative to the package (development only)

Example servers.toml:

[settings]
ssh_config_path = "~/.ssh/config"
command_timeout = 30          # SSH *connect* timeout in seconds, range 1..3600
max_output_bytes = 51200      # truncate captured output at this many bytes, per stream
max_command_bytes = 65536     # reject longer command strings at the tool boundary (1024..1048576)
connection_idle_timeout = 300 # seconds; eviction scan runs every 60s
known_hosts = true            # false removes MITM protection
max_parallel_hosts = 10       # process-wide concurrency cap for group execution (1..100)

[groups]
production = { description = "Production servers" }
staging    = { description = "Staging servers" }

[servers.web-prod-01]
description = "Production web server"
groups      = ["production"]

[servers.web-staging-01]
description = "Staging web server"
groups      = ["staging"]
jump_host   = "bastion"

[servers.db-prod-01]
description = "Production database"
groups      = ["production"]
user        = "dbadmin"

Note two things about the timeouts, because the names invite confusion:

• command_timeout is the SSH connection-establishment timeout, not the command execution timeout.
• Per-command timeout comes from the timeout argument of execute / execute_on_group (default 30) — unless the server block sets timeout = N, which wins over the caller's argument.

max_parallel_hosts bounds the whole process, not a single call: the semaphore is built once at startup, so concurrent execute_on_group calls share the same budget rather than each getting their own.

Per-server overrides (hostname, port, user, identity_file, jump_host, default_dir, timeout) take precedence over ~/.ssh/config. See config/servers.example.toml for the annotated reference.

Restrict config file permissions to your user:

chmod 600 ~/.config/ssh-mcp/servers.toml

Available Tools

Tool	Description
list_servers	List configured servers; optionally filter by group
list_groups	List server groups with member counts
execute	Run a shell command on a single server (supports force to bypass dangerous-command detection, and dry_run)
execute_on_group	Run a command on all servers in a group (parallel; supports fail_fast, force and dry_run)
upload_file	Upload a file to a server via SFTP. Local path is relative to transfer_root
download_file	Download a file from a server via SFTP. Local path is relative to transfer_root; will not overwrite

dry_run=true on either execute tool returns a [DRY RUN] preview of the server, command, working directory, timeout and force flag without opening a connection. Dangerous-command detection still runs, so a rejection can be previewed; if force=true would bypass a match, the preview carries an explicit ⚠️ DANGEROUS banner.

Command strings longer than max_command_bytes (default 65536 encoded UTF-8 bytes) are rejected at the tool boundary, before redaction or dangerous-command matching runs. Single SFTP transfers are capped at 100 MiB: an oversized upload is refused outright, an oversized download only logs a warning (the bytes are already on disk). Use rsync or scp for anything larger.