mcp-ssh-terminal

An MCP server that gives an AI agent persistent, fully interactive SSH sessions — a real shell into a remote host that behaves as if you were typing at a local terminal.

• Sessions persist across tool calls — connect once, run commands, inspect output, run more; state (working directory, environment, running programs) is preserved.

• A real terminal, not a command runner — arbitrary control characters (Ctrl-C, Ctrl-X, arrows, Tab, function keys) pass through faithfully, so interactive TUIs, pagers, tab-completion, and prompts all work.

• Non-Unix CLIs work too — network appliances like Mikrotik RouterOS are first-class citizens because the session is a genuine PTY.

• Your existing SSH setup just works — ~/.ssh/config aliases, IdentityFile, ssh-agent, ProxyJump chains, and known_hosts are all handled by the real OpenSSH client, untouched.

ssh_connect { "host": "prod-web" }                                → s1 + login screen
ssh_send    { "session": "s1", "text": "htop", "appendEnter": true }
ssh_send    { "session": "s1", "keys": ["F5"] }                   → tree view, rendered
ssh_interrupt { "session": "s1" }                                 → Ctrl-C, back to prompt

Table of contents

• How it works

• Requirements

• Install

• Register with an MCP client

• Docker

• Tools

• Special keys

• Usage walkthroughs

• Security notes

• Troubleshooting

• Development

Related MCP server: Shuttle

How it works

Decision 1: drive the real OpenSSH client (ssh) inside a PTY

Rather than reimplementing SSH in JavaScript, each session spawns your actual ssh binary attached to a pseudo-terminal. Every connection requirement you'd otherwise have to hand-build is something OpenSSH already does correctly:

A pure-JS library (e.g. ssh2) would force us to re-implement ssh_config resolution, Match logic, ProxyJump chaining, known_hosts hashing/verification, and key handling — a large, security-sensitive surface that OpenSSH already gets right. Delegating to ssh means the server behaves exactly like your own ssh <host> command.

Decision 2: a headless terminal emulator for reading output

Raw PTY output is a byte stream full of cursor moves, colors, and redraws. Feeding that to an agent is unreadable. So output is piped through @xterm/headless, which maintains a virtual screen. Tools return the rendered screen a human would see — redraws collapsed to their final state, escape codes resolved to plain text. (A raw mode is still available on ssh_read when you need the underlying bytes.) The emulator also answers terminal queries from the remote side (cursor-position reports, device attributes), so programs that probe the terminal don't hang.

How "is the output done?" is decided

After input is sent, the server waits until output has been quiet for settleMs (default 500 ms) or a timeoutMs cap is hit, then renders. A long-running command returns partial output at the timeout with a hint to call ssh_read again — no output is lost, and short commands feel snappy.

Terminal multiplexing

Two levels:

• Multiple concurrent sessions — connect to many hosts at once; each has its own session id (up to 32 concurrent).

• tmux/screen inside a session — since each session is a real terminal, you can run tmux on the remote host and drive it with control keys (ssh_send { keys: ["C-b", "c"] }, etc.).

Requirements

• Node.js ≥ 22 (fs.glob, used by the config lister, does not exist on Node 20)

• The OpenSSH client (ssh) on PATH — the same one your shell uses.

• macOS/Linux. (node-pty ships prebuilt binaries; on macOS the bundled spawn-helper must be executable — see Troubleshooting.)

Install

From npm — nothing to do up front; register it straight with npx (next section). Or install globally:

npm install -g mcp-ssh-terminal

From source:

git clone https://github.com/zhdkirill/mcp-ssh-terminal.git
cd mcp-ssh-terminal
npm install
npm run build      # compiles TypeScript to dist/
npm test           # optional: runs the tests (keys, argv builder, ssh_config, live PTY sessions)

Register with an MCP client

Claude Code (CLI):

claude mcp add ssh -- npx -y mcp-ssh-terminal
# or, from a source checkout:
claude mcp add ssh -- node /path/to/mcp-ssh-terminal/dist/index.js

Project-scoped .mcp.json or Claude Desktop config:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-terminal"]
    }
  }
}

(For a source checkout, use "command": "node", "args": ["/path/to/mcp-ssh-terminal/dist/index.js"] instead.)

The server speaks MCP over stdio. It writes nothing to stdout except protocol traffic (logs go to stderr), so it is safe to run under any stdio MCP host.

Docker (optional)

Run it natively if you can. The whole design delegates auth to your OpenSSH — config, keys, agent, known_hosts — and a container sees none of that unless you mount it in. Docker is the right choice when the consuming machine shouldn't need Node, or you want a pinned, hermetic runtime; it is the wrong choice if you rely on ssh-agent, FIDO keys, or VPN-only routes that exist on the host.

docker build -t mcp-ssh-terminal .

Register (mounting your ssh config/keys read-only):

claude mcp add ssh -- docker run -i --rm --init -v "$HOME/.ssh:/home/node/.ssh:ro" mcp-ssh-terminal

Notes for container mode:

• -i is mandatory (stdio transport) and --init is recommended (proper PID-1 signal handling; the server also handles SIGTERM itself).

• ssh-agent: Linux: add -v "$SSH_AUTH_SOCK:/agent.sock" -e SSH_AUTH_SOCK=/agent.sock. Docker Desktop for Mac: -v /run/host-services/ssh-auth.sock:/agent.sock -e SSH_AUTH_SOCK=/agent.sock. Without an agent, mounted key files still work (you'll type passphrases interactively via ssh_send).

• known_hosts: with a read-only mount, newly-accepted host keys can't be persisted — ssh warns and continues for that session. Mount ~/.ssh read-write (or a dedicated known_hosts file) if you want them remembered.

• File ownership: the image runs as the node user (uid 1000). If your bind-mounted keys come through owned by a different uid and unreadable, add --user root (the container is ephemeral and has your keys mounted either way).

• Networking: the container has its own network namespace. Host-only routes (VPN tunnels, localhost targets) may need --network host (Linux only) or won't work as they do natively.

Tools

ssh_connect parameters

Every screen-returning tool accepts settleMs, timeoutMs, and maxLines, and appends a status footer:

[session=s1 | state=live | wait=idle | cursor=12,1 | screen=40x120 | shown=24/40]

state becomes exited code=N when the ssh process ends; wait tells you whether output settled (idle), was still streaming (timeout), or nothing new arrived (quiet).

Special keys for ssh_send

Pass an ordered keys array. Recognised tokens (case-insensitive):

• Control chords: C-c (Ctrl-C), C-x, Ctrl-d, ^u, C-[ (Esc), C-@ (NUL), C-\, C-? (DEL) — covers all of 0x00–0x1F and 0x7F.

• Named keys: Enter, Tab, Backtab, Space, Escape, Backspace, Delete, Insert, Up/Down/Left/Right, Home, End, PageUp, PageDown, F1–F12.

• Alt/Meta: M-b, Alt-f, meta-. → ESC-prefixed.

• Raw bytes: hex:1b5b41 → arbitrary byte sequence.

• Single characters: y, Q → sent as-is.

Any other multi-character token is an error — a typo'd chord is rejected instead of being typed into the remote shell. Literal text belongs in text, not keys. Arrow/Home/End keys automatically switch to SS3 sequences when the remote app enables application cursor-keys mode (DECCKM), like a real terminal.

text is sent literally first, then keys in order, then Enter if appendEnter: true.

Usage walkthroughs

Basic:

1. ssh_connect { "host": "prod-web" } → screen shows the shell prompt.

2. ssh_send { "session": "s1", "text": "uname -a", "appendEnter": true } → screen shows the output.

3. ssh_disconnect { "session": "s1" }.

Mikrotik RouterOS:

1. ssh_connect { "host": "admin@192.0.2.1" } → RouterOS banner + [admin@MikroTik] > prompt.

2. ssh_send { "session": "s1", "text": "/interface print", "appendEnter": true }.

3. Tab-completion: ssh_send { "session": "s1", "text": "/ip ad", "keys": ["Tab"] }.

4. Abort a running command: ssh_interrupt { "session": "s1" } (Ctrl-C), or send Q to quit a pager.

RouterOS console gotchas worth knowing:

• ? and Tab are live hotkeys (inline help / completion) — they act the instant they arrive, so keep them out of text unless intended, and prefer single-line commands (multi-line pastes are mangled by auto-indent; use /import for scripts).

• Long print output stops at a pager line (-- [Q quit|D dump|down]): send D to dump the rest, or run print without-paging.

• keys: ["C-x"] toggles Safe Mode — enter it before config changes so they auto-revert if the session drops.

ProxyJump A → B → C: use a config alias that sets ProxyJump, and just ssh_connect { "host": "internal-box" }. Or set the chain inline: ssh_connect { "host": "10.0.0.5", "jump": "bastionA,bastionB" }.

Answering auth / host-key prompts: if the initial screen shows Are you sure you want to continue connecting (yes/no)?, reply ssh_send { "session": "s1", "text": "yes", "appendEnter": true }. For a password prompt, send the password the same way. The known_hosts check is never disabled.

Long-running output: ssh_send returns at the settle/timeout; if the footer says output is still arriving, call ssh_read { "session": "s1", "waitMs": 2000 } to poll for more. ssh_read blocks until new output arrives (footer wait=idle/timeout) or reports wait=quiet if nothing new came within waitMs.

Security notes

This server hands an AI agent a real shell with your SSH identity. Read this section before wiring it into anything.

• The agent can do whatever your keys can do. Every host reachable from your ~/.ssh/config and agent is reachable by the model. Use your MCP client's permission prompts (don't blanket-allow ssh_send), and consider a dedicated restricted key or user for agent-driven work.

• Remote output is untrusted input to the model. Screen content from a remote host flows back into the agent's context; a compromised or malicious host could try prompt injection through banners, MOTDs, or command output. Treat sessions to untrusted hosts accordingly.

• known_hosts verification is left on. The server does not add StrictHostKeyChecking=no or similar; you decide, per host, by answering the fingerprint prompt.

• Argument injection is blocked for host/user/jump: values starting with - are rejected and the destination is passed after a -- separator, so a hostile hostname can't smuggle in ssh options like ProxyCommand. extraArgs remains a deliberate raw passthrough — treat it as you would a shell: options like -oProxyCommand=… execute local commands as the user running the server. If your MCP client supports per-tool argument review, scrutinize extraArgs.

• ssh_config_hosts reads the file you point it at. configPath accepts any path readable by the server's user (it only echoes config-shaped lines, but still). Point it at ssh configs only.

• Credentials are never handled by this server; ssh/ssh-agent own them. Passwords you type via ssh_send go straight to the PTY (not logged to stdout) — but they do transit the MCP transport and may end up in client-side conversation logs. Prefer key-based auth over typing passwords.

• Run it as your normal user so it inherits your ~/.ssh and agent.

Troubleshooting

• posix_spawnp failed from node-pty on macOS: the prebuilt spawn-helper lost its execute bit. Fix: chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helper. npm run build is unaffected, but a fresh npm install may need this once.

• ssh: connect to host … Connection refused: faithfully reported from the real ssh; the destination isn't listening. Session exits with code 255.

• Connection timed out during banner exchange on a ProxyJump chain: OpenSSH's ConnectTimeout (default here: 30) also caps the destination's banner exchange, and that clock keeps running while you answer interactive prompts (host key, password) at the jump hop. Answer promptly, or raise it: extraArgs: ["-o", "ConnectTimeout=120"]. Note that -o options are not propagated to the jump hop itself — its host key is checked against your default known_hosts.

• channel 0: open failed: administratively prohibited via a jump host: the jump's sshd has AllowTcpForwarding no (common on hardened/minimal distros, e.g. Alpine's default). Enable it on the jump host; ProxyJump needs TCP forwarding there.

• Output looks truncated: increase maxLines on ssh_send/ssh_read, or poll with ssh_read. The emulator keeps 5000 lines of scrollback per session.

• Session limit reached: at most 32 concurrent sessions; exited ones are evicted automatically, live ones must be ssh_disconnected first.

Development

npm run build   # tsc → dist/
npm test        # vitest: unit tests + live PTY integration tests

src/
  index.ts       entry point; stdio transport + graceful shutdown
  server.ts      MCP server + tool definitions
  manager.ts     session registry + ssh argv builder
  session.ts     PTY + headless xterm; idle-wait + screen rendering
  keys.ts        key-token → byte-sequence translation
  sshConfig.ts   best-effort ~/.ssh/config host lister (discovery only)
test/            vitest tests (keys, argv builder, ssh_config, live PTY sessions)
Dockerfile       optional container packaging (see the Docker section)

Contributions welcome — please run npm test before opening a PR.

License

MIT