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

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

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.

Security

Dangerous command blocking. ssh-mcp rejects commands that match known destructive patterns unless the tool caller passes force=true:

• Recursive deletes of /, ~, $HOME, $USER — combined (rm -rf /) and split (rm -r -f /, rm --recursive --force /) flag forms, in any flag order
• find / -delete, find / -exec rm
• Block-device wipes: shred /dev/*, wipefs /dev/*, blkdiscard /dev/*, sgdisk -Z /dev/*
• Partition-table destruction: parted /dev/… mklabel, fdisk /dev/sd*
• mkfs, dd if=… and the reordered dd of=… if=… form
• Redirects into a block device or auth database: > /dev/sd*, > /dev/nvme*, > /dev/hd*, > /etc/{passwd,shadow,gshadow,sudoers}
• chmod 777 / — flag before or after the mode (chmod -R 777 /, chmod 777 -R /)
• Fork bombs (spaced and adjacent variants)
• Payload-execution wrappers: base64 -d | bash|sh|zsh|python|perl|ruby, eval "…", python|python3|perl|ruby -c, bash -c
• Host-availability destruction, matched only in command position (string start, after a shell separator, or after sudo/doas): reboot, poweroff, halt, shutdown, init 0|6, telinit 0|6, systemctl reboot|poweroff|halt|kexec, iptables|ip6tables -F|--flush, nft flush ruleset, userdel, passwd -l

Note the payload-execution bullet — it catches ordinary commands too. bash -c '…', python3 -c '…' and eval … are blocked by default even when entirely benign. Wrap them differently (a script file, a heredoc) or pass force=true for an audited call. The host-availability bullet is anchored the other way on purpose, so read-only diagnostics like last reboot or grep reboot /var/log/messages are not blocked — the cost of that anchor is that sudo -n reboot slips past it.

ASCII control characters (null bytes, \x01..\x1f, \x7f) are normalized to spaces before matching, so rm\x00-rf / is caught just like rm -rf /. Line breaks are matched both ways — as whitespace and as the statement separator they are — because rm -rf\n/ needs the first reading and a second line reboot needs the second, where it sits in command position rather than reading as an argument to line one. The regexes are fuzz-tested with Hypothesis on every CI run.

This is a TRIPWIRE, not a security boundary. The regex catches obvious accidents and shortcut destructive commands. It does NOT defend against a motivated attacker:

• The base64/eval/-c wrappers above are matched literally; any rewrite the regex does not spell out (a different decoder, a temp file, sh <<'EOF') gets through
• Shell hex escapes ($'\x72\x6d -rf /') are interpreted AFTER regex matching
• Unicode homoglyphs (Cyrillic р, Greek ρ) do not match Latin r
• Indirection via $(...) and `...` can hide intent — those are not matched at all

If you need real isolation for untrusted tool callers, sandbox at a lower layer: run ssh-mcp inside a container with a restricted SSH config, use ForceCommand on the managed servers, or audit force=false usage via the structured logs. The dangerous-command filter exists to stop LLM accidents and typos, not adversaries.

The bypass is not recorded in the audit log. Audit records carry server, command, exit_code and duration_ms only; force is emitted solely as an OpenTelemetry span attribute (ssh.force), and therefore only when an OpenTelemetry SDK and exporter are configured. The tracing API itself now ships as a required dependency of the MCP SDK, so spans are always created — but with no SDK installed they are no-ops that record nothing. A block is logged as a warning on the operational logger, not the audit logger. If you need a paper trail for bypasses, export traces or withhold force=true at the MCP client. Do not grant force=true to untrusted MCP clients.

Credential redaction in logs. ssh-mcp automatically redacts known credential patterns (MySQL -p<pass>, --password=, PGPASSWORD=, Authorization: Bearer, URL basic-auth user:pass@host, plus any env var ending in _PASSWORD, _SECRET, _TOKEN, _KEY, _CREDENTIAL, _PWD) from audit logs and OTel span attributes before they reach stderr or trace backends. The asyncssh internal channel logger is suppressed to WARNING level so it never emits the raw command.

Known limitation: command OUTPUT is NOT redacted. If you run cat /etc/mysql/my.cnf, env | grep PASSWORD, or kubectl get secret X -o yaml, the stdout/stderr returned to the MCP client will contain plaintext secrets. The redaction pipeline only filters the COMMAND string (what you asked to run), not the OUTPUT (what it printed). Avoid running commands that print secrets via ssh-mcp — pass credentials through env vars, Docker/K8s secrets, or dedicated config files instead.

{REDACTED+ELIDED} means more than a secret was cut. Redaction replaces from the credential marker to the end of the whitespace-delimited token, so a shell separator inside that token is consumed with it — before 0.8.1, echo --password=X;reboot was logged as echo --password={REDACTED} and the chained command did not appear in the record at all, though it ran. The secret is still never partially printed; the placeholder changes instead, so the log does not read as a faithful transcript. It errs toward flagging, so a password that merely contains ;, |, &, a backtick or $( is flagged too.

Local path confinement (new in 0.6.0; versions ≤ 0.5.6 are affected by the flaw it fixes — see CHANGELOG.md). SFTP upload_file and download_file no longer accept arbitrary absolute local paths. Every local path is relative to a configured transfer root and is resolved one component at a time beneath it, refusing a symbolic link at any component:

[settings]
transfer_root = "~/.local/share/ssh-mcp/transfers"   # default; honours $XDG_DATA_HOME

Override with the SSH_MCP_TRANSFER_ROOT environment variable. The directory is created 0700 on demand, must be owned by the user running ssh-mcp, and must not itself be a symlink — ssh-mcp refuses to start a transfer otherwise.

Consequences, all deliberate:

• Absolute local paths and .. are rejected. Sub-directories are allowed, but they must already exist.
• Downloads do not overwrite. An existing destination fails rather than being silently replaced. A failed transfer removes its own partial file.
• Remote non-regular files (symlinks, devices, FIFOs) are refused on a best-effort basis. SFTP protocol v3 offers no atomic no-follow open, so a remote server that swaps the file between the check and the open can still win that race; the local destination stays confined regardless.
• Remote paths keep the existing sensitive-path denylist — a tripwire, not a boundary, matched as a substring after normalizing // and ./ away, case-insensitively. It covers /etc/{shadow,gshadow,passwd,sudoers} and /etc/ssh/ssh_host_*; .ssh/{authorized_keys,id_rsa,id_ed25519,id_ecdsa,id_dsa,identity,config,known_hosts}; .aws/{credentials,config}, .azure/accesstokens.json, .config/gcloud/{credentials,access_tokens}.db; .kube/config, /etc/kubernetes/{admin,kubelet}.conf, /var/lib/kubelet/pki/; .netrc, .pgpass, .git-credentials, .docker/config.json; /proc/{self,<pid>}/{environ,mem,cmdline,maps,stack,status}, /proc/{kcore,kallsyms}; the MySQL / PostgreSQL / MongoDB data directories under /var/lib/; and the Windows SAM / SECURITY hives plus \users\administrator\.ssh\. Public keys are not exempt — the old *.pub carve-out was a string check on a caller-supplied name and was removed.

Prior versions validated the caller's path string against a denylist and then handed that string to asyncssh, which resolved it independently — so anything not enumerated was writable. Confinement replaces enumeration: ssh-mcp opens the local file itself and never lets a caller-supplied path reach the SFTP library.

Migrating from ≤ 0.5.x: replace absolute local paths with names relative to transfer_root, or set transfer_root to the directory you were already using. There is no flag to restore the old behaviour.

Host key verification is on by default (known_hosts = true). Disabling StrictHostKeyChecking in ~/.ssh/config weakens MITM protection and should be avoided in production.

Audit logging. Every tool call is logged to stderr with server, command, exit_code, duration_ms, and (for SFTP) byte counts. SFTP operations emit three-stage events: sftp.upload.start → sftp.upload.complete (or sftp.upload.failed), each tagged with a stable connection_id so a single transfer is grep-correlatable.

For production log aggregation, set SSH_MCP_LOG_FORMAT=json to emit single-line JSON events:

{"event": "sftp.upload.complete bytes=4096 duration_ms=183", "level": "info", "timestamp": "2026-04-08T16:00:11.761575Z", "server": "web-prod-01", "operation": "upload", "local_path": "releases/app.tar.gz", "remote_path": "/var/www/release.tar.gz", "connection_id": "web-prod-01-4242-a3f1c9d2"}

When running in Docker, capture stderr with docker logs for the audit trail.

For vulnerability reports, see SECURITY.md. Do not open public GitHub issues for security concerns.

Development

git clone https://github.com/blackaxgit/ssh-mcp.git
cd ssh-mcp
uv sync --locked --extra dev
uv run pytest
uv run ruff check src/ tests/

See CONTRIBUTING.md for guidelines on making changes and submitting pull requests.

Changelog

See CHANGELOG.md.

License

Mozilla Public License 2.0. See LICENSE.