Remote Ssh Mcp

Remote SSH MCP

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

Why · 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, MOTD, 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.

Why pick this over one-shot ssh in bash?

Concrete gains for agent workflows (multi-step remote work: deploy, debug, build, inspect logs):

| Dimension | One-shot ssh host "…" | Remote SSH MCP | |-----------|-------------------------|---------------------| | 💰 Tokens | Each step re-pays connect noise + state probes; models often re-cd / re-pwd | Pay once on ssh_open; later ssh_run returns mostly command output. Structured tools + head/tail caps cut tool-result bloat. In multi-step sessions this commonly cuts remote-tool context by ~50–80% vs reconnect-every-time (exact savings depend on MOTD size and how chatty the model is). | | ✅ Success rate | N steps ≈ N handshakes → N chances to fail (timeout, jump, agent, host key) | One handshake per session; subsequent commands ride a live shell. Long jobs use running + ssh_peek instead of killing the tool call and restarting. Fewer reconnects → far fewer false “SSH failed” loops mid-task. | | 🧳 Portability | Remote needs nothing extra — but every agent machine reimplements the same brittle ssh … patterns | Install once on the machine that runs Claude / Cursor / Grok / etc. Remote hosts install nothing (no Node, no MCP daemon, no agent). Only a normal shell account + tools already required for SSH (bash, base64, stty, …). Keys and jump hosts stay in local ~/.ssh/config. | | 🧠 Model ergonomics | Model invents ssh strings, escapes, and recovery | Stable tools: open → run → peek → close. Session id is the only handle. | | 🔐 Trust boundary | Easy to over-expose keys or prompt for passwords in-band | OpenSSH client only; tools never accept passwords or private-key material |

Portability in one line: put the MCP on your dev box / AI host; every server already in your SSH config is reachable — zero package install on the remote fleet.

┌─────────────────────────┐         SSH (OpenSSH)         ┌──────────────────┐
│  Your laptop / CI agent │  ───────────────────────────► │  prod / staging  │
│  Claude · Cursor · Grok │     ~/.ssh/config · agent     │  no MCP install  │
│  + remote-ssh-mcp       │                               │  plain Bash OK   │
└─────────────────────────┘                               └──────────────────┘

Token sketch (illustrative multi-step remote debug):

One-shot path (per step × 8):
  ssh wrapper + banner/MOTD + pwd/whoami + re-cd + command output
  → noise dominates; context fills with reconnect junk

Session path:
  ssh_open  → once (handshake + READY)
  ssh_run × 8 → mostly the real stdout/stderr (truncated head+tail)
  → context stays on the work product, not the transport

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
• ANSI / PTY noise stripped before the model sees output (colors, CSI, bracketed-paste markers, control-only blank lines)
• Quiet open-frame: TERM=dumb, NO_COLOR, bracketed-paste off — less junk at the source
• Slim JSON payloads: omit empty stderr, false truncation flags, and request-echo fields so dual content + structuredContent stays cheap
• 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/configagent / 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](./远程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.2 | | License | [MIT](./LICENSE) | | Language | TypeScript (Node ≥ 20) | | Protocol | MCP over stdio | | Transport to host | System OpenSSH |

---

Changelog

0.2.2 — quieter remote output, fewer tokens

PTY-backed interactive bash often injects escape sequences that look like “binary” when JSON-escaped (\u001b[?2004h, color CSI, cursor codes). That noise burned context on every ssh_peek / ssh_run.

| Change | What it does | |--------|----------------| | Present-time sanitize | Strip ANSI/OSC/CSI, honor CR overwrite (progress bars), drop control-only blank lines, then apply the lines window | | Quiet session open | Export TERM=dumb / NO_COLOR / CLICOLOR=0, disable bracketed paste, send \033[?2004l once at open | | Slim tool payloads | Drop empty stderr, false flags (truncated, interrupted, …), and echoed lines; keep empty stdout so silence stays explicit | | Tests | Coverage for sanitize, open-frame quieting, session present path, and slim JSON |

Upgrade: npm i -g @zyluo/remote-ssh-mcp@0.2.2 (or bump the package in your MCP config), then restart the MCP process so the new server binary is loaded.

0.2.1

• Fix READY-marker parsing when the open frame is PTY-echoed

0.2.0

• Initial

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: the-nine-nation
• Source: the-nine-nation/remote-ssh-mcp
• License: MIT
• Homepage: https://github.com/the-nine-nation/remote-ssh-mcp#readme

Install and usage instructions live in the source repository linked above.