Skip to main content
Glama
caikiji

mcp-ssh

by caikiji
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

✨ 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

Related MCP server: MCP SSH Manager

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 deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches