@zyluo/remote-ssh-mcp

Remote SSH MCP

Persistent, stateful remote Bash sessions for AI agents
via the Model Context Protocol

Features · How it works · Tools · Quick start · Config · Security · 简体中文

Why Remote SSH MCP?

Most agents reach remote machines like this:

bash → ssh host "cmd" → disconnect → repeat

Every call pays the same tax:

Pain	What happens
🔁 Token waste	Banners, login noise, and pwd / whoami probes flood the context
🧊 Lost state	cwd, export, venv activation, and shell side effects vanish
🔌 Unstable	Fresh connects hit timeouts, host-key prompts, ProxyJump, and auth jitter
🌀 Error spiral	The model compensates with longer probe commands → more tokens

Remote SSH MCP turns a long-lived remote Bash into first-class MCP tools. One session ID keeps working directory, environment variables, and shell side effects. Open a new session when you need a clean environment.

It does not reimplement SSH. Your system OpenSSH client stays in charge — so ~/.ssh/config, known hosts, the SSH agent, ProxyJump routes, and hardware keys keep working exactly as they already do.

ssh_hosts()              → discover allowed Host aliases
ssh_open(host)           → session id
ssh_run(id, command)     → same cwd + env as last time
ssh_peek / ssh_interrupt → observe or recover long / stuck work
ssh_close(id)            → release the shell and connection

Features

🧠 Persistent remote sessions

• One stable session ID maps to one long-lived remote Bash
• cwd and environment survive across ssh_run calls
• Open a fresh session whenever you need a clean slate
• Multiple sessions can target the same or different hosts (up to maxSessions)

🔧 Native OpenSSH integration

• Spawns the real ssh binary — no custom crypto stack
• Honors ~/.ssh/config, Include, agent sockets, and ProxyJump
• Forces BatchMode=yes and StrictHostKeyChecking=yes
• Never accepts passwords, private-key text, or arbitrary SSH option args from the model

📡 Long-running command friendly

• ssh_run waits up to wait_sec (default 10s), then returns status: "running" while the remote command continues
• Poll with ssh_peek(wait_sec=...) long-poll instead of busy-looping
• Optional hard timeout_sec sends Ctrl-C; no automatic kill by default
• Ideal for docker pull, builds, downloads, and deploys that must not block the tool call forever

🛡️ Safety & control plane

• Exact Host-alias allowlist from ssh_config + optional config / env overrides
• Patterns with *, ?, or ! are ignored
• Fail-closed interrupt: if shell recovery cannot be confirmed after Ctrl-C, the session is closed
• Built-in denylist for a few obviously destructive patterns (not a full policy engine)
• Idle reaping, session caps, and a JSONL audit log (0600) with hashed commands

📦 Clean tool results for models

• Separate stdout / stderr streams
• Head-and-tail byte truncation with valid UTF-8 boundaries
• ssh_hosts returns only safe metadata: alias, hostname, user, port, proxy_jump
• Never leaks IdentityFile, certificates, agent sockets, or ProxyCommand

🔌 MCP-native

• stdio transport for Claude Desktop, Cursor, and other MCP hosts
• Compatible with both legacy and current MCP handshakes
• Parent / stdio exit closes every tracked SSH connection

How it works

flowchart LR
  A[AI Agent] -->|MCP tools| B[Remote SSH MCP]
  B -->|spawn| C[OpenSSH client]
  C -->|SSH + PTY| D[Remote Bash]
  D --> E[(cwd / env / side effects)]

  subgraph Local machine
    B
    C
    F[~/.ssh/config<br/>agent / keys]
    C -.-> F
  end

  subgraph Remote host
    D
    E
  end

Typical agent flow

1. ssh_hosts()                 # pick an alias from the allowlist
2. ssh_open(host="prod")       # get session id "s_…"
3. ssh_run(id, "cd app && …")  # state sticks to this id
4. ssh_run(id, "npm test")     # still in app/, env preserved
5. ssh_peek(id, wait_sec=20)   # long-poll a slow job
6. ssh_close(id)               # clean up when done

MCP tools

Tool	What it does
🗂️ ssh_hosts	List allowed Host aliases (safe metadata only). Pass reload=true after editing ~/.ssh/config
🔓 ssh_open	Open a clean persistent shell for an allowed Host alias → returns session id
▶️ ssh_run	Run a non-interactive command in an existing session
👀 ssh_peek	Latest N lines of output + status; optional wait_sec long-polls while running
⛔ ssh_interrupt	Send Ctrl-C and wait for confirmed shell recovery
📋 ssh_list	List sessions, cwd, state, idle countdown, and capacity
🔒 ssh_close	Tear down remote temp state and close the connection

Tool parameters (essentials)

Tool	Key params
ssh_open	host (required Host alias), optional name label
ssh_run	id, command, optional wait_sec, optional timeout_sec
ssh_peek	id, optional lines (default 50, max 1000), optional wait_sec
ssh_interrupt / ssh_close	id
ssh_hosts	optional reload boolean

Quick start

Requirements

Requirement	Notes
Node.js	20 or newer
OpenSSH client	System ssh on PATH (or set sshPath)
Remote host	Bash + base64, stty, mkdir, cat, rm
SSH setup	Host alias in ~/.ssh/config, host key already trusted

⚠️ First-time host-key confirmation and authentication must be completed in a normal terminal. The MCP server never shows password or trust prompts.

Install

git clone https://github.com/the-nine-nation/remote-ssh-mcp.git
cd remote-ssh-mcp
npm install
npm run build
npm test

Run the server:

node /absolute/path/to/remote-ssh-mcp/dist/index.js

Or install from npm (once published):

npx @zyluo/remote-ssh-mcp
# or
npm install -g @zyluo/remote-ssh-mcp
remote-ssh-mcp

Or, after a local package install from this repo, use the remote-ssh-mcp executable.

MCP host configuration

Most stdio hosts accept a shape like this (outer key may differ by product):

{
  "mcpServers": {
    "remote-ssh": {
      "command": "node",
      "args": [
        "/absolute/path/to/remote-ssh-mcp/dist/index.js"
      ],
      "env": {
        "SSH_MCP_ALLOWED_HOSTS": "prod,staging"
      }
    }
  }
}

Cursor · Claude Desktop · Claude Code · other MCP-capable hosts: point command / args at the built dist/index.js and set SSH_MCP_ALLOWED_HOSTS (or rely on auto-discovery from ~/.ssh/config).

SSH_MCP_ALLOWED_HOSTS adds aliases to the allowlist. By default the server also discovers exact Host entries from ~/.ssh/config and its Include files. Tool inputs accept only safe aliases — not user@host, ports, or extra SSH options.

After editing ~/.ssh/config, call ssh_hosts(reload=true) instead of restarting the server.

Credential boundary

Authentication stays inside the local OpenSSH client:

• Tools never accept passwords or private-key material
• ssh_hosts never returns key paths, certs, agent sockets, or ProxyCommand
• Agents should call ssh_open with a Host alias and must not read ~/.ssh private keys from disk

Configuration

Optional config file (default path):

~/.config/remote-ssh-mcp/config.json

{
  "allowedHosts": ["prod", "staging"],
  "sshConfigPath": "~/.ssh/config",
  "sshPath": "ssh",
  "maxTimeoutSec": 1800,
  "defaultWaitSec": 10,
  "maxWaitSec": 30,
  "openTimeoutSec": 20,
  "idleTimeoutSec": 1800,
  "interruptGraceSec": 5,
  "maxSessions": 8,
  "outputMaxBytes": 32768,
  "outputHeadBytes": 4096,
  "auditLogPath": "~/.local/state/remote-ssh-mcp/audit.jsonl"
}

Environment variables

Variable	Purpose
SSH_MCP_CONFIG	Configuration file path
SSH_MCP_ALLOWED_HOSTS	Comma-separated additional Host aliases
SSH_MCP_SSH_CONFIG	SSH config path
SSH_MCP_SSH_PATH	OpenSSH executable
SSH_MCP_MAX_TIMEOUT_SEC	Max explicit command timeout
SSH_MCP_DEFAULT_WAIT_SEC	How long ssh_run waits before returning running
SSH_MCP_MAX_WAIT_SEC	Max wait_sec on ssh_run / ssh_peek
SSH_MCP_OPEN_TIMEOUT_SEC	Connect / handshake timeout
SSH_MCP_IDLE_TIMEOUT_SEC	Idle session lifetime
SSH_MCP_INTERRUPT_GRACE_SEC	Marker recovery grace after Ctrl-C
SSH_MCP_MAX_SESSIONS	Maximum live sessions
SSH_MCP_OUTPUT_MAX_BYTES	Per-stream retained output limit
SSH_MCP_OUTPUT_HEAD_BYTES	Retained head bytes when truncating
SSH_MCP_AUDIT_LOG	JSONL audit-log path

Environment variables override the file. The audit log is created with mode 0600 and records session, host, result, duration, command length, command name, and SHA-256 — not full argument strings (reduces secret leakage).

Execution semantics

Detailed rules the agent (and you) should know:

Topic	Behavior
Concurrency	One session runs one foreground command at a time; extra ssh_run → busy
wait_sec	Limits only how long the MCP call waits. On expiry: status: "running", remote work continues
Do not retry	Never re-issue the same long command after running — poll with ssh_peek
Hard timeout	Only an explicit timeout_sec creates a deadline that sends Ctrl-C
ssh_peek	Default last 50 lines (max 1000); byte caps still apply; optional long-poll wait_sec
stdin	User commands get /dev/null — no vim, top, or interactive installers
Interrupt recovery	Ctrl-C + grace period for protocol marker; if recovery fails → session closed (fail-closed)
Output	stdout / stderr keep head + tail independently; always valid UTF-8 boundaries
Denylist	Blocks a few high-risk patterns only — not a complete policy engine
Trust model	Local trusted developer tool — not a multi-tenant remote execution service
Host exit	MCP host / stdio death closes all SSH connections; nohup / setsid jobs may survive

Example: start docker pull with wait_sec: 10 and no timeout_sec. A running result means the original pull is still active — do not start another. Call ssh_peek with a positive wait_sec until idle, interrupt it, or open another session for parallel work.

Development

npm run typecheck
npm test
npm run build
npm audit --omit=dev

The test suite covers MCP stdio discovery and calls, persistent cwd / environment state, stream separation, framing across arbitrary chunk boundaries, timeout fail-closed behavior, shell death, allowlist discovery, output truncation, and the safety denylist.

Design notes and wire protocol: 远程SSH-MCP设计.md.

Security

Please do not report security vulnerabilities through public GitHub issues. Until a private advisory workflow is configured, contact the maintainer via the email on their GitHub profile.

Remote commands can have irreversible side effects even when the MCP transport is healthy. Use least-privilege accounts, keep the allowlist narrow, and review host permissions carefully.

Project status

Item	Status
Version	0.2.1
License	MIT
Language	TypeScript (Node ≥ 20)
Protocol	MCP over stdio
Transport to host	System OpenSSH

Star History

If this project saves you tokens and flaky reconnects, a ⭐ on GitHub helps others find it.

_{Built for agents that need a real remote shell — not another one-shot ssh host "…".}