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.

Requirements

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

• OpenSSH client (ssh, scp) on PATH

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