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

Tool	Description
ssh_connect	Open an SSH connection to a remote host
ssh_execute	Run a command on a connected host
ssh_disconnect	Close a connection
ssh_list_connections	Show all connections and their status

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

Parameter	Type	Required	Description
host	string	yes	Hostname, IP, or SSH config alias
username	string	no	Override SSH config user
port	number	no	Override SSH config port (default 22)
password	string	no	Password auth
privateKeyPath	string	no	Path to private key (e.g. ~/.ssh/id_ed25519)
passphrase	string	no	Passphrase for encrypted private key
useAgent	boolean	no	Use SSH agent (default: true if no other auth given)
connectTimeout	number	no	Timeout in ms for TCP + handshake (default 20000)
connectionId	string	no	Custom ID for this connection (default: host value)

Returns a connection ID used by the other tools.

ssh_execute

Parameter	Type	Required	Description
connectionId	string	yes	Connection ID from ssh_connect
command	string	yes	Shell command to run
cwd	string	no	Working directory (wraps as cd <cwd> && <command>)
timeout	number	no	Command timeout in ms (default 30000)
errOnNonZero	boolean	no	Mark non-zero exit as MCP error (default false)

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

Parameter	Type	Required	Description
connectionId	string	yes	Connection ID to close

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