Skip to main content
Glama
Remote SSH MCP

Remote SSH MCP


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

Related MCP server: TerminusAI

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

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.2

License

MIT

Language

TypeScript (Node ≥ 20)

Protocol

MCP over stdio

Transport to host

System OpenSSH


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.

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.

Available Tools

7 tools
ssh_closeClose persistent SSH sessionA
DestructiveIdempotent

Close the remote shell and SSH connection, clean its private temporary directory, and invalidate the id. Close a dirty session and call ssh_open for a clean environment.

Inputs: id (required).

ssh_hostsList allowed SSH Host aliasesA
Read-onlyIdempotent

List allowed OpenSSH Host aliases discovered from the local ssh_config (and explicit allowlist). Returns only safe connection metadata: alias, hostname, user, port, proxy_jump. Never returns private keys, IdentityFile paths, agent sockets, or ProxyCommand. Pass reload=true after editing ~/.ssh/config to re-parse without restarting the MCP server. Use an alias from this list with ssh_open.

Inputs: reload.

ssh_interruptInterrupt SSH foreground commandA
Destructive

Send Ctrl-C to the current foreground process group and wait for the shell protocol to recover. The session is kept only when recovery is confirmed. Returns nothing_to_interrupt when idle.

Inputs: id (required).

ssh_listList persistent SSH sessionsA
Read-onlyIdempotent

List all live sessions with host, cwd, state, last exit code, idle time, idle-reap countdown, and connection capacity. Use this to recover valid ids; never invent one.

Inputs: no named parameters.

ssh_openOpen persistent SSH sessionA

Open a new persistent remote bash shell for an allowed ssh_config Host alias from ssh_hosts. Each call creates a clean session with a new id. Credentials come only from local OpenSSH configuration/agent; passwords and private keys are never accepted as arguments and must not be read from disk by the model.

Inputs: host (required), name.

ssh_peekPeek at SSH command outputA
Read-onlyIdempotent

Observe the current foreground command and its latest output without starting another command. When status=running, optional wait_sec (default 0) long-polls this MCP call until the command finishes or the wait expires—prefer a positive wait_sec over busy-looping. wait_sec never stops the remote command. Returns the newest lines in chronological order, limited independently for stdout and stderr; lines defaults to 50 and is capped to protect model context. Use after ssh_run returns status=running. When idle, returns immediately with cwd, last exit code, and the latest lines from the completed command.

Inputs: id (required), lines, wait_sec.

ssh_runRun command in persistent SSH sessionA
Destructive

Start a non-interactive command in the same persistent shell identified by id. cwd and environment changes persist. The call waits at most wait_sec (default 10 seconds); if the command is still active it returns status=running without stopping it. Commands have no automatic execution timeout by default. Only an explicitly provided timeout_sec sends Ctrl-C at that deadline. Never retry a running command: poll with ssh_peek(wait_sec=...) so the MCP call blocks until idle or the wait expires; do not spam peeks with wait_sec=0. Call ssh_interrupt to stop it, or open another session for concurrent work. Only one foreground command may run per id. Do not use vim, top, password prompts, or other interactive TUI/input flows.

Inputs: id (required), command (required), wait_sec, timeout_sec.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool maps to a discrete part of the SSH session lifecycle: discover hosts, open a session, run a command, interrupt, peek output, list sessions, and close. No two tools could plausibly be selected for the same action.

    Naming Consistency4/5

    Most tools follow a consistent ssh_<verb> pattern: open, run, interrupt, peek, list, close. However, ssh_hosts is a noun-resource name rather than an action verb, and ssh_list is slightly generic, so the pattern has minor deviations.

    Tool Count5/5

    Seven tools cover the full remote-shell workflow without redundancy. Each tool has a clear role, and none feel like filler or unnecessary overlap.

    Completeness5/5

    The lifecycle is complete: discover allowed hosts, open persistent shells, run commands, poll and interrupt active commands, enumerate live sessions, and cleanly close. There are no obvious missing operations for the stated remote-shell purpose.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to securely execute shell commands on local machines through an SSH interface with session management, command execution, and sudo support.
      1
      -
    • A
      license
      B
      quality
      D
      maintenance
      Execute terminal commands locally or remotely via SSH with session persistence and environment variable support. Manage terminal sessions that maintain state for up to 20 minutes, enabling efficient command execution workflows. Connect using stdio or SSE for flexible integration with AI models and a
      1
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to run commands on remote SSH-accessible devices via persistent sessions, supporting both POSIX and CLI shells with safety filters.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Persistent SSH sessions for AI assistants, enabling long-running remote shell connections with features like file transfer, port forwarding, and swarm mode.
      56
      MIT