---
## Why Remote SSH MCP?
Most agents reach remote machines like this:
```text
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**.
```text
โโโโโโโโโโโโโโโโโโโโโโโโโโโ 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):**
```text
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.
```text
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
```mermaid
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**
```text
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
```bash
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:
```bash
node /absolute/path/to/remote-ssh-mcp/dist/index.js
```
Or install from npm (once published):
```bash
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):
```json
{
"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):
```text
~/.config/remote-ssh-mcp/config.json
```
```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
```bash
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](https://github.com/the-nine-nation/remote-ssh-mcp/blob/HEAD/่ฟ็จ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](https://github.com/the-nine-nation).
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](https://github.com/the-nine-nation/remote-ssh-mcp/blob/HEAD/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 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 "โฆ".
