ssh-mcp

ssh-mcp

Streamable HTTP を介して AI エージェントに制御された SSH アクセスを提供する、集中型 MCP ゲートウェイです。

どのような問題を解決しますか？

ほとんどの MCP SSH サーバーは、ローカルの stdio プロセスとして動作します。クライアントごとにプロセスが必要で、状態の共有、集中型の認可、監査証跡はありません。複数の AI エージェントが SSH アクセスを必要とする場合、各エージェントが独自の SSH キーを管理し、それぞれ独自のプロセスを実行します。その結果、次の問題が生じます。

• 集中型のアクセス制御がない — 各クライアントが実行可能な内容を決定します
• 監査証跡がない — コマンドが運用チームから見えません
• SSH キーの乱立 — エージェントの各マシンにキーが分散します
• レート制限がない — 暴走したエージェントがターゲットに過剰な負荷をかける可能性があります

ssh-mcp は、単一の HTTP ゲートウェイをデプロイすることでこれらの問題を解決します。すべてのクライアントがゲートウェイに接続し、ゲートウェイが SSH ターゲットに接続します。認可、レート制限、接続プーリング、監査ログを一元管理できます。

クイックスタート

ビルド済みイメージを使用する（推奨）

docker compose pull
docker compose up -d

イメージは ghcr.io/gelse/ssh-mcp:latest で公開されています。 compose ファイルはホストのポート 9080 をコンテナのポート 8080 に割り当てます。

サーバーが実行中であることを確認します。

curl http://localhost:9080/health
# → {"status": "ok"}

config/ssh-mcp-config.json に最小限の設定を作成します。

{
  "version": 1,
  "ssh_targets": {
    "my-server": {
      "host": "10.0.1.10",
      "username": "deploy"
    }
  },
  "allowed_commands": {
    "default": [
      {
        "targets": ["*"],
        "commands": ["hostname", "uptime", "free", "df"]
      }
    ]
  }
}

API キーのハッシュを生成し、設定ファイルまたは secrets.json に追加します（設定を参照）。

make build
docker compose up -d --build

できること（ツール）

Streamable HTTP 経由で、6 つの MCP ツールを利用できます。

ツールの命名規則

すべてのツールは ssh_<verb>_<noun> の形式に従います。

• ssh_list_servers — リソースを一覧表示します
• ssh_list_allowed_commands — 権限を一覧表示します
• ssh_execute_command — 操作を実行します
• ssh_check_connection — 接続を確認します
• ssh_download_file / ssh_upload_file — ファイルを転送します

curl コマンドや Python クライアントのコードを含む使用例については、examples/README.md を参照してください。

設定可能な項目

ssh-mcp は、ホットリロードに対応した JSON ファイルで設定します （15 秒間隔でポーリング、デバウンス 2 秒）。主な設定項目は次のとおりです。

詳細なリファレンス：docs/CONFIGURATION.md

素の SSH や他の MCP サーバーではなく、なぜこれを使うのですか？

ssh-mcp は、すべてのクライアントリクエストとすべての SSH コマンドの間に、9 層からなる順序付きの認可チェーンを設けます。API キーごと、ネットワークごとにルールを設定できるため、基盤となる SSH アカウントに手を加えることなく、異なるエージェントに異なるサーバー上で異なる権限を付与できます。

追加の保護機能：

• サーキットブレーカーにより、障害が発生したターゲットを指数バックオフで隔離します
• レート制限により、制御不能になったエージェントがホストに過剰な負荷をかけるのを防ぎます
• 構造化監査ログにより、すべてのコマンド、クライアント、IP、認可の判断を追跡できます
• コネクションプーリングにより、リクエスト間で SSH セッションを再利用します
• 入力のサニタイズと危険なパターンの検出により、シェルインジェクションの試みをブロックします

アーキテクチャ：ARCHITECTURE.md セキュリティモデル：docs/SECURITY.md

これは何ではないか

• 対話型シェルではありません — コマンドは個別に実行され、構造化された出力が返されます
• ファイルマネージャーではありません — SFTP がサポートするのは単一ファイルのダウンロードとアップロードのみです（ディレクトリ一覧表示や再帰転送はできません）
• ファイアウォール／ネットワーク ACL ではありません — 認可はコマンドレベルで行われ、ネットワークレベルではありません
• SSH アカウントの権限を縮小するものではありません — コマンドが許可されている場合、SSH ユーザーはそのアカウントが持つ権限で実行します

未対応／既知の制限事項

貢献によって修正可能：

• SFTP は単一ファイルのみです — ディレクトリ一覧表示や再帰転送はできません
• TLS 終端機能はありません — 前段に Traefik または nginx を配置してください
• OAuth や mTLS によるアプリケーション層認証はありません
• レートリミッターの設定はホットリロードできません（起動時に設定します）

アーキテクチャ上の制限：

• Config API ダッシュボードのログインセッションはメモリ内のみです — 再起動後は保持されず、API は単一インスタンスで動作します（設定の変更自体は通常どおり設定ファイルに保持されます）
• 監査ログの改ざん防止機能はありません

オブザーバビリティ

• ヘルス： GET /health — {"status": "ok"} を返します
• メトリクス： GET /metrics — Prometheus のエクスポジション形式
• ロギング： リクエスト相関情報を含む構造化 JSONL

完全なリファレンス：docs/OBSERVABILITY.md

Config API とダッシュボード

JSON ファイルを編集せずに設定を管理できる、オプションのウェブダッシュボードです。CONFIG_API_ENABLED=true で有効にします。

完全なリファレンス：docs/CONFIG-API.md

よくある質問

HTTP 経由でダッシュボードにアクセスすると 401 が返る

セッション Cookie はデフォルトで Secure（HTTPS のみ）に設定されています。ローカルで HTTP を使ってテストする場合は、次のように設定してください：

environment:
  - CONFIG_API_SESSION_COOKIE_SECURE=false

その後、コンテナを再起動してください。

MCP クライアントはどのように接続しますか？

Streamable HTTP トランスポートを使用して http://host:9080/mcp に接続します。API キーは X-API-Key または Authorization: Bearer ヘッダーで渡してください。

API キーのハッシュはどのように生成しますか？

docker compose exec mcp-ssh python -c \
  "from lib.crypto import hash_api_key; print(hash_api_key('your-key'))"
# → pbkdf2:sha256:100000$<salt>$<hash>

または、Config API ダッシュボードのハッシュユーティリティを使用してください。

ホットリロードはどのように動作しますか？

設定ファイルは 15 秒ごとにポーリングされ、2 秒のデバウンスが適用されます。ターゲット、コマンド、設定の変更は再起動せずに反映されます。レートリミッターとログ出力先の設定を変更するには再起動が必要です。

コマンドが拒否されたのはなぜですか？

コマンドは 9 層の認可チェーンを通じて評価されます。ログの matched_via フィールドに、どの層で拒否されたかが表示されます。チェーンの全容については、セキュリティモデルを参照してください。

レート制限はどのように動作しますか？

IP ごとのスライディングウィンドウ方式で、デフォルトは 60 秒間に 60 リクエストです。制限を超えると HTTP 503 が返されます。設定ファイルの settings.rate_limit で設定してください。

ログはどこに出力されますか？

ログは /logs ボリューム（./logs からマッピング）に書き込まれます。アクティブなログファイルは ssh-mcp.log で、JSONL 形式です。オプションで gzip ローテーションを設定できます。

基本的なトラブルシューティング

# Check server health
curl http://localhost:9080/health

# Validate config
make config-test

# Check logs
docker compose logs mcp-ssh

ドキュメント

開発

# Unit tests
make test

# Integration tests (builds Docker image)
make integrationtest

開発ガイド、コーディング規約、PR ワークフローの詳細については、 CONTRIBUTING.md をご覧ください。

ロードマップ

公開ロードマップはありません。現在の制限と改善の機会については、 未対応事項／既知の課題をご覧ください。

ライセンス

MIT