MCP server for SSH remote execution, file transfer, file editing
with automatic backup/trash & ~/.ssh/config integration
npm version npm downloads github stars 中文文档 node version license
Installation · Configuration · Tools · Backup & Trash · 中文文档
- 🔐 SSH via env — register multiple servers with password or key auth in a single env var
- 📋 Config integration — use or auto-import
~/.ssh/confighosts ($config) - 💻 Remote exec — run commands with optional timeout, PTY, and sudo password support
- 📁 File transfer — upload/download via SFTP
- 📝 File editing — read, write, search/replace, line operations with automatic backup
- 🗑️ Trash protection — deleted files go to
~/.mcp-ssh/trash/(configurable threshold) - 🐞 Debug mode —
SSH_DEBUG=truefor connection/exec/SFTP diagnostics
npm install -g @caikiji/mcp-ssh
Register servers via environment variable. Separate multiple entries with ;.
SSH_SERVICES="web:root@192.168.1.100:22|/path/to/id_rsa;db:deploy@db.internal|db_password"
Format: [name:]user@host[:port]|credential
| Part | Description |
|---|---|
name |
Optional display name (defaults to host). Duplicates get a numeric suffix. |
port |
Optional, defaults to 22. |
credential |
File path → SSH key, otherwise treated as password. |
Reference any Host from ~/.ssh/config by name (no @ needed):
SSH_SERVICES="production|password;db:db-server|"- Empty credential (
|at end) → usesIdentityFilefrom config [name:]config_host→ custom display name
Import every config host that has both User and IdentityFile:
SSH_SERVICES="$config" # Mixed with regular entries: SSH_SERVICES="$config;extra:root@other.host|password"
Config changes take effect on the next tool call — no MCP restart required.
| Variable | Default | Description |
|---|---|---|
SSH_TIMEOUT |
15000 |
Connection timeout (ms) |
SSH_LARGE_FILE_MB |
10 |
Files larger than this (MB) skip backup/trash |
SSH_DEBUG |
— | Set to true for debug logging to stderr |
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": ["-y", "@caikiji/mcp-ssh"],
"env": {
"SSH_SERVICES": "$config;web:root@192.168.1.100|/path/to/key"
}
}
}
}| Tool | Arguments | Description |
|---|---|---|
list_servers |
— | List all configured servers with address and auth type |
| Tool | Arguments | Description |
|---|---|---|
exec |
server, command, [workdir], [timeout], [pty], [sudo_password] |
Run any shell command. workdir prepends cd <path> &&. timeout limits execution (seconds). pty: true allocates a TTY for apt/tmux/etc. sudo_password runs via sudo -S <cmd> (password sent via stdin, no PTY needed). |
| Tool | Arguments | Description |
|---|---|---|
upload |
server, local_path, remote_path |
Upload a local file via SFTP |
download |
server, remote_path, local_path |
Download a remote file via SFTP |
| Tool | Arguments | Description |
|---|---|---|
read |
server, remote_path, [offset], [limit], [mode], [count] |
Read file. mode:text (default), head, tail (via exec, zero transfer). count for head/tail (default 50). offset 1-indexed, for text mode. |
write |
server, remote_path, content, [mode] |
Create/overwrite (mode: "write", default) or append (mode: "append") to a file. Auto-backup before overwrite. |
update |
server, remote_path, search+replace+[replace_all] or line+content+[position] |
Edit existing file: search/replace (all or first), or line operations (replace, insert before/after, delete range). Backup before modification. |
rm |
server, remote_path |
Remove file/dir with trash protection (≤10MB → trash) |
ls |
server, remote_path |
List dir entries or get single file details (name, type, size, mtime, permissions) |
~/.mcp-ssh/
├── backups/<server>/<path>.bak.1-3 ← auto-rotated before overwrite
└── trash/<server>/<path>.<timestamp> ← small files (≤10MB) on delete
Check real usage via exec:
exec server, "du -sh ~/.mcp-ssh"