ssh-session-mcp

One SSH terminal. Two operators. Less chaos.

`ssh-session-mcp` gives MCP clients a persistent SSH runtime instead of a stateless shell wrapper. The user keeps the browser terminal open, the AI works through MCP tools, and both sides see the same session state.

Best For

Remote Linux boards, SSH dev hosts, collaborative AI-assisted terminal work.

Core Promise

Shared PTY, browser viewer, input lock, async tracking, diagnostics.

Fastest Demo

`ssh-session-mcp-ctl launch --local --viewerPort=auto`

Why it matters

Many MCP SSH integrations can execute commands, but they still lose the terminal as a shared runtime. This project keeps that runtime alive and inspectable.

shared PTY browser terminal input lock

What it adds

State-aware command handling, safe/full modes, async polling, viewer diagnostics, session history, and local debug mode for demos without SSH.

safe/full mode async status local debug

Who it helps

Operators who want the AI to help with a real remote terminal, but still need visibility, manual intervention, and guardrails when the shell gets weird.

embedded ops AI coding

Install paths

Use the operator helper when a human wants the easiest local experience. Use the server binary directly when an MCP client needs a stdio command.

Fast local demo

npm install -g ssh-session-mcp
ssh-session-mcp-ctl launch --local --viewerPort=auto

MCP stdio command

ssh-session-mcp --viewerPort=auto

Use `.env` for a single target. Use `ssh-session-mcp.config.json` for multi-device setups. Keep secrets in environment variables, not in tracked JSON.

Core tool flow

For agents, the normal loop should stay short and explicit: `ssh-device-list`, `ssh-quick-connect`, `ssh-run`, `ssh-status`, `ssh-command-status`, and `ssh-retry`. Drop to lower-level tools only when you need raw terminal control.

`ssh-quick-connect`Open or reuse the common session and optionally launch the viewer.

`ssh-run`Execute a command with completion detection and exit-code capture.

`ssh-status`Inspect runtime state, viewer state, and active sessions.

`ssh-command-status`Poll async commands instead of guessing when long work is done.

`ssh-session-diagnostics`Inspect lock state, running command state, terminal warnings, and viewer health.