ssh-mcp-dynamic

A minimal Model Context Protocol (MCP) server that lets an MCP client (Claude Code, Claude Desktop) run shell commands on remote hosts over SSH. The host, private key, user and port are chosen per call, so a single server instance can reach many machines.

It exposes two tools:

Authentication is key-based only (PEM private keys). No passwords are handled or stored.

Contents: Quick start · Usage · Configuration · Security model · Development · License

Quick start

You need Node.js 18+ on the machine that runs your MCP client, and SSH access to the target hosts with a private key. The server is published on npm as @calevi/ssh-mcp-dynamic; npx downloads and runs it on demand, so there is nothing to clone or build.

Claude Code (CLI)

Minimal — no environment config at all. You provide the host, command and a full key path on every call:

claude mcp add ssh-mcp -- npx -y @calevi/ssh-mcp-dynamic

With shortcuts and defaults — preconfigure your keys once so calls can use a short name (e.g. prod) and omit the user/port, bound the reachable hosts, and keep an audit log:

claude mcp add ssh-mcp -s user \
  -e SSH_MCP_KEYS='{"prod":"~/keys/prod.pem"}' \
  -e SSH_MCP_DEFAULT_KEY=prod \
  -e SSH_MCP_DEFAULT_USER=ubuntu \
  -e SSH_MCP_ALLOWED_HOSTS='10.0.0.*,*.internal.example.com' \
  -e SSH_MCP_AUDIT_LOG=~/.ssh-mcp/audit.log \
  -- npx -y @calevi/ssh-mcp-dynamic

Scopes (-s): local (default, current project only), user (all your projects), project (saved to a versioned .mcp.json to share with your team).

Verify with claude mcp list, or /mcp inside a session. Remove with claude mcp remove ssh-mcp.

To pin an exact version use npx -y @calevi/ssh-mcp-dynamic@1.1.2. To run straight from GitHub instead (a tagged release, or main without the #tag), use npx -y github:Calevi-Consulting/ssh-mcp-dynamic#v1.1.2; npx then clones and builds it via the prepare script. For a local checkout see Development.

Claude Desktop

Add the server to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "npx",
      "args": ["-y", "@calevi/ssh-mcp-dynamic"],
      "env": {
        "SSH_MCP_KEYS": "{\"prod\":\"~/keys/prod.pem\",\"staging\":\"~/keys/staging.pem\"}",
        "SSH_MCP_DEFAULT_KEY": "prod",
        "SSH_MCP_DEFAULT_USER": "ubuntu",
        "SSH_MCP_ALLOWED_HOSTS": "10.0.0.*,*.internal.example.com",
        "SSH_MCP_AUDIT_LOG": "~/.ssh-mcp/audit.log"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Related MCP server: ssh-chat-mcp

Usage

Once the server is registered, you don't call the tools directly — you ask your MCP client (Claude Code / Claude Desktop) in plain language and it invokes ssh_exec / ssh_sudo_exec for you. Some example prompts:

Using ssh-mcp, run `hostname && uptime` on 10.0.0.5 with the prod key.

Check the free disk space on staging.example.com (df -h) via ssh-mcp.

On 10.0.0.5, tail the last 50 lines of /var/log/syslog with sudo.

Restart nginx on web-01.example.com with sudo, then show `systemctl status nginx`.

Run `docker ps` on 203.0.113.10 as user ubuntu on port 2222 using ~/keys/prod.pem.

How those map to a tool call (the client fills this in for you):

// "run hostname on 10.0.0.5 with the prod key"
{
  "tool": "ssh_exec",
  "host": "10.0.0.5",
  "command": "hostname",
  "key": "prod"          // a configured shortcut, or a full path like ~/keys/prod.pem
}

// "tail syslog with sudo on 10.0.0.5"
{
  "tool": "ssh_sudo_exec",
  "host": "10.0.0.5",
  "command": "tail -n 50 /var/log/syslog"   // no 'sudo' prefix — the tool adds it
}

Tips:

• Mention the host, the command, and which key/user/port when they aren't the configured defaults.

• Naming the server ("using ssh-mcp…") helps the client pick the right tool when you have several MCP servers registered.

• For privileged commands ask for "with sudo" so the client uses ssh_sudo_exec — and don't put sudo in the command yourself.

Configuration

Everything host-specific is supplied through environment variables — nothing is hardcoded in the source.

Example SSH_MCP_KEYS:

{
  "prod": "~/keys/prod.pem",
  "staging": "~/keys/staging.pem"
}

With that set, a call can pass "key": "prod" instead of a full path. You can also pass a full path directly at call time without configuring any shortcut.

Tool parameters

Both tools accept:

• host (required) — IP or hostname.

• command (required) — the shell command.

• key — a configured shortcut or a path to the PEM file. Required unless SSH_MCP_DEFAULT_KEY is set.

• user — SSH username (defaults to SSH_MCP_DEFAULT_USER).

• port — SSH port (defaults to SSH_MCP_DEFAULT_PORT).

• timeout — timeout in ms (defaults to SSH_MCP_TIMEOUT_MS).

Host allowlist

Set SSH_MCP_ALLOWED_HOSTS to bound which machines the model can reach, regardless of what it puts in host:

SSH_MCP_ALLOWED_HOSTS='10.0.0.*,*.internal.example.com,web-01'

A call to a host outside the list returns an error and is recorded in the audit log with "outcome":"denied". No SSH connection is opened. The configured list is also included in the tool description so the model knows the boundary up front. When the variable is unset, any host is allowed.

Host key verification

The server verifies the remote host key against SSH_MCP_KNOWN_HOSTS (default ~/.ssh/known_hosts), the same file OpenSSH uses. Plain, hashed (|1|...), [host]:port, wildcard and @revoked entries are understood. SSH_MCP_HOST_KEY_CHECKING selects the policy, mirroring OpenSSH StrictHostKeyChecking:

A refused call returns an error explaining why and is audited as denied. If you hit Host key verification failed for a host you trust, either connect to it once with ssh from the same machine (so OpenSSH records the key), or run with SSH_MCP_HOST_KEY_CHECKING=accept-new. A HOST KEY MISMATCH means the key on record differs from the one the server presented: treat it as OpenSSH would, and only remove the old entry if you know the host was rebuilt.

Audit log

Every call produces one JSON line on stderr (Claude Code and Claude Desktop keep MCP server stderr in their logs). Set SSH_MCP_AUDIT_LOG to also append it to a file (created with mode 0600):

{"ts":"2026-09-06T14:02:11.482Z","tool":"ssh_sudo_exec","host":"10.0.0.5","port":22,"user":"ubuntu","key":"prod","command":"sudo systemctl restart nginx","duration_ms":812,"outcome":"ok","exit_code":0}
{"ts":"2026-09-06T14:02:40.107Z","tool":"ssh_exec","host":"203.0.113.9","port":22,"user":"ubuntu","key":"prod","command":"id","duration_ms":1,"outcome":"denied","error":"Host '203.0.113.9' is not in SSH_MCP_ALLOWED_HOSTS ('10.0.0.*')"}

outcome is ok (exit code 0), error (non-zero exit or connection failure) or denied (blocked by the allowlist or host key policy). key is the shortcut or path as supplied by the caller. Command output and key material are never logged.

Security model

This server executes arbitrary shell commands on remote hosts, including with sudo via ssh_sudo_exec. It is deliberately thin and does not try to be a policy engine. The controls are layered, and the server only owns some of them:

1. The MCP client. Claude Code and Claude Desktop show the exact host and command and ask for approval before each call. Nothing runs unattended unless you allowlist the tool in the client.

2. This server. SSH_MCP_ALLOWED_HOSTS bounds which hosts the model can reach. Host key verification (strict by default) refuses unknown or changed hosts. Every call, including refused ones, is written to the audit log. Authentication is key-based only; no passwords are handled or stored, and keys are read from disk at call time.

3. The keys and the hosts. A call can only reach hosts where the configured key is authorized, so keep one key per environment. On the host, scope what that identity can do with authorized_keys options (from=, command=, restrict), a dedicated low-privilege user, and sudoers rules that limit what ssh_sudo_exec can run.

4. Transport. The server talks to the MCP client over stdio and opens no network listener of its own.

What it does not do: there is no command allow/deny list (express that in sudoers and authorized_keys, where it is enforced regardless of the client), no support for SSH certificates (@cert-authority entries are ignored), and the audit log is advisory (a failure to write it is reported on stderr but does not block the call).

Practical notes:

• Only connect it to hosts and keys you control, and only run it with an MCP client you trust.

• Never commit private keys. *.pem, *.key, and common key filenames are already in .gitignore.

• Prefer passphrase-protected keys or keys scoped to specific hosts.

• Setting SSH_MCP_HOST_KEY_CHECKING=off and leaving SSH_MCP_ALLOWED_HOSTS unset restores the 1.0.x behaviour.

Development

Local checkout

git clone https://github.com/Calevi-Consulting/ssh-mcp-dynamic.git
cd ssh-mcp-dynamic
npm install
npm run build

This compiles src/index.ts to dist/index.js. Point your MCP client at the compiled file instead of the npm package:

claude mcp add ssh-mcp -s user \
  -e SSH_MCP_KEYS='{"prod":"~/keys/prod.pem"}' \
  -e SSH_MCP_DEFAULT_KEY=prod \
  -- node "$(pwd)/dist/index.js"

For Claude Desktop, use "command": "node" with "args": ["/absolute/path/to/ssh-mcp-dynamic/dist/index.js"].

Tests

npm test

Tests use Node's built-in test runner and an in-process SSH server from the ssh2 package with generated ed25519 keys, so the host key, allowlist and audit paths are exercised over a real SSH handshake with no external dependencies. The same suite runs in CI on Node 18, 20, 22 and 24 for every pull request, together with a stdio smoke test of the built server and npm audit.

Releasing

1. Bump version in package.json on a branch and merge it through a pull request (main requires green CI).

2. Tag the merge commit vX.Y.Z and publish a GitHub Release for that tag.

3. The Publish to npm workflow (.github/workflows/publish.yml) runs the tests, checks the tag matches package.json, and runs npm publish --provenance. It authenticates with npm trusted publishing (OIDC), so no npm token lives in the repository; the trusted publisher is configured once on npmjs.com under the package's settings. If that version is already on npm the publish step is skipped, so re-publishing a release is safe.

License

MIT