What can you do with this server?

The Remote SSH MCP server provides persistent, stateful SSH sessions for AI agents, enabling long-lived remote shell operations with easy session management. Key capabilities: * List allowed hosts (ssh_hosts) – shows safe metadata for permitted Host aliases from SSH config. * Open session (ssh_open) – starts a persistent remote Bash shell for an allowed host, returning a session ID. * Run commands (ssh_run) – executes non-interactive commands in a session, preserving working directory and environment across calls; supports optional wait/timeout and is designed for long-running tasks (returns early with running status). * Peek at output (ssh_peek) – retrieves recent stdout/stderr and command status; long-polling waits for completion. * Interrupt command (ssh_interrupt) – sends Ctrl‑C to the foreground process, with recovery confirmation; session closed on failure. * List sessions (ssh_list) – shows active sessions with host, cwd, state, exit code, idle time, and capacity. * Close session (ssh_close) – terminates remote shell and SSH connection, cleans up temporary files. Security & integration: * Enforces host allowlist and destructive-command denylist; idle reaping, output truncation, and audit logging. * Uses the system OpenSSH client, honoring ~/.ssh/config, agent forwarding, ProxyJump; never accepts passwords or keys from tools – credentials remain local.

How do I use Remote SSH MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Remote SSH MCP Open a session to prod and run 'df -h'" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Remote SSH MCP

by the-nine-nation

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Local

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

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.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds valuable behavioral details: it cleans a private temporary directory and invalidates the id. This surpasses what annotations alone convey, while remaining consistent with them. There is no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief, two sentences, with the primary action stated upfront. Every sentence adds value: the first defines the behavior, the second gives a practical use case. No filler or redundant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema) and the annotations covering safety profile, the description covers the essential aspects: what is closed, what is cleaned, and when to reopen. The sibling context is clear from the name itself. Nothing critical is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one required parameter 'id' with a pattern, but no description. The description indirectly clarifies its meaning by stating it "invalidate[s] the id," confirming that id refers to the session identifier. While it could explicitly say 'the id returned by ssh_open', the context and pattern make the parameter's purpose clear enough.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's core function: "Close the remote shell and SSH connection." It also adds specific cleanup actions (clean private temporary directory, invalidate the id), which distinguishes it from the sibling tools like ssh_open and ssh_interrupt. The verb 'close' is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a usage pattern: "Close a dirty session and call ssh_open for a clean environment." This implies when the tool is appropriate (for dirty sessions) and suggests a follow-up action. However, it does not explicitly contrast with alternatives like ssh_interrupt or state when not to use it, missing the full 'when/when-not' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`reload`	No

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral detail: returns only safe connection metadata, never exposes private keys/IdentityFile paths/agent sockets/ProxyCommand, and re-parses config without restarting. This is consistent with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the main purpose, then adds safety guarantees, reload guidance, and a pointer to ssh_open. Every sentence earns its place; there is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since there is no output schema, the description adequately explains return values (alias, hostname, user, port, proxy_jump) and exclusions. It also covers parameter behavior. For a simple list tool, this is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, so the description must compensate. It fully explains the reload parameter: passing reload=true after editing ~/.ssh/config re-parses without restarting the MCP server. This adds clear meaning beyond the boolean type and default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists allowed OpenSSH Host aliases from local ssh_config and an explicit allowlist, with a specific resource and scope. However, with a sibling named ssh_list that could also be a listing tool, there is no explicit differentiation from that sibling, preventing a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context: use this to discover aliases for ssh_open, and pass reload=true after editing ~/.ssh/config. It does not explicitly state when not to use it or name alternatives among the sibling tools, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that the session is kept only when recovery is confirmed and that it waits for recovery, going beyond the destructiveHint annotation. Reveals return behavior for idle state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, direct, no redundant words, front-loads the primary action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the main behavior and idle return, but omits how the id parameter relates to the session and lacks error cases beyond idle. Given simple schema and no output schema, it's mostly sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and description never explains the required 'id' parameter. The agent cannot learn from the description what id identifies or how to obtain it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it sends Ctrl-C to the current foreground process group, distinguishing it from open/run/peek/list/close siblings. Specific verb 'send' and resource 'foreground process group'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes the recovery wait and the 'nothing_to_interrupt' when idle, which guides when it's applicable. Does not explicitly name alternatives but context implies interrupt vs other session operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/destructive hints, so the description adds value by specifying the exact fields returned and the 'live session' scope. The mention of 'idle-reap countdown' provides extra lifecycle context beyond what annotations convey, though it does not detail the output format or pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero filler. It front-loads the core action, then packs in specific return fields and a critical usage reminder. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no parameters and no output schema, the description fully covers behavior, return field details, and usage instructions. The agent knows exactly what to expect from the call and how to apply it, making the tool self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, and the schema is empty, so the baseline is 4 per the rubric. The description accurately reflects the parameterless nature and adds no unnecessary parameter details. Nothing is needed beyond the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all live SSH sessions with a specific set of fields (host, cwd, state, etc.). This distinguishes it from sibling tools that open, run, interrupt, peek, or close sessions. The verb 'list' unambiguously defines the action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly directs users to use this tool to recover valid session ids and warns against inventing ids, which is crucial for safely using other ssh commands. It lacks an explicit 'when not to use' or alternative comparison, but the context of the sibling tools makes the use case clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`host`	Yes
`name`	No

TDQS

A4.2/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds significant context beyond annotations: sessions are clean and get a new id, credentials only come from local OpenSSH config/agent, and passwords/private keys are never accepted as arguments nor read from disk. This safety-related transparency is valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three focused sentences; every sentence provides useful information without excess. Front-loaded with purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers key constraints (persistent shell, allowed hosts, credential handling, clean session), but does not describe the return value or lifecycle (how to use/close the session). Given no output schema, a mention of what the tool returns or how the session id is used would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Describes the 'host' parameter semantically as an allowed ssh_config Host alias from ssh_hosts, but does not explain the 'name' parameter. Schema coverage is 0%, so the description partially compensates but leaves a gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Open') on a specific resource ('a new persistent remote bash shell'), and distinguishes itself from siblings by specifying usage of an allowed ssh_config Host alias from ssh_hosts and clean sessions with new ids.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context that this is for persistent sessions using allowed hosts, but does not explicitly name alternatives like ssh_run or ssh_peek or state when to use them. The 'from ssh_hosts' constraint gives some usage guidance, but it lacks explicit when/when-not.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes
`lines`	No
`wait_sec`	No

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint, idempotentHint), the description adds key behavioral details: wait_sec long-polls but never stops the remote command, output is limited independently for stdout/stderr, lines are capped to protect model context, and idle returns cwd and last exit code. These traits are not in the annotations and significantly enhance transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and each sentence adds unique value: purpose, wait_sec semantics, output behavior, usage context, and idle behavior. There is no fluff or redundancy, and the length is justified given the parameter complexity and zero schema descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description thoroughly explains return values: newest lines in chronological order for stdout/stderr, and when idle, cwd, last exit code, and latest lines. It also covers all operational states (running vs idle) and parameter effects, making the tool fully comprehensible.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates fully. It explains wait_sec's long-polling behavior and that it never stops the command, lines defaults to 50 with a cap, and id is implicitly tied to ssh_run's returned handle. This gives meaning to all three parameters beyond their raw schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool observes the current foreground command and its latest output without starting another command. It distinguishes itself from siblings like ssh_run (start) and ssh_interrupt (interrupt) by focusing on passive observation. The verb 'observe' plus specific resource (SSH command output) makes the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use after ssh_run returns status=running', giving a clear when-to-use directive. It also advises preferring a positive wait_sec over busy-looping, which is a practical usage guideline. The idle-state description further clarifies expected behavior in different conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes
`command`	Yes
`wait_sec`	No
`timeout_sec`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint=false, destructiveHint=true), the description adds rich behavioral detail: wait_sec behavior with status=running, no automatic timeout, timeout_sec sending Ctrl-C, one foreground command per id, and persistence of cwd/environment changes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core operation and then provides precise behavioral and usage clauses. Every sentence adds value, and the length is justified by the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The lifecycle, timeout, concurrency, and restrictions are thoroughly covered. However, with no output schema, the description does not specify the return payload for completed commands—only mentioning status=running for still-active commands. This is a minor but non-negligible gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has zero property descriptions, but the description fully compensates: id identifies the persistent shell, command is non-interactive, wait_sec is the call wait limit with a default, and timeout_sec triggers Ctrl-C at the deadline. All four parameters are semantically grounded.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it starts a non-interactive command in the same persistent shell identified by id, with persistent cwd and environment changes. This distinguishes it from sibling tools like ssh_open (new session) and ssh_peek/ssh_interrupt.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given: poll with ssh_peek(wait_sec=...), call ssh_interrupt to stop, open another session for concurrency, and never retry a running command. It also explicitly forbids interactive TUI/input flows such as vim or top.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

1 tool updateAug 5, 2026
- Addedssh_hosts
6 tool updatesv0.2.0Jul 31, 2026
- First observedssh_close
- First observedssh_interrupt
- First observedssh_list
- First observedssh_open
- First observedssh_peek
- First observedssh_run

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0

Disambiguation5/5

Each tool targets a distinct action in the SSH session lifecycle: open creates, run executes, interrupt signals, peek observes, list enumerates, close destroys. There is no overlap or ambiguity between them.

Naming Consistency5/5

All tool names follow the same ssh_verb pattern using clear, imperative verbs (open, run, interrupt, peek, list, close). The naming is perfectly consistent.

Tool Count5/5

Six tools is an ideal scope for managing remote SSH sessions. Each tool is necessary and none are redundant, covering the full lifecycle without bloat.

Completeness5/5

The tool set covers the complete lifecycle of a persistent remote shell: open, run, monitor, interrupt, list, and close. Given the non-interactive design constraint, there are no evident gaps for the intended domain.

Maintenance

ActivityActive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

SentinelX MCPOAuth
app.sentinelx
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Shell Access OS Automation
26
mcp AOAuth
dev.aicommander
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Shell Access Command Line OS Automation
2
Railway MCPOAuth
com.railway
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Cloud Platforms Developer Tools CI/CD & DevOps
2
browser-ssh
com.browserssh
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Shell Access File Systems
2

Related MCP Servers

SSH MCP Server
Shell Access OS Automation Security
format37
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.
Updated a year ago (2025-06-21 12:56 UTC)
1
-
TerminusAI
Gorav22
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
Updated a year ago (2025-07-01 11:42 UTC)
1
2
MIT
SSH MCP Server
Shell Access Command Line OS Automation
fryjustinc
A
license
Not graded
quality
D
maintenance
Provides LLM clients with safe, persistent SSH access to remote machines through the Model Context Protocol. Maintains shell sessions that preserve environment state between commands, enabling multi-step workflows and interactive diagnostics on remote systems.
Updated a year ago (2025-10-01 11:41 UTC)
42
16
MIT
mcp-ssh
Shell Access Command Line
seraved
F
license
Not graded
quality
C
maintenance
Enables AI assistants to run commands on remote SSH-accessible devices via persistent sessions, supporting both POSIX and CLI shells with safety filters.
Updated 2 months ago (2026-07-11 13:44 UTC)
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/the-nine-nation/remote-ssh-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Why Remote SSH MCP?

Why pick this over one-shot ssh in bash?

Features

🧠 Persistent remote sessions

🔧 Native OpenSSH integration

📡 Long-running command friendly

🛡️ Safety & control plane

📦 Clean tool results for models

🔌 MCP-native

How it works

MCP tools

Tool parameters (essentials)

Quick start

Requirements

Install

MCP host configuration

Credential boundary

Configuration

Environment variables

Execution semantics

Development

Security

Project status

Changelog

0.2.2 — quieter remote output, fewer tokens

0.2.1

0.2.0

Star History

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Why pick this over one-shot `ssh` in bash?