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:

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 agent / keys] C -.-> F end

subgraph Remote host D E end

Typical agent flow

1. ssh_hosts()                 # pick an alias from the allowlist

1. ssh_open(host="prod") # get session id "s_…"
2. ssh_run(id, "cd app && …") # state sticks to this id
3. ssh_run(id, "npm test") # still in app/, env preserved
4. ssh_peek(id, wait_sec=20) # long-poll a slow job
5. 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 bu