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:<version>

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: