SSH MCP Server
This server lets an AI assistant securely execute commands, transfer files, and manage SSH connections to remote servers using aliases — without ever exposing real hostnames, usernames, or credentials to the model.
Core capabilities:
Execute remote commands (
ssh_exec): Run any shell command on a remote server and get back stdout, stderr, and exit code.Upload files/directories (
ssh_upload): Upload a single file, a glob pattern (e.g.logs/*.gz), or an entire directory (withrecursive=true). Optionally preserve file permissions and timestamps withpreserve=true.Download files/directories (
ssh_download): Download a single file, a glob pattern (e.g./var/log/*.log), or an entire directory (withrecursive=true). Also supports thepreserveoption.List remote directory contents (
ssh_list): Browse files in a specified directory on the remote server.List configured server aliases (
ssh_list_servers): View all available server aliases and their descriptions — without revealing real hosts, IPs, or usernames.
Key security features:
All servers are referenced by alias only (e.g.
prod,server1); real connection details never reach the AI model.Supports multiple auth methods: SSH keys (recommended), environment-variable passwords, inline passwords, or full passthrough to
~/.ssh/config.ProxyJump/bastion host support via native
ssh2or passthrough mode.Connection errors are sanitized so no real host/IP/username leaks to the assistant.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SSH MCP Server run 'systemctl status nginx' on prod"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 whatprodresolves to.Real
scp/rsync/ProxyJumpsupport via passthrough mode when you want it.
Related MCP server: ssh-mcp
Tools
Tool | Description |
| Run a command on a server. Returns stdout/stderr/exit code. |
| Upload a file, a glob ( |
| Download a file, a glob, or a whole directory ( |
| List a remote directory. |
| List configured aliases and their descriptions. Never exposes hosts. |
Install
git clone <this-repo> sshmcp
cd sshmcp
npm installRequires 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": truereuses 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.
ProxyJump (e.g. reaching Proxmox VMs / hosts behind a bastion)
Add proxyJump to reach a target that isn't directly reachable — such as a VM on a Proxmox host's internal network. It works in both modes:
Passthrough:
proxyJumpis an ssh host/alias passed toscp -J/ssh -J."vm-web": { "sshConfigHost": "vm-web", "proxyJump": "pmx" }(Equivalent to putting
ProxyJump pmxin the Host block in~/.ssh/config, which also just works.)Native (ssh2):
proxyJumpnames another configured native alias to tunnel through. Chains are supported (a jump may have its own jump)."vm-web": { "host": "10.10.0.50", "username": "root", "privateKeyPath": "~/.ssh/vm_key", "proxyJump": "server1" }
The jump host's real address is scrubbed from output alongside the target's.
Register with Claude Code
claude mcp add ssh --scope user -- node /absolute/path/to/sshmcp/ssh-server.jsMCP servers are not configured in
settings.json— useclaude 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 -Gserver-side only to scrub them from output; that data never enters the assistant's context.Prefer keys or
passwordEnvover 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 a755source becomes666when Windows is one end. Linux↔Linux (server-to-server style) is unaffected.Glob matches a single directory level; use
recursive=truefor 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
Available Tools
5 toolsssh_downloadA
Download from a remote server over SFTP. Supports a single file, a glob pattern within a remote directory (e.g. /var/log/*.log) which downloads all matches into localPath, or a whole remote directory when recursive=true.
Inputs: localPath (required), remotePath (required), serverAlias (required), preserve, +1 more.
ssh_execB
Execute a command on a remote server
Inputs: command (required), serverAlias (required).
ssh_listB
List files in a remote directory
Inputs: serverAlias (required), remotePath.
ssh_list_serversA
List all configured server aliases and their descriptions
Inputs: no named parameters.
ssh_uploadA
Upload to a remote server over SFTP. Supports a single file, a glob pattern (e.g. logs/*.gz) which uploads all matches into remotePath, or a whole directory when recursive=true.
Inputs: localPath (required), remotePath (required), serverAlias (required), preserve, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: download, execute, list files, list servers, and upload. No overlap or ambiguity.
All tools follow a consistent 'ssh_verb_noun' pattern using snake_case, with descriptive verbs like download, exec, list, and upload.
5 tools is well-scoped for an SSH server, covering core operations (execution, file transfer, listing) without being excessive or insufficient.
The set covers essential SSH operations (exec, list, download, upload) but lacks directory creation/deletion or file renaming, which are minor gaps.
Related MCP Connectors
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI assistants full SSH/SFTP remote operations — session management, command execution, interactive shells, file transfers, port forwarding, and system diagnostics.2MIT
- AlicenseAqualityCmaintenanceAn MCP server that gives AI agents SSH access to remote machines through your local OpenSSH client, enabling remote command execution, file transfer, persistent shell sessions, and port forwarding.17432 PyPI40MIT
- AlicenseAqualityBmaintenanceAn open MCP server that gives any AI agent SSH access to remote Linux/Unix machines — shell commands, file read/write, and SFTP transfers.1116 PyPIMIT
- AlicenseNot gradedqualityFmaintenanceA security-first MCP server that gives AI assistants controlled, safe access to manage remote servers via SSH with whitelisted operations and no generic command execution.MIT