ssh-mcp

A small, reliable MCP server that gives an AI agent (Claude Code, etc.) persistent SSH access to your servers — register a host once, then run commands by name.

Why

Stock SSH MCP servers reimplement the SSH transport in-process: they drop connections, lose credentials between sessions, and force the agent to fall back to raw ssh -i key user@host shell-outs (which leak creds into command history and break on reconnect).

This server does not reimplement SSH. It wraps the system ssh/scp binaries with OpenSSH ControlMaster multiplexing:

• A background control socket (ControlPersist=10m) keeps one authenticated connection warm — reconnects are instant and survive MCP restarts.

• Credentials live in a registry file (~/.ssh/ssh_mcp_hosts.json), set once, reused by host name.

• The agent calls ssh_exec(host="myserver", command=...) — no keys or IPs in every call.

Related MCP server: SSH MCP Server

Tools

Execution model — one-shot

Each ssh_exec is an independent command. State does not persist between calls:

• cwd does not persist → use absolute paths or cd /path && cmd.

• env does not persist → set inline (VAR=x cmd).

• No interactive TUI (vim, top, less) and no prompts → pass -y/--yes.

• Long jobs: nohup cmd >/tmp/x.log 2>&1 &, then tail the log in a later call.

First connect with a password (auto key-provisioning)

For a host that only accepts a password (a factory-default device, a fresh VPS), let the server mint a dedicated key for it:

1. host_add(name="cam1", host="10.0.0.180", user="root") — no key.

2. ssh_exec(host="cam1", command="uname -a") → fails with Permission denied plus a hint.

3. Put the password in a file so it never enters the transcript: umask 077; printf %s 'THE_PASSWORD' > /tmp/sshpw_cam1

4. ssh_exec(host="cam1", command="uname -a", password_file="/tmp/sshpw_cam1")

The server generates ~/.ssh/ssh_mcp_cam1_ed25519, installs it via ssh-copy-id, records the key path in the registry, shreds the password file, and runs the command. Every later call authenticates by key — no password needed. One dedicated key per host; the password is read from the file (never argv) and is never logged.

Requires sshpass and ssh-copy-id on PATH for this flow.

Requirements

• Node.js 23.6+ (runs TypeScript directly via type-stripping — no build step)

• OpenSSH client (ssh, scp) on PATH

• sshpass + ssh-copy-id (only for password-based auto-provisioning)

Install

pnpm install

Register with your MCP client (e.g. Claude Code ~/.claude.json):

{
  "mcpServers": {
    "ssh": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/ssh_mcp/src/index.ts"]
    }
  }
}

Restart the client, then add a host:

host_add(name="myserver", host="1.2.3.4", user="root", key="~/.ssh/id_ed25519")
ssh_exec(host="myserver", command="uname -a")

License

MIT