SSH MCP Server

An MCP server that lets an AI assistant (Claude Code, Claude Desktop, etc.) run commands and transfer files over SSH — without ever seeing your real connection details. The assistant only works with aliases like prod or server1; hostnames, usernames, keys, and passwords stay on your machine.

Built on the official @modelcontextprotocol/sdk and ssh2, with an optional passthrough mode that shells out to your system ssh/scp and reads ~/.ssh/config.

Why

• Credentials never reach the model. Real host/user/IP live in your local config (or ~/.ssh/config) and are scrubbed from all output before the assistant sees it.
• Alias-only surface. The assistant calls ssh_exec("prod", "..."); it has no idea what prod resolves to.
• Real scp/rsync/ProxyJump support via passthrough mode when you want it.

Tools

Tool	Description
ssh_exec	Run a command on a server. Returns stdout/stderr/exit code.
ssh_upload	Upload a file, a glob (logs/*.gz), or a whole directory (recursive=true). preserve=true keeps mode+timestamps (scp -p).
ssh_download	Download a file, a glob, or a whole directory (recursive=true). Same preserve option.
ssh_list	List a remote directory.
ssh_list_servers	List configured aliases and their descriptions. Never exposes hosts.

Install

git clone <this-repo> sshmcp
cd sshmcp
npm install

Requires Node 18+. Passthrough mode additionally needs the OpenSSH client (ssh/scp) on your PATH — built into Windows 10/11, macOS, and Linux.

Configure your servers

Create ~/.claude/ssh-servers.json (or anywhere, and point SSH_CONFIG_PATH at it). Each entry is an alias. Pick one auth method per server.

A. SSH key (recommended)

{
  "server1": {
    "description": "Main deploy box",
    "host": "10.0.0.5",
    "port": 22,
    "username": "deploy",
    "privateKeyPath": "~/.ssh/id_ed25519"
  }
}

B. Password from an environment variable

{
  "box": {
    "host": "10.0.0.6",
    "username": "admin",
    "passwordEnv": "BOX_PASS"
  }
}

Then export BOX_PASS before the server starts.

C. Direct password (local/testing only)

{
  "box": { "host": "10.0.0.6", "username": "admin", "password": "secret" }
}

D. SSH-config passthrough (most secure, full scp/rsync)

{
  "prod": { "description": "Main prod", "sshConfigHost": "prod" }
}

When an entry has sshConfigHost, the tools shell out to the system ssh/scp using that Host alias from ~/.ssh/config. HostName, User, IdentityFile, ProxyJump, etc. all come from there and never appear in this file — no credentials live in ssh-servers.json at all. Real hostnames/users/IPs are scrubbed from output.

• "sshConfigHost": true reuses the JSON alias as the Host name.
• "sshConfigHost": "prod" maps to a differently-named Host in ~/.ssh/config.
• Requires key/agent auth (ssh config holds no passwords).

Methods can be mixed freely across servers in one file. See ssh-servers.example.json.

Register with Claude Code

claude mcp add ssh --scope user -- node /absolute/path/to/sshmcp/ssh-server.js

MCP servers are not configured in settings.json — use claude mcp add (writes ~/.claude.json) or a project .mcp.json.

Set a custom config path with the SSH_CONFIG_PATH env var if you don't use ~/.claude/ssh-servers.json.

After adding (or editing the server), fully restart Claude Code — MCP tools load at session startup, so a running session won't pick up changes.

Usage examples

# run a command
ssh_exec(serverAlias="prod", command="systemctl status nginx")

# upload a build, preserving permissions and timestamps
ssh_upload(serverAlias="prod", localPath="./dist", remotePath="/var/www/app", recursive=true, preserve=true)

# pull all logs matching a glob
ssh_download(serverAlias="prod", remotePath="/var/log/*.log", localPath="./logs")

Security model

• The config file holds credentials and is .gitignored. chmod 600 ~/.claude/ssh-servers.json.
• Connection errors are sanitized — host/IP/username are replaced with the alias before returning.
• Passthrough mode resolves the real host/user via ssh -G server-side only to scrub them from output; that data never enters the assistant's context.
• Prefer keys or passwordEnv over inline passwords.

Notes & limitations

• Windows + preserve: timestamps are preserved reliably in both directions; Unix permission bits are limited by what Windows (NTFS) can represent — Windows has no execute bit, so a 755 source becomes 666 when Windows is one end. Linux↔Linux (server-to-server style) is unaffected.
• Glob matches a single directory level; use recursive=true for whole trees.
• Symlinks are skipped during recursive directory walks to avoid cycles.
• Passwords are not supported in passthrough mode (ssh config holds none); give those hosts a key to use mode D.

License

MIT