🔌 @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: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. |

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:root@other.host|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:root@192.168.1.100|/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"

📖 中文文档