MCP Hub

1つのMCPサーバーであなたのAIアシスタントにホームラボ全体の鍵を渡します。

MCP Hubは、ネットワーク内の1台のマシンに配置され、そこからSSHでフリート内のすべてのホスト、Proxmoxコンテナ、Docker、Synology DSM、CloudflareトンネルとDNS、n8nワークフロー、Notion、パスワードボールトにアクセスする単一のModel Context Protocolサーバーです。多数のMCPサーバーを実行してそれぞれをクライアントに配線する代わりに、1つを実行してアシスタントをそのサーバーに向けるだけです。

「なぜJellyfinに到達できないのか？」 — アシスタントがコンテナを確認し、ジャーナルを読み取り、トンネルのイングレスが古くなっていることに気づき、修正し、何をしたかを伝えます。

⚠️ デプロイする前にSECURITY.mdをお読みください。 MCP HubはLLMにフリート全体へのrootシェルアクセスを提供します。それがこのツールの目的であり、本当に危険です。デフォルトは安全です（127.0.0.1、読み取り専用）。危険は設定を変更したときに始まります。

トラブルシューティングデモ

このリポジトリには、サニタイズされたAsciinema録画が含まれています。これは、完全な観察優先のトラブルシューティングセッション（失敗したエンドポイント、systemd診断、正確な変更計画、明示的な確認、再起動、最終的なヘルスチェック）です。サンプルインベントリを使用しており、プライベートなインフラデータは含まれていません。

asciinema play docs/troubleshooting.cast

Asciinemaがインストールされていない場合は、録画を直接参照してください。キャスト形式は改行区切りのJSONであり、レビュー可能です。

Related MCP server: homelab-mcp

目次

• 機能

• クイックスタート

• デプロイ

• ローカルテスト

• レスキュー診断

• 設定

• ツールリファレンス

• セキュリティ

• バージョン管理

• コントリビューション

機能

• 111のツール、1つのエンドポイント、1つの設定ファイル。

• 設定駆動型。 ネットワークはhosts.yamlと.envに記述します。インフラストラクチャに関する情報はコードに組み込まれていません。

• 多重化SSH。 永続的な制御ソケットにより、フリート全体のコマンドがTCPハンドシェイクごとにミリ秒単位で実行されます。

• オプションの統合。 すべての統合はデフォルトでオフになっており、1つのフラグで有効になります。SSHフリートツールとしてのみ使用したい場合は、そのまま使用できます。

• プラグ可能なシークレット。 環境から、またはbw serveを介してBitwarden/Vaultwardenのボールトから資格情報を読み取ります。

• ベアラートークン認証 推測不可能なエンドポイントパスの上に実装。

• グローバル読み取り専用モード（デフォルトでオン）：1つのフラグで43の変更ツールすべてを無効にし、ツールごとではなく中央で強制します。

• ファイル読み取りとコマンド出力における自動シークレット編集。

• バックグラウンドジョブ（ポーリング、ログ、永続的なSQLite状態ストア付き）。

クイックスタート

Python 3.11+と、管理したいマシンへのSSHアクセスがあるLinuxホストが必要です。

git clone https://github.com/wnx82/mcp-hub.git
cd mcp-hub

python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env                  # then edit — see below
cp hosts.example.yaml hosts.yaml      # then edit: your fleet
chmod 600 .env hosts.yaml

python server.py

最低限、.envに次の2つを設定します。

MCP_SECRET_PATH=/$(openssl rand -hex 16)   # unguessable endpoint path
MCP_AUTH_TOKEN=$(openssl rand -hex 32)     # bearer token — the real auth

サーバーはhttp://127.0.0.1:8000<MCP_SECRET_PATH>でリッスンし、MCP_READ_ONLY=trueが設定されます。MCPクライアントをそのURLに向け、Authorization: Bearer <MCP_AUTH_TOKEN>を送信します。トークンがないリクエストは401、他のパスへのリクエストは404になります。

HTTPではなくstdioを必要とするローカルMCPクライアントの場合は、同じハブを次のように起動します。

mcp-hub --transport stdio

または、起動前に環境にMCP_TRANSPORT=stdioを設定します。

systemdデプロイの場合、sudo ./deploy/install.shは専用のmcphubユーザーとSSHキーを作成し、両方のシークレットを/etc/default/mcp-hubに生成し、ユニットをインストールします。冪等であり、既存の設定を上書きすることはありません。deploy/を参照してください。

完全なClaude Codeのセットアップ、安全なトークン処理、接続チェック、最初の読み取り専用プロンプト、および現在のClaude Desktopの制限については、**MCP HubをClaudeに接続する**を参照してください。

アシスタントにプライベートなトポロジ、ホストの役割、変更ウィンドウ、MCP運用ルールを理解させたいが、それらのデータをコミットしたくない場合は、PROJECT_INSTRUCTIONS.example.mdから始めて、カスタマイズしたPROJECT_INSTRUCTIONS.mdをローカルのみに保持してください。

デプロイ

MCP Hubは3つの実行モードをサポートしています。

Pythonパッケージと直接実行は、現在のチェックアウトとそのvirtualenvを使用します。サービスアカウント、SSHキー、環境ファイル、再起動ポリシーは作成しません。systemdインストーラーはこれらの運用部品をプロビジョニングし、再実行時にローカル設定をそのまま保持し、ハブのvirtualenvの外部にRescueをインストールします。

コンテナイメージはまだ公式のデプロイターゲットではありません。ハブはネットワークアクセス、SSH ID、永続的なstate.db、およびローカルインベントリへのアクセスを必要とします。コンテナにパッケージ化するオペレーターは、これらのプロパティを自分で保持する必要があります。

現在の要件と、公式イメージが推奨される前に保証する必要があるものについては、docs/docker-packaging.mdを参照してください。

ローカルテスト

lint、ユニットテスト、ツール登録、生成ドキュメント、インストーラースモークテスト、手動読み取り専用実行をカバーするコントリビューター向けチェックリストについては、**docs/testing-local.md**を参照してください。

MCP 2026-07-28移行の概要、互換性マトリックス、ロールバック手順については、**docs/migration/mcp-2026-07-28-guide.md**を参照してください。

PRを開いたりブランチを公開したりする前に、ローカルリリース準備チェックを実行することもできます。

python3 scripts/check_repo_hygiene.py
python3 scripts/check_tool_annotations.py
python3 scripts/check_security_readiness.py

セキュリティ準備チェックをプッシュ時にGitに自動的に組み込むには：

./scripts/install_pre_push_hook.sh

アーキテクチャ

server.pyはMCPサーバーの構成ルートであり続けますが、ドメインコードは段階的にtools/に移動しています。SSHコマンド構築、Cloudflareパスと応答抽出、DSMプロトコルメタデータ、インベントリ、プレイブックビルダーはすでに分離されています。tools/registry.pyは抽出されたツールをドメインに割り当てます。そのドメインは各監査サマリーに含まれます。新しいプロトコルロジックはそのドメインモジュールに配置し、server.pyをインポートしてはいけません。

将来の統合は、最小特権スコープと昇格ゲートを含めて、docs/integration-evaluation.mdで優先順位付けされています。

レスキュー診断

mcp-hub-rescueは、メインサーバーがインポートできない場合やそのvirtualenvが壊れている場合でも動作し続けるように設計された、読み取り専用のローカルCLIです。systemdインストーラーはこれを/opt/mcp-hub-rescueにコピーし、システムPythonでMCP Hubプロセスとvirtualenvの外部で実行します。

sudo mcp-hub-rescue doctor
sudo mcp-hub-rescue status
sudo mcp-hub-rescue health
sudo mcp-hub-rescue logs --lines 50
sudo mcp-hub-rescue validate-config

結果は構造化JSONです。Rescueはserver.py、tools/*、MCP、またはオプションの統合を決してインポートしません。この境界はCIによって強制されます。現在のコマンドは観察と診断のみを行います。再起動、修復、ロールバック操作は、確認と最後の正常動作のセーフガードとともに別途追加されます。

設定

すべてgit無視されています。それぞれに追跡された.exampleテンプレートがあります。

ホストエントリは設計上最小限です。

hosts:
  nas:
    hostname: nas.example.lan
    user: admin
    role: storage
    tags: [nas, backup]
    mac: "aa:bb:cc:dd:ee:01"   # optional, enables wake_host()

タグはグループを指定する方法です：fleet_exec(tag="backup", command="df -h")。コピー可能な2ホストインベントリについては、docs/examples/hosts.minimal.yamlから始めてください。より大きなhosts.example.yamlは、サポートされているすべてのホストオプションを示しています。

docs/examples/topology.guarded.yamlと組み合わせて、Proxmoxゲストをマッピングし、古いアドレストラップを記録し、気軽に変更してはいけないインフラを表面化します。_do_not_touchエントリはアシスタントの運用コンテキストであり、強制されたアクセス制御境界ではありません。技術的な強制にはトークンプロファイルとホスト制限を使用してください。

docs/examples/endpoints.minimal.yamlを追加して、常時稼働および断続的なHTTPサービスを監視します。通常のセットにはendpoints_health()を呼び出し、通常は電源がオフになっている可能性のあるサービスを含めるにはendpoints_health(include_intermittent=true)を呼び出します。200から399までの応答は正常と見なされます。リダイレクトは追跡されません。

完全なデフォルト、制限、統合設定、シークレット処理の注意事項は、**環境変数リファレンス**にあります。

追跡されたこれらの例と、プライベートで追跡されていないPROJECT_INSTRUCTIONS.mdを組み合わせて、アシスタントがトポロジの注意点、メンテナンスウィンドウ、命名規則、リポジトリに置くべきでない「触らないで」ガイダンスを認識できるようにします。

ツールリファレンス

すべてのツールは同じトップレベルのエンベロープを返します。

{
  "ok": true,
  "data": {},
  "error": null,
  "duration_ms": 12,
  "host": "example",
  "request_id": "4d52b1f69b974b7784bf65dd",
  "tool": "system_info"
}

dataにはツール固有のペイロードが含まれます。セキュリティ拒否と制御された例外は、ok: falseで同じ形状を使用するため、チェーン呼び出しと監査の相関が予測可能になります。

中央ツールラッパーは、リクエストサイズ、トークンあたりの呼び出し数、ターゲットあたりの同時呼び出し数、繰り返されるターゲット障害、変更頻度も制限します。デフォルトは.env.exampleに文書化されています。制限拒否は、他のすべての呼び出しと同じ応答エンベロープと監査証跡を使用します。

完全な生成ツールリファレンス は、各グループを各ツールの正確なシグネチャとモデル向けの説明を含むテーブルに展開します。CI は登録された関数に対してそれを検証します。

ガイド付き診断は常に観察後に停止します。それらは証拠、評価、および correction_applied: false とともに次のステップの提案を返します。check_backup_chain は鮮度とストレージのシグナルであり、復元が成功するという証明ではありません。

セキュリティ

MCP Hub は設計上、リモートコード実行サービスです。公開する前に以下の点を確認してください：

• デフォルトの 127.0.0.1 バインディングを維持するか、アクセスポリシー付きのトンネルの背後に配置します。

• MCP_AUTH_TOKEN を設定します — シークレットURLパスは難読化であり、認証ではありません。

• モデルが何をするかを信頼するまでは MCP_READ_ONLY=true のままにしておきます。

• リソースガードのデフォルトを有効にしたままにし、監視された監査トラフィックから調整を行い、無効にしないでください。

• 専用のSSHキーと最小限の hosts.yaml を割り当てます。

完全な脅威モデル、強化ガイド、脆弱性報告については：SECURITY.md。

公開前のチェックリストと、プッシュ前に一般的な秘密漏洩のミスを検出するオプションのGitフックについては、scripts/check_security_readiness.py および scripts/install_pre_push_hook.sh を参照してください。

バージョン管理

SemVer。1.0 未満では、破壊的変更は マイナー バージョンを上げます — そのため、アップグレードする前に Changed と Removed のノートを読んでください。_version.py が単一の信頼源です。実行中のサーバーは mcp-hub --version、MCPハンドシェイク、および mcp_health でそれを報告します。

すべてのリリースは CHANGELOG.md に文書化されており、セキュリティ関連の変更は独自のセクションで強調表示されます。

コントリビューション

問題やプルリクエストは歓迎します — 特にバグ報告、新しい統合、ドキュメント修正です。CONTRIBUTING.md を参照してください。

ライセンス

MIT © wnx82