SSH Host Storage & Remote Exec

mcp-ssh-server

A standalone stdio MCP server that turns *SSH host management* and *remote command execution* into MCP tools.

It also ships an interactive / batch CLI (remote-ssh-cli) for managing SSH hosts on the local machine.

简体中文文档见 README.zh-CN.md。

This is a Node.js re-implementation of the SSH-host half of a FastAPI project (app/services/llm_tools.py + app/utils/ssh_helper.py + app/models/host.py) — without the backend, without the database, without a network service. Any MCP client (Claude Desktop, Continue, a custom agent, …) can start it with npx and talk to it over JSON-RPC.

Highlights

• Fully standalone — its own encrypted JSON store (~/.mcp-ssh-server/hosts.json); no FastAPI backend, no database.
• No native dependencies — Node's built-in crypto for AES-256-GCM, pure-JS ssh2 for SSH; runs on Windows / macOS / Linux.
• Standards-compliant stdio MCP — speaks the Model Context Protocol stdio transport and can be launched with npx.
• Credentials never leave the server — host tool responses never contain a password or a private key; the SSH tools decrypt them internally to open a connection and never echo them back.
• Connection pooling — one live SSH session per host, reused across commands and playbook steps.
• Pool monitoring — pool_status renders the live pool as a desensitized table: uid, name, connection state, executed / failed commands and the last command (secrets and IP addresses masked).
• CLI companion — remote-ssh-cli manages the very same store (interactive TUI, batch commands, CSV bulk import) and can monitor the connection pool live (one frame per second, q quits).

MCP tools

Nine tools are published:

The host identifier contract

• host_list is the entry point: every host comes back as exactly two fields — sys_name (the name) and uid (the unique identifier).
• Every other tool takes that same value under the name host_id. Pass it back unchanged; never assemble or guess one.
• When an id does not resolve, the tool answers with an actionable error: Host ' ' not found. host_id must be the exact 'uid' value returned by host_list — call host_list to obtain the valid identifiers. Call host_list again and retry with the value it returns.
• host_get is deliberately not published to MCP clients: the model only ever sees sys_name + uid, never one host's address, user name or credential. The CLI keeps its own get subcommand for human operators.

Arguments at a glance

ip_address is unique across the store — creating a duplicate fails.

Command results come back as a plain text block:

[stdout]

hello [stderr] [exit_code=0 success=true duration_ms=42]

Quick start

git clone https://github.com/xlbbb-cn/mcp_ssh_exec_cmd.git

cd mcp_ssh_exec_cmd npm install npm run build

The build output lands in dist/ and provides two binaries:

Install

The package is published to two registries under the same name, @xlbbb-cn/mcp_ssh_exec_cmd:

GitHub Packages requires authentication for installs as well — even for public packages — so give npm a token first:

npm login --scope=@xlbbb-cn --auth-type=legacy --registry=https://npm.pkg.github.com

Username:

Password:

The same thing can be written into ~/.npmrc:

//npm.pkg.github.com/:_authToken=<PAT>

@xlbbb-cn:registry=https://npm.pkg.github.com

Global install (CLI)

From a local checkout:

npm run build

npm install -g --allow-scripts=ssh2,cpu-features .

Or straight from a registry:

npm install -g @xlbbb-cn/mcp_ssh_exec_cmd                                      # npmjs.org

npm install -g @xlbbb-cn/mcp_ssh_exec_cmd --registry=https://npm.pkg.github.com # GitHub Packages

Afterwards remote-ssh-cli is on your PATH:

remote-ssh-cli                        # interactive TUI

remote-ssh-cli list # JSON list of every host remote-ssh-cli get remote-ssh-cli create remote-ssh-cli update remote-ssh-cli delete remote-ssh-cli import [--dry-run] remote-ssh-cli monitor # live connection-pool monitor (q quits)

create / update take a JSON file, e.g.:

{

"ip_address": "192.168.1.100", "system_name": "web-01", "ssh_port": 22, "ssh_username": "root", "ssh_auth_method": "password", "ssh_password": "your-password" }

CSV bulk import

remote-ssh-cli import hosts.csv turns every row of the file into one host. The first line must be a header row containing at least an ip_address column:

ip_address,system_name,ssh_port,ssh_username,ssh_auth_method,ssh_password

192.168.1.100,web-01,22,root,password,secret 192.168.1.101,db-01,2222,deploy,password,secret

• Column names are case-insensitive and accept aliases (ip, host, name, port, user, password, …).
• Quoted commas, embedded newlines and "" escapes are parsed per RFC 4180, so private key material is never mangled.
• A bad row never aborts the batch: every row ends up reported as created / skipped (duplicate IP) / failed (invalid data). The command prints a summary and exits with code 1 when at least one row failed.
• --dry-run only validates and reports — nothing is written.
• The CSV template (header + example row) is printed in the remote-ssh-cli banner, and remote-ssh-cli import without a file argument prints the same thing.

Windows note: if you hit JScript runtime error (800A03EA), make sure npm is >= 10.8.0 or run the command from cmd.exe instead of PowerShell — the .ps1 wrapper npm generates may not invoke node explicitly on older npm versions. Both entry points ship a #!/usr/bin/env node shebang.

Monitor the connection pool

remote-ssh-cli monitor opens a live view of the SSH connection pool. The screen is redrawn once per second and the view is left with the `q` key (Ctrl+C works as well):

SSH connection pool monitor · 15:05:31 · tick 42 · refresh 1000ms · last tick 41ms

pool 2/32 connections · idle timeout 1m00s · probe timeout 5s · press q to quit

HOST ADDRESS USER STATUS LATENCY LAST OK POOL

web-01 192.168.1.100 root up 12ms 15:05:30 1m05s db-01 10.0.0.5:2222 deploy down 8ms - -

problems (1): db-01 (10.0.0.5:2222): connect ECONNREFUSED 10.0.0.5:2222

• The monitor keeps the pool warm: every host is probed through the very same ConnectionPool the SSH tools use, so the connections it shows are real, reusable sessions.
• The CLI runs its own pool — the MCP server is a separate process, so its connections cannot be inspected from the terminal.
• The default probe command is echo (it exists in a POSIX shell *and* in cmd.exe); every probe runs once per interval, so keep --interval reasonable on large host lists.
• Without a terminal (a pipe, a CI job) the monitor prints a single frame instead of looping — there would be no key to stop it.

The same view is available from the interactive TUI (7) Monitor connection pool).

Register it with an MCP client

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{

"mcpServers": { "ssh": { "command": "npx", "args": ["-y", "-p", "@xlbbb-cn/mcp_ssh_exec_cmd", "remote-ssh-server"] } } }

On GitHub Packages, add the registry to the same snippet:

"args": [

"--registry=https://npm.pkg.github.com", "-y", "-p", "@xlbbb-cn/mcp_ssh_exec_cmd", "remote-ssh-server" ]