SSH Session MCP

ssh-session-mcp

中文 | English

SSH 経由で MCP クライアントに永続的な共有ターミナル環境を提供します。

ssh-session-mcp はユーザーと AI が同じ SSH PTY セッションを共有できるようにし、ブラウザーのビューアーを追加して、誰が何を入力したかを追跡します。また、リモートでの長時間作業をステートレスではなく、管理しやすくします。

目次

• 概要を見ながらインストール
• プロジェクト構成
• クイックスタート
• Docker のステータス
• MCP ツール
• 設定の概要
• セキュリティ
• ドキュメント
• 開発

概要を見ながらインストール

• 通常のユーザーは、このリポジトリを git clone する必要はありません。
• MCP クライアントに推奨されるインストール方法：npx -y ssh-session-mcp --viewerPort=auto
• ローカルバイナリを使いたいオペレーターに推奨されるインストール方法：npm install -g ssh-session-mcp
• 公式コンテナーは、docker.io/zwawa/ssh-session-mcp などのパブリックレジストリに公開できます。
• git clone は、コントリビューター、ソースからのビルド、ローカル開発にのみ使用します。
• 一般的なデスクトップ MCP ワークフローでは、npx または npm のグローバルインストールが、依然として最も手軽な方法です。Docker は、バージョンを固定したランタイム、コンテナーを使ったデプロイ、またはレジストリを利用した配布が必要な場合に主に役立ちます。

存在する理由

SSH を中心とするほとんどの MCP サーバーはコマンドを実行できますが、実際の共同作業に十分なターミナル状態の管理機能を備えていません。

ssh-session-mcp は、欠けているランタイム層に重点を置いています。

• 人間と AI が共有する 1 つの PTY
• 状態をリアルタイムで確認し、手動で介入できるブラウザーターミナル
• AI がユーザーの入力に割り込まないようにする入力ロック
• リスクのあるコマンドに対応するセーフモード／フルモード
• 設定可能なデフォルトポリシールールと、セッション単位でのカスタムルールの上書き
• リモートでの長時間作業に対応する非同期コマンド追跡
• 複数デバイスおよび複数接続プロファイルのサポート
• デモ、オフラインテスト、プロンプトの調整に使えるローカルデバッグモード

最適な用途

• Linux ボードや SSH サーバーでの AI 支援リモート開発
• 実際のターミナルが必要な組み込み、ROS、トレーニング、デプロイ用ホスト
• AI に支援してほしい一方、ターミナルを完全に明け渡したくないユーザー
• インストール方法とデモへの導線を明確にする必要がある MCP Marketplace の掲載情報

プロジェクト構成

主なディレクトリとファイル：

パス	用途
src/	MCP サーバー、SSH セッションランタイム、ビューアー、ツール、設定 CLI のコアとなる TypeScript 実装
src/viewer-html/	ターミナルビューアー向けの HTML ページ生成機能とブラウザー側スクリプト
test/	ランタイムの動作、ビューアーのコントラクト、設定の読み込み、リポジトリの検証に関する Vitest テスト
docs/	コントラクト、障害分類、プラットフォームに関する注記、Docker の使用方法などの補足ドキュメント
docs/examples/	通常のセットアップおよび Docker 向けセットアップの設定例ファイル
scripts/	ビルド、バージョン同期、ローカル運用支援用スクリプト
deploy/helm/	シングルノードまたは分散型 v0 モードで Kubernetes にデプロイするための Helm チャート
site/	GitHub Pages ランディングページのソース
dist/	npm run build:site で生成される静的サイトの出力
build/	npm run build で生成される JavaScript の出力
Dockerfile	コンテナーイメージのビルド定義
docker-compose.yml	プロファイルベースの Docker Compose の例
docker-compose.env.yml	レガシーな .env 形式の Docker Compose の例
server.json	マーケットプレイス形式で配布するための MCP サーバーのメタデータ
AGENT.md	エージェント／運用者向けの主要な手引き
llms-install.md	エージェント向けのインストールおよび環境チェックリスト
.env.example	レガシーな単一ターゲット向け環境変数テンプレート

クイックスタート

1. エージェント優先のインストール（初回実行時に自動ダウンロード）

Claude Code、Codex、OpenCode にサーバーを自動でインストールさせる場合は、事前にグローバルインストールを行う代わりに、MCP コマンドで npx -y ssh-session-mcp を使ってください。

Cline Marketplace やその他のエージェントインストーラーについては、llms-install.md を参照してください。このリポジトリは、npx -y ssh-session-mcp --viewerPort=auto コマンドでワンクリックインストールできるように構成されています。

Claude Code

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

Claude Code のドキュメントに記載されている Windows に関する注意：ネイティブの Windows ユーザーは、stdio MCP サーバーで npx を使う際に cmd /c でラップする必要があります。

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 の opencode mcp add の手順は対話式です。ローカル MCP サーバーを選択し、次のコマンドを使用してください。

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

対話式の手順ではなく設定を使う場合：

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

これは、現在の stdio MCP サーバーにおける「自動インストール」に最も近い方法です。MCP クライアントがコマンドを保存し、初回実行時に npx -y がパッケージを自動でダウンロードします。

2. 最速のローカルデモ

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

SSH ではなくローカルシェルを起動してブラウザーターミナルを開くため、実際のサーバーに接続する前に MCP ランタイムを試す最も簡単な方法です。

3. MCP サーバーとして登録する

クライアントを接続する際は、MCP サーバーのバイナリを直接使用してください。

# 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

グローバルインストールではなく npx を使う場合：

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

4. 実際の SSH ターゲットに接続する

.env.example から .env を作成します。

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

次に起動します。

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

5. 複数デバイスの設定

複数のボードまたは名前付きターゲットを使う場合は、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"
      }
    }
  ]
}

検出順序：

1. --config=/path/to/config.json
2. ワークスペースの ssh-session-mcp.config.json
3. ユーザーのグローバル設定
4. レガシーな .env へのフォールバック

重要事項：

• 設定の検出は、MCP プロセスの作業ディレクトリを基準に行われます。
• auth.password は意図的にサポートされていません。auth.passwordEnv または auth.keyPath を使用してください。
• シークレットは .env または親環境変数に保存し、リポジトリで追跡される JSON には含めないでください。

6. Docker の状況

公開 Docker イメージは Docker Hub を通じて配布し、GitHub Container Registry は任意のセカンダリレジストリとして利用してください。

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

実際の SSH ターゲットに推奨されるコンテナの起動方法：

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

パスワードをコマンドラインに直接記述するのではなく、まずシェルでエクスポートしてください。

プロファイルベースの設定に推奨される起動方法：

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

同等の Compose の例：

docker compose up -d

すぐに実行できる例については、docker-compose.yml を参照してください。この例では ssh-session-mcp.config.json をマウントし、ビューアを 8793 で公開します。また、SSH_KEY_DIR が設定されていればその値を使用し、未設定の場合は専用の ./keys ディレクトリにフォールバックします。 従来の .env を使った Compose 形式や MCP クライアント設定のスニペットを含む、Docker の詳細なガイドについては、docs/docker.md を参照してください。 コンテナ向けのプロファイル例については、docs/examples/ssh-session-mcp.config.docker.example.json を参照してください。

コンテナ固有の注意事項：

• ブラウザーのビューアを確実に公開できるよう、イメージでは未設定時の VIEWER_PORT の既定値を 8793 にしています。
• マッピングしたポートにホストからアクセスできるよう、コンテナ内ではイメージの VIEWER_HOST の既定値を 0.0.0.0 にしています。
• コンテナ内からブラウザーを自動で開いても通常は役に立たないため、コンテナでは AUTO_OPEN_TERMINAL の既定値は false です。
• 可能であれば、設定ファイルや SSH キーは読み取り専用でマウントしてください。
• SSH キーはリポジトリのルートディレクトリ外にあるディレクトリからマウントすることを推奨します。
• docker-compose.yml では、SSH_KEY_DIR によって既定のキーのマウント先を上書きできます。未設定の場合、Compose はリポジトリのルートではなく ./keys にフォールバックします。
• パスワードをコマンドラインに直接記述しないでください。エクスポートした環境変数、Compose の .env、または --env-file を使用してください。
• stdio MCP クライアントでは Docker も利用できますが、クライアントがコンテナ化されたコマンドを明示的に優先しない限り、ホストにインストールした npx のほうが簡単です。

Docker ベースの MCP クライアントコマンドの例：

# 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

JSON ベースの MCP クライアントでは、同じパターンを使用できます。コマンドに docker を指定し、残りの run ... docker.io/zwawa/ssh-session-mcp:latest トークンを引数として渡してください。

次のような場合に役立ちます：

• 主なワークフローが、長時間稼働するネットワークサービスではなく、ローカルの stdio MCP サーバーコマンドである。
• ローカルにインストールせず、バージョンを固定した Node／ランタイム環境を使用したい。
• チームや管理対象ホスト向けに、レジストリベースで配布する必要がある。
• MCP サーバープロセスをコンテナレベルで分離したい。

多くのユーザーにとって、npm で公開し、npx -y ssh-session-mcp --viewerPort=auto を推奨する方法が、今でも最も手軽なインストール手段です。

ビューアとコラボレーションのモデル

ブラウザーのビューアは単なる飾りではありません。ワークフローの一部です：

• ユーザーは AI が行った操作を正確に確認できます。
• ユーザーが操作を引き継ぐと、AI は一時停止できます。
• パスワードの入力要求、ページャー、エディターを、隠れた障害要因ではなく、目に見える状態として確認できます。
• セッションの診断情報と履歴により、ターミナルのデバッグ状況を確認できるようになります。

マーケットプレイス向けのフロー

ユーザー向け：

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

エージェント向け：

ssh-quick-connect -> ssh-run -> inspect output -> ssh-command-status if needed -> ssh-run again

AI にインストール、設定の確認、デバイスへの接続を行わせ、エンドツーエンドでユーザーを支援させる場合は、AGENT.md を使用してください。古いエージェント設定との互換性に関する注意事項は、引き続き AI_AGENT_GUIDE.md に記載されています。

ステートレスな MCP SSH ラッパーとの主な違い

• 単発のコマンド実行ではなく、共有 PTY
• ユーザー、システム、エージェントの入力を示す、実行主体を識別できるトランスクリプトマーカー
• 危険または不適切な書き込みを行う前のターミナル状態チェック
• セッションとビューアプロセスの自動クリーンアップ
• 診断情報と履歴を備えた、セッション単位のブラウザービューア
• オフラインテスト用の --local によるローカルデバッグモード

操作モード

モード	動作
safe	セッションごとのデフォルトです。明らかに危険なコマンド、対話型コマンド、または終了しないコマンドを自動的にブロックします。
full	セッションごとのモードです。高度な用途向けにガードレールを緩和しつつ、明らかに破壊的な悪用の一部は引き続きブロックします。

各セッションは、それぞれ独自の safe ／ full モードを持つようになりました。あるブラウザーターミナルを full に切り替えても、ほかのセッションには影響しません。

必要に応じて、デフォルトのルールセットをカスタマイズできます。カスタムルールでは、次の設定をサポートするようになりました。

• error：コマンドをブロックします
• warning：許可しますが、警告を表示します
• log：許可し、注釈のみを付けます

ルールの優先順位は error > warning > log で、同じレベルでは先に定義されたルールが優先されます。

ロックポリシー

ブラウザーターミナルの UI では、オペレーターが次の入力ポリシーから選択できます。

ポリシー	オペレーターの操作感
common	ユーザーとエージェントの両方が共有ターミナルに入力できます。
user	ユーザーのみが入力できます。エージェントによる書き込み操作はブロックされます。
auto	エージェントと入力が競合することなく、ユーザーが入力を開始できます。ユーザーが入力を編集中は、エージェントによる書き込みがブロックされます。
agent	エージェントのみが入力できます。ポリシーが変更されるまで、ユーザー入力はブロックされます。

エージェント入力にターミナルを使用できない場合、ssh-run、ssh-session-send、ssh-session-control などのツールは、PTY に入力を無理に送信する代わりに、ブロックされたことを示す応答を返します。

MCP ツール

日常的な利用におすすめのツール

ツール	用途
ssh-quick-connect	デフォルトの接続先に接続または再利用し、必要に応じてビューアーを開きます
ssh-run	完了を検出し、終了コードを取得しながらコマンドを実行します
ssh-status	セッション、ビューアーの状態、操作モードを確認します
ssh-command-status	非同期コマンドの進行状況をポーリングします
ssh-retry	不安定なコマンドをバックオフ付きで再試行します
ssh-session-policy-list	継承されたデフォルト設定と、現在のセッションのカスタムポリシールールを確認します
ssh-session-policy-upsert	セッションレベルのカスタムポリシールールを追加または更新します
ssh-session-policy-remove	セッションレベルのカスタムポリシールールを削除します
ssh-session-policy-reset	セッションのカスタムルールを継承されたデフォルト設定にリセットします

ツールの全一覧

ツール	用途
ssh-session-open	明示的な SSH パラメーターを指定してセッションを開きます
ssh-session-send	PTY に生の入力を送信します
ssh-device-list	設定済みのデバイスとデフォルト設定を一覧表示します
ssh-session-read	オフセットを指定して、バッファーされたターミナル出力を読み取ります
ssh-session-watch	出力とダッシュボードの変更をロングポーリングします
ssh-session-history	ターミナル履歴を行番号付きで混在形式で読み取ります
ssh-session-control	ctrl_c、矢印キー、tab などの制御キーを送信します
ssh-session-resize	PTY のサイズを変更します
ssh-session-list	追跡中のセッションを一覧表示します
ssh-session-diagnostics	ロック状態、警告、実行中のコマンドの状態、ビューアーの健全性を確認します
ssh-session-policy-list	継承されたポリシーのデフォルト設定と、現在のセッションのルールセットを表示します
ssh-session-policy-upsert	セッション固有のカスタムポリシールールを追加または更新します
ssh-session-policy-remove	セッション固有のカスタムポリシールールを削除します
ssh-session-policy-reset	現在のセッションの継承ルールを復元します
ssh-session-set-active	デフォルトのセッションを選択します
ssh-viewer-ensure	ローカルビューアーを開くか、既存のものを再利用します
ssh-viewer-list	追跡中のビューアープロセスを一覧表示します
ssh-session-close	セッションを正常に閉じます
ssh-quick-connect	エージェント向けのワンステップ接続フローです
ssh-run	主なコマンド実行ツールです
ssh-status	ランタイムの概要を表示します
ssh-command-status	非同期ポーラーです
ssh-retry	再試行を実行します

ローカルオペレーターコマンド

これらのヘルパーは、ビューアーを所有するワークステーション上のユーザー向けです。

ssh-session-mcp-ctl status
ssh-session-mcp-ctl devices
ssh-session-mcp-ctl launch --viewerPort=auto
ssh-session-mcp-ctl launch --local --viewerPort=auto
ssh-session-mcp-ctl logs --tail=60
ssh-session-mcp-ctl cleanup

オペレーター向けのデフォルトルールライブラリ管理：

ssh-session-mcp-config policy list --scope=merged
ssh-session-mcp-config policy set error-kubectl-delete --pattern="\\bkubectl\\s+delete\\b" --category=dangerous --action=error --priority=0 --message="kubectl delete is blocked in safe mode"
ssh-session-mcp-config policy remove error-kubectl-delete

同等のリポジトリローカルコマンドもあります。

npm run launch
npm run status
npm run devices
npm run logs
npm run cleanup

設定の概要

主な環境変数：

変数	意味	デフォルト
SSH_HOST	従来形式の単一ターゲット SSH ホスト	従来モードでは必須
SSH_PORT	従来形式の単一ターゲット SSH ポート	22
SSH_USER	従来形式の単一ターゲット SSH ユーザー	従来モードでは必須
SSH_PASSWORD	パスワード認証	空
SSH_KEY	ローカル秘密鍵のパス	空
SSH_PASSWORD_FILE	SSH パスワードを含むファイル	空
SSH_KEY_FILE	SSH 秘密鍵を含むファイル	空
SSH_MCP_INSTANCE	実行時の分離キー	proc-<pid> またはヘルパーによる選択値
SSH_MCP_CONFIG	明示的な設定ファイルのパス	自動検出
SSH_MCP_STATE_DIR	実行時状態のルートディレクトリ	プラットフォームのデフォルト
VIEWER_HOST	ビューアーのバインド先ホスト	127.0.0.1
VIEWER_PORT	ビューアーのポートまたは auto	設定がない場合は 0
VIEWER_ACCESS_MODE	ビューアーの IP フィルターモード	設定に基づく
SSH_MCP_MODE	safe または full	safe
SSH_MCP_LOCAL	SSH の代わりにローカルシェルを起動	false
SSH_MCP_DEBUG	デバッグ用ブラウザー操作を有効化	false
AUTO_OPEN_TERMINAL	ブラウザーターミナルを自動で開く	false
SSH_MCP_LOG_MODE	off、meta、または stderr のログ記録	off
SSH_MCP_LOG_DIR	メタデータログのディレクトリ	プラットフォームのデフォルト

Distributed v0

Distributed v0 では、意図的に限定された境界を実装しています。

• サポートする実行モード：single-node と distributed
• 分散モードで共有するのはコントロールプレーンの状態のみです。ノードのハートビート、セッションメタデータ、バインディングメタデータ、コマンドメタデータ、ビューアーのアクセス方針が含まれます。
• 現在のレプリカが所有者でない場合、HTTP API は REMOTE_OWNER を返し、HTML ページにはリモート所有者エラーページが表示され、WebSocket 接続はコード 4009 で閉じられます。
• ノード間の PTY 移行はサポートされていません。
• ノード間の透過的な HTTP または WebSocket プロキシはサポートされていません。

Distributed v0 で実際のマルチノード環境を構築するには Redis が必要です。SSH_MCP_STORE=memory はローカルでのスケルトンテスト用にのみ存在し、レプリカ間で共有ストアを提供しません。

分散構成：

変数	意味	デフォルト
SSH_MCP_RUNTIME_MODE	single-node または distributed	single-node
SSH_MCP_STORE	memory または redis	分散モードでは redis、それ以外では memory
SSH_MCP_REDIS_URL	Redis 接続 URL	SSH_MCP_STORE=redis の場合は必須
SSH_MCP_NODE_ID	このレプリカの安定した論理ノード ID	実行時のインスタンス ID
SSH_MCP_PUBLIC_BASE_URL	他のレプリカに通知する公開ビューアーのベース URL	未設定
SSH_MCP_AUTH_MODE	off または proxy	off
SSH_MCP_TRUST_PROXY	認証済みプロキシヘッダーを信頼するかどうか	false
SSH_MCP_AUTH_USER_HEADER	認証済みユーザーのヘッダー名	x-ssh-session-mcp-user
SSH_MCP_AUTH_ROLE_HEADER	認証済みロールのヘッダー名	x-ssh-session-mcp-role

推奨する分散環境の例：

SSH_MCP_RUNTIME_MODE=distributed
SSH_MCP_STORE=redis
SSH_MCP_REDIS_URL=redis://redis:6379/0
SSH_MCP_NODE_ID=node-a
SSH_MCP_PUBLIC_BASE_URL=https://ssh-mcp.example.com
SSH_MCP_AUTH_MODE=proxy
SSH_MCP_TRUST_PROXY=true
SSH_MCP_AUTH_USER_HEADER=x-forwarded-user
SSH_MCP_AUTH_ROLE_HEADER=x-forwarded-role

プロキシ認証は、信頼できるリバースプロキシの背後で分散モードを使用する場合に最も有用です。組み込みのロールマッピングは次のとおりです。

• viewer_read：ページ、セッション一覧／読み取りエンドポイント、履歴、診断、ヘルスチェック、レディネス、メトリクス
• viewer_write：接続入力、サイズ変更、制御
• session_admin：モード変更、ポリシー更新、終了、アクティブ設定、デバッグエージェント操作、ローカルデバッグセッションの作成

マクロ／環境変数のリファレンス

インストール方法に応じて、次の変数を使用してください。

変数	必須となる条件	使用できる値／例	備考
SSH_HOST	レガシーな単一ターゲット SSH モード	YOUR_DEVICE_HOST	ssh-session-mcp.config.json または --local を使用しない場合に必須です。
SSH_PORT	レガシーな単一ターゲット SSH モード	22	レガシーモードでは任意です。既定値は 22 です。
SSH_USER	レガシーな単一ターゲット SSH モード	YOUR_DEVICE_USER	デバイスプロファイルを使用しない場合に必須です。
SSH_PASSWORD	パスワード認証	エクスポート済み環境変数	パスワードをコマンドラインに直接記述するより、環境変数としてエクスポートすることを推奨します。
SSH_PASSWORD_FILE	シークレットファイルを使ったパスワード認証	/run/secrets/ssh_password	ファイルの内容がパスワードとして使用されます。Docker と Kubernetes のシークレットには、この方法を推奨します。
SSH_KEY	レガシーモードでの鍵認証	/absolute/path/to/private/key	MCP サーバーを実行するホスト上に、このパスが存在する必要があります。
SSH_KEY_FILE	シークレットファイルを使った鍵認証	/run/secrets/ssh_private_key	ファイルの内容が秘密鍵として使用されます。マウントされたコンテナーシークレットとの併用に適しています。
SSH_MCP_CONFIG	プロファイルベースのモード、または cwd 外の設定ファイル	/path/to/ssh-session-mcp.config.json	設定ファイルの自動検出だけでは不十分な場合に使用します。
SSH_MCP_INSTANCE	複数エージェント／複数クライアントの分離	agent-a	2 つのエージェントでランタイム状態を共有しない場合は、異なる値を使用します。
SSH_MCP_STATE_DIR	ランタイム状態のルートディレクトリの上書き	/workspace/state	インスタンスごとのサーバー情報、ビューアーの状態、既定のログの保存先を指定します。コンテナーでは永続化できるようにマウントしてください。
SSH_MCP_RUNTIME_MODE	分散トポロジーの選択	single-node、distributed	分散 v0 で共有されるのはコントロールプレーンの状態のみです。ノード間で PTY は移行されません。
SSH_MCP_STORE	分散状態のバックエンド	memory、redis	実際のマルチノードデプロイでは redis を使用します。memory はローカルでの分散スケルトンのテスト専用です。
SSH_MCP_REDIS_URL	Redis バックエンドが有効な場合	redis://redis:6379/0	SSH_MCP_RUNTIME_MODE=distributed かつ SSH_MCP_STORE=redis の場合に必須です。
SSH_MCP_NODE_ID	分散ノードの固定 ID	node-a	複数のレプリカで Redis を共有し、永続的なオーナー ID が必要な場合に便利です。
SSH_MCP_PUBLIC_BASE_URL	このノードのパブリックルーティングのヒント	https://ssh-mcp.example.com	REMOTE_OWNER ペイロードとクラスターのステータス出力で使用されます。
SSH_MCP_AUTH_MODE	ビューアーの認証モード	off、proxy	proxy は、信頼できるリバースプロキシの背後でのみ使用することを推奨します。
SSH_MCP_TRUST_PROXY	ビューアーの識別情報ヘッダーを信頼するかどうか	true、false	SSH_MCP_AUTH_MODE=proxy と併せて有効にする必要があります。
SSH_MCP_AUTH_USER_HEADER	プロキシ認証で使うビューアーユーザーヘッダー	x-forwarded-user	ヘッダー名は内部で小文字に正規化されます。
SSH_MCP_AUTH_ROLE_HEADER	プロキシ認証で使うビューアーロールヘッダー	x-forwarded-role	ロールはカンマ区切りで指定し、viewer_read、viewer_write、session_admin にマッピングされます。
VIEWER_HOST	ビューアーのバインド先のカスタム指定	127.0.0.1、0.0.0.0	コンテナー内では 0.0.0.0 を使用します。リモートアクセスが必要な場合を除き、通常のホストへのインストールでは 127.0.0.1 のままにしてください。
VIEWER_PORT	ビューアーが有効な場合	auto、0、8793	auto は空きポートを選択し、0 はビューアーを無効にします。Docker では固定ポートが最適です。
VIEWER_ACCESS_MODE	ビューアーのアクセス制御モード	allow_all、allowlist、denylist	通常はビューアーのホームページで編集します。localhost のみで使用する場合に限り、allow_all のままにしてください。
AUTO_OPEN_TERMINAL	ビューアータブの自動起動	true、false	コンテナーでは通常 false にします。
SSH_MCP_MODE	ランタイムの安全モード	safe、full	既定値には safe を推奨します。
SSH_MCP_LOCAL	ローカルデモモード	true、false	SSH の代わりにローカルシェルを起動します。
SSH_MCP_DEBUG	ブラウザーのデバッグ制御	true、false	デモやトラブルシューティングを目的としています。
SSH_MCP_LOG_MODE	ランタイムメタデータのログ記録	off、meta、stderr	meta は、生のシークレットを保存せずに JSONL メタデータログを書き込みます。stderr は、stdio の MCP トランスポートを維持しながら、構造化ログをコンテナーランタイムに出力できるため、コンテナーではこちらを推奨します。
SSH_MCP_LOG_DIR	メタデータログディレクトリの上書き	/workspace/state/instances/<instance>/logs	主に SSH_MCP_LOG_MODE=meta の場合に便利です。stderr では無視されます。
SSH_KEY_DIR	Docker Compose のプロファイルベースの例	/path/to/host/keys	docker-compose.yml では任意です。未設定の場合は ./keys が使用されます。
SSH_SESSION_MCP_IMAGE	Docker Compose のイメージの上書き	docker.io/zwawa/ssh-session-mcp:latest	イメージをミラーリングする場合や、別のタグをテストする場合に上書きします。

最小限の必須設定

次の最小構成のいずれかを選択してください。

• ローカルデモ：SSH_MCP_LOCAL=true と VIEWER_PORT=auto
• パスワードを使用するレガシー SSH：SSH_HOST、SSH_USER、SSH_PASSWORD
• キーを使用するレガシー SSH：SSH_HOST、SSH_USER、SSH_KEY
• プロファイルベースのモード：ssh-session-mcp.config.json と、その設定で参照される passwordEnv 変数
• Docker Compose のプロファイルモード：ssh-session-mcp.config.json、任意で SSH_KEY_DIR、任意で SSH_SESSION_MCP_IMAGE

コンテナランタイムに関する注意事項

• コンテナのデフォルトでは SSH_MCP_LOG_MODE=stderr が設定されているため、stdio の MCP トランスポートを破損させることなく、ログがコンテナランタイムに送られます。
• ビューアーポリシー、サーバー情報、状態ファイルをコンテナの再起動後も保持する場合は、SSH_MCP_STATE_DIR を永続化してください。
• 分散マルチノード構成では、Redis と、レプリカごとにルーティング可能な SSH_MCP_PUBLIC_BASE_URL が必要です。
• 分散 v0 では、ノード間の PTY 移行や、透過的なノード間プロキシは提供されません。REMOTE_OWNER を受け取った場合は、所有ノードにリクエストをルーティングしてください。
• ヘルスエンドポイント：
  • プロセスの稼働確認には /livez
  • レディネスチェックには /readyz
  • Prometheus 形式のテキストメトリクスには /metrics
• Kubernetes の単一インスタンス構成例：docs/examples/ssh-session-mcp.k8s.single-instance.yaml
• Kubernetes の分散構成例：docs/examples/ssh-session-mcp.k8s.distributed.example.yaml
• Kubernetes の主なインストール先：deploy/helm/ssh-session-mcp

設定ファイルの例：docs/examples/ssh-session-mcp.config.example.json

セキュリティ

• パッケージが、追跡対象の JSON 設定ファイル内に生のパスワードを記述するよう求めることはありません。
• .env は git と npm による追跡対象外です。
• ビューアーの HTTP はデフォルトで localhost にバインドされます。
• MCP サーバーは、ターミナルモードと入力ロックを最重要の安全性シグナルとして扱います。
• CI では、Trivy のファイルシステムスキャンとコンテナイメージスキャンを実行し、深刻度が高および重大な脆弱性を検出します。
• CI では、変動するサードパーティアクションのタグに依存するのではなく、チェックサム検証を行って固定された Trivy CLI リリースをインストールします。
• リリースビルドでは、公開された GHCR イメージのダイジェストを対象に CycloneDX SBOM を生成し、GitHub リリースに添付します。
• リリースビルドでは、鍵不要の Cosign を使用して、公開された GHCR イメージのダイジェストに署名します。
• 検証の主な手段は GHCR のダイジェストです。Docker Hub は配布経路であり、署名検証の主な対象ではありません。

ポリシーの全文については、SECURITY.md を参照してください。

プラットフォームに関する注意事項

• Windows 10/11：主要なホスト環境
• Linux：ヘッドレス MCP とブラウザービューアーを使用するワークフローに最適です
• macOS：標準の Node.js パスをサポートします
• リモートの Linux ホスト：主要な対象環境

詳細：docs/platform-compatibility.md

ドキュメント

• AGENT.md
• AI_AGENT_GUIDE.md
• llms-install.md
• docs/contracts.md
• docs/failure-taxonomy.md
• docs/acceptance-scenarios.md
• docs/docker.md
• docs/kubernetes.md
• docs/ingress-proxy-auth.md
• CHANGELOG.md

開発

ソースを変更する場合、ローカルでテストを実行する場合、またはリリース成果物をビルドする場合にのみ、リポジトリをクローンしてください。

npm install
npm run build
npm run test
npm run validate:repo
npm run build:site

このリポジトリに含まれる GitHub Actions では、次のことができます。

• push とプルリクエストで CI を実行する
• dist/ から GitHub Pages のランディングページをデプロイする
• npm パッケージの tarball を添付した、タグ付きの GitHub リリースをビルドする

ライセンス

Apache-2.0。LICENSE を参照してください。