SSH MCP Server

An MCP (Model Context Protocol) server that lets Claude execute commands on remote servers over SSH. Supports ~/.ssh/config, private keys, password auth, and SSH agent forwarding.

Tools

Related MCP server: SSH Remote MCP Server

Setup

git clone <repo-url> && cd ssh-mcp-server
npm install
npm run build

Claude Code

claude mcp add ssh node /absolute/path/to/ssh-mcp-server/build/index.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/absolute/path/to/ssh-mcp-server/build/index.js"]
    }
  }
}

Authentication

Auth is resolved in this order — the first match wins:

1. Explicit password — password param

2. Explicit private key — privateKeyPath param (supports passphrase)

3. SSH config IdentityFile — reads ~/.ssh/config, tries each key in order

4. SSH agent — uses SSH_AUTH_SOCK (default when nothing else is specified)

Using ~/.ssh/config

The server reads ~/.ssh/config on every connect call, so edits are picked up without restarting. All standard directives are supported:

Host myserver
    HostName 10.0.1.50
    User deploy
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

Then just connect with host: "myserver" — the alias, hostname, user, port, and key are all resolved automatically.

Tool Reference

ssh_connect

Returns a connection ID used by the other tools.

ssh_execute

Returns stdout, stderr, and exit code. Output is capped at 1MB per stream.

errOnNonZero defaults to false because many commands like grep (no match = exit 1) and diff (differences = exit 1) use non-zero exits for normal results.

ssh_disconnect

ssh_list_connections

No parameters. Returns all connections with host, port, user, and status (connected/dead).

Broken Pipe Handling

• Keepalive packets are sent every 10 seconds to detect dead connections early

• If a connection drops, ssh_execute returns a clear error telling you to reconnect

• An outer timeout wraps the entire TCP + SSH handshake so connections to firewalled/black-hole IPs don't hang forever

• All connections are cleaned up on SIGTERM/SIGINT

Example Session

1. ssh_connect({ host: "myserver" })
   → Connected to 10.0.1.50:2222 as deploy. Connection ID: "myserver"

2. ssh_execute({ connectionId: "myserver", command: "uname -a" })
   → Linux prod-01 5.15.0 #1 SMP x86_64 GNU/Linux
   → Exit code: 0

3. ssh_execute({ connectionId: "myserver", command: "ls", cwd: "/var/log" })
   → syslog auth.log kern.log ...
   → Exit code: 0

4. ssh_list_connections()
   → - myserver: 10.0.1.50:2222 as deploy [connected]

5. ssh_disconnect({ connectionId: "myserver" })
   → Disconnected "myserver".

Security Notes

• Host key verification is not enforced (TOFU — trust on first use). The server accepts any host key.

• Passwords and passphrases are passed as tool parameters and are not persisted, but may appear in MCP client logs depending on your client.

• The server runs with the permissions of the user who started it.

License

MIT