🔌 @caikiji/mcp-ssh

MCP server for SSH remote execution, file transfer, file editing
with automatic backup/trash & ~/.ssh/config integration

Installation · Configuration · Tools · Backup & Trash · 中文文档

✨ Features

• 🔐 SSH via env — register multiple servers with password or key auth in a single env var
• 📋 Config integration — use or auto-import ~/.ssh/config hosts ($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=true for connection/exec/SFTP diagnostics

Installation

npm install -g @caikiji/mcp-ssh

Configuration

SSH_SERVICES

Register servers via environment variable. Separate multiple entries with ;.

SSH_SERVICES="web:[email protected]:22|/path/to/id_rsa;db:[email protected]|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.

Using ~/.ssh/config

Reference any Host from ~/.ssh/config by name (no @ needed):

SSH_SERVICES="production|password;db:db-server|"

• Empty credential (| at end) → uses IdentityFile from config
• [name:]config_host → custom display name

Auto-import all config hosts ($config)

Import every config host that has both User and IdentityFile:

SSH_SERVICES="$config"
# Mixed with regular entries:
SSH_SERVICES="$config;extra:[email protected]|password"

Config changes take effect on the next tool call — no MCP restart required.

Environment variables

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

MCP Client config

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@caikiji/mcp-ssh"],
      "env": {
        "SSH_SERVICES": "$config;web:[email protected]|/path/to/key"
      }
    }
  }
}

Tools

Server Management

Tool	Arguments	Description
list_servers	—	List all configured servers with address and auth type

Command Execution

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).

File Transfer

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

File Operations

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)

Backup & Trash

~/.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"

---

📖 中文文档