How do I use mcp-ssh?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-ssh execute 'ls -la /home' on production" 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.

mcp-ssh by caikiji

✨ 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"

This server cannot be installed

A

license - permissive license

-

quality - not tested

C

maintenance

How are these scores calculated?

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

mcp-ssh

✨ Features

Installation

Configuration

`SSH_SERVICES`

Using `~/.ssh/config`

Auto-import all config hosts (`$config`)

Environment variables

MCP Client config

Tools

Server Management

Command Execution

File Transfer

File Operations

Backup & Trash

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

✨ Features

Installation

Configuration

SSH_SERVICES

Using ~/.ssh/config

Auto-import all config hosts ($config)

Environment variables

MCP Client config

Tools

Server Management

Command Execution

File Transfer

File Operations

Backup & Trash

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

`SSH_SERVICES`

Using `~/.ssh/config`

Auto-import all config hosts (`$config`)