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:

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):

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/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 parameters (essentials)

Quick start

Requirements

⚠️ 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

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:

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

Changelog

Unreleased — Connection and progress feedback

• Custom sshConfigPath / SSH_MCP_SSH_CONFIG now controls the actual connection through OpenSSH -F, as well as host discovery. The default ~/.ssh/config keeps native OpenSSH behavior; a custom file follows -F semantics (system-wide config is skipped).
• Host discovery also accepts Host=prod, HostName = example.com, and Include=... syntax.
• ssh_open failures include a reason and actionable hint for host trust, authentication, DNS, network, timeout, and local setup issues, alongside the original error.
• Short progress output is delivered immediately unless its suffix could be a partial protocol marker.
• Completed ssh_peek responses include command_status and duration_ms, keeping shell state (idle) separate from the command outcome. A peek already waiting when a session dies retains available output and timeout/interruption details. Later calls to the removed session still return session_gone.

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.

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 public release on npm / GitHub

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 "…".}