SSH Session MCP

ssh-session-mcp

中文 | English

Persistent shared-terminal runtime for MCP clients over SSH.

ssh-session-mcp gives the user and the AI the same SSH PTY session, adds a browser viewer, tracks who typed what, and makes long-running remote work manageable instead of stateless.

Contents

• Install At A Glance
• Project Structure
• Quick Start
• Docker Status
• MCP Tools
• Configuration Summary
• Security
• Docs
• Development

Install At A Glance

• Normal users do not need to git clone this repository.
• Preferred install path for MCP clients: npx -y ssh-session-mcp --viewerPort=auto
• Preferred install path for human operators who want local binaries: npm install -g ssh-session-mcp
• Official container distribution can be published to a public registry such as docker.io/zwawa/ssh-session-mcp
• git clone is only for contributors, source builds, and local development.
• For the common desktop MCP workflow, npx or a global npm install is still the lowest-friction path. Docker is mainly useful when you want a pinned runtime, container-based deployment, or registry-backed distribution.

Why It Exists

Most SSH-oriented MCP servers can execute commands, but they do not manage terminal state well enough for real collaboration.

ssh-session-mcp focuses on the missing runtime layer:

• One shared PTY for both the human and the AI
• Browser terminal for live inspection and manual intervention
• Input lock so the AI does not type over the user
• Safe/full execution modes for risky commands
• Configurable default policy rules plus session-level custom rule overrides
• Async command tracking for long-running remote work
• Multi-device and multi-connection profile support
• Local debug mode for demos, offline testing, and prompt iteration

Best Fit

• AI-assisted remote development on Linux boards and SSH servers
• Embedded, ROS, training, and deployment hosts that need a real terminal
• Users who want the AI to help, but do not want to surrender the terminal
• MCP Marketplace listings where the install and demo path must be clear

Project Structure

Key directories and files:

Quick Start

1. Agent-First Install (Auto-download on first run)

If the goal is to let Claude Code, Codex, or OpenCode install the server automatically, prefer npx -y ssh-session-mcp in the MCP command instead of a prior global install.

For Cline Marketplace and other agent installers, see llms-install.md. This repo is structured to be one-click installable through an npx -y ssh-session-mcp --viewerPort=auto command.

Claude Code

claude mcp add --transport stdio ssh-session-mcp -- npx -y ssh-session-mcp --viewerPort=auto

Windows note from the Claude Code docs: native Windows users should wrap npx with cmd /c for stdio MCP servers.

claude mcp add --transport stdio ssh-session-mcp -- cmd /c npx -y ssh-session-mcp --viewerPort=auto

Codex

codex mcp add ssh-session-mcp -- npx -y ssh-session-mcp --viewerPort=auto

OpenCode

OpenCode's opencode mcp add flow is interactive. Choose a local MCP server and use this command:

npx -y ssh-session-mcp --viewerPort=auto

If you prefer config instead of the interactive flow:

{

"$schema": "https://opencode.ai/config.json", "mcp": { "ssh-session-mcp": { "type": "local", "command": ["npx", "-y", "ssh-session-mcp", "--viewerPort=auto"] } } }

This is the closest thing to "automatic installation" for stdio MCP servers today: the MCP client stores the command, and npx -y downloads the package automatically the first time it runs.

2. Fastest Local Demo

npm install -g ssh-session-mcp

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

This starts a local shell instead of SSH and opens the browser terminal, which is the easiest way to test the MCP runtime before touching a real server.

3. Register As An MCP Server

Use the MCP server binary directly when wiring a client:

# Global install

npm install -g ssh-session-mcp

Server command used by MCP clients

ssh-session-mcp --viewerPort=auto

# Claude Code

claude mcp add --transport stdio ssh-session-mcp -- ssh-session-mcp --viewerPort=auto

Codex CLI

codex mcp add ssh-session-mcp -- ssh-session-mcp --viewerPort=auto

If you prefer npx instead of a global install:

npx -y ssh-session-mcp --viewerPort=auto

4. Connect To A Real SSH Target

Create .env from .env.example:

cp .env.example .env

SSH_HOST=YOUR_DEVICE_HOST

SSH_PORT=22 SSH_USER=YOUR_DEVICE_USER SSH_PASSWORD= SSH_KEY= VIEWER_PORT=auto AUTO_OPEN_TERMINAL=false SSH_MCP_MODE=safe

Then launch:

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

5. Multi-Device Config

For multiple boards or named targets, create ssh-session-mcp.config.json:

{

"defaultDevice": "DEVICE_A_ID", "devices": [ { "id": "DEVICE_A_ID", "host": "DEVICE_A_HOST", "port": 22, "user": "DEVICE_A_USER", "auth": { "passwordEnv": "DEVICE_A_PASSWORD" }, "defaults": { "term": "xterm-256color", "cols": 120, "rows": 40, "autoOpenViewer": true, "viewerMode": "browser" } } ] }

Discovery order:

1. --config=/path/to/config.json
2. Workspace ssh-session-mcp.config.json
3. User-global config
4. Legacy .env fallback

Important:

• Config discovery is based on the MCP process working directory.
• auth.password is intentionally unsupported. Use auth.passwordEnv or auth.keyPath.
• Secrets belong in .env or the parent environment, not in repo-tracked JSON.

6. Docker Status

Public Docker images should be distributed through Docker Hub, with GitHub Container Registry as an optional secondary registry:

docker.io/zwawa/ssh-session-mcp:<version>

docker.io/zwawa/ssh-session-mcp:latest ghcr.io/zw-awa/ssh-session-mcp:

Recommended container launch for a real SSH target:

docker run --rm -i \

-p 8793:8793 \ -e VIEWER_PORT=8793 \ -e VIEWER_HOST=0.0.0.0 \ -e SSH_HOST=YOUR_DEVICE_HOST \ -e SSH_PORT=22 \ -e SSH_USER=YOUR_DEVICE_USER \ -e SSH_PASSWORD \ docker.io/zwawa/ssh-session-mcp:latest

Export the password in your shell first instead of placing it directly on the command line.

Recommended launch for profile-based config:

docker run --rm -i \

-p 8793:8793 \ -e VIEWER_PORT=8793 \ -e VIEWER_HOST=0.0.0.0 \ -e SSH_MCP_CONFIG=/workspace/ssh-session-mcp.config.json \ -v "$PWD/ssh-session-mcp.config.json:/workspace/ssh-session-mcp.config.json:ro" \ -v "/path/to/host/keys:/workspace/keys:ro" \ docker.io/zwawa/ssh-session-mcp:latest

Equivalent Compose example:

docker compose up -d

See docker-compose.yml for a ready-to-run example that mounts ssh-session-mcp.config.json, publishes the viewer on 8793, and uses SSH_KEY_DIR when set or falls back to a dedicated ./keys directory. For the full Docker guide, including the legacy .env compose variant and MCP client config snippets, see docs/docker.md. For a container-oriented profile example, see docs/examples/ssh-session-mcp.config.docker.example.json.

Container-specific notes:

• The image defaults VIEWER_PORT to 8793 when unset so the browser viewer can be published reliably.
• The image defaults VIEWER_HOST to 0.0.0.0 inside the container so the mapped port is reachable from the host.
• AUTO_OPEN_TERMINAL defaults to false in the container because browser auto-open from inside a container is usually not useful.
• Mount config files or SSH keys read-only when possible.
• Prefer mounting SSH keys from a directory outside the repo root.
• In docker-compose.yml, SSH_KEY_DIR overrides the default key mount path. If it is unset, Compose falls back to ./keys, not the repo root.
• Avoid putting passwords directly on the command line. Prefer exported env vars, Compose .env, or --env-file.
• For stdio MCP clients, Docker is viable, but host-native npx is still simpler unless your client explicitly prefers containerized commands.

Docker-based MCP client command examples:

# Claude Code

claude mcp add --transport stdio ssh-session-mcp -- docker run --rm -i -p 8793:8793 -e VIEWER_PORT=8793 -e VIEWER_HOST=0.0.0.0 docker.io/zwawa/ssh-session-mcp:latest

Codex CLI

codex mcp add ssh-session-mcp -- docker run --rm -i -p 8793:8793 -e VIEWER_PORT=8793 -e VIEWER_HOST=0.0.0.0 docker.io/zwawa/ssh-session-mcp:latest

For JSON-based MCP clients, the same pattern works by using docker as the command and passing the remaining run ... docker.io/zwawa/ssh-session-mcp:latest tokens as args.

This is useful when:

• The primary workflow is a local stdio MCP server command, not a long-lived network service.
• You want a pinned Node/runtime environment without a local install.
• You need registry-based distribution for a team or managed host.
• You want container-level isolation for the MCP server process.

For many users, publishing to npm and recommending npx -y ssh-session-mcp --viewerPort=auto is still the lower-friction install path.

Viewer And Collaboration Model

The browser viewer is not decorative. It is part of the workflow:

• The user can see exactly what the AI did.
• The AI can pause when the user takes over.
• Password prompts, pagers, and editors become visible state instead of hidden failure modes.
• Session diagnostics and history turn terminal debugging into something inspectable.

Marketplace-Friendly Flow

For users:

install -> launch viewer -> connect once -> keep the session alive -> let the AI help

For agents:

ssh-qu