homelab-infra-mcp

Homelab

Homelab は、AI アシスタントが Nginx Proxy Manager のプロキシホスト、Docker コンテナー、Cloudflare DNS レコードを一か所から管理できる MCP サーバーです。コンテナーから公開 Web アドレスまでの一連の手順をカバーします。expose_service を 1 回呼び出すだけで、コンテナーを確認し、DNS レコードとプロキシホストを追加し、変更を加える前に実行計画を表示します。さらに、Uptime Kuma、Cloudflare Tunnel、AdGuard Home、Authentik に対応する 4 つのオプションモジュールがあります。

これは バンドル です。モジュールで構成される 1 つのサーバーと、アシスタントにワークフローを教えるスキルが含まれます。使用するモジュールを有効にします。新しいモジュールは無効の状態で追加されるため、選択するまでは、更新によってアシスタントができることが変わることはありません。

対象ユーザー： ホームラボを運用するセルフホストユーザー。

モジュール	機能	状態
proxy	Nginx Proxy Manager：プロキシホスト、リダイレクト、SSL 証明書、アクセスリスト	デフォルトで有効
docker	ローカルの Docker ソケットまたは Portainer を通じたコンテナー、イメージ、ボリュームの管理	デフォルトで有効
dns	Cloudflare DNS ゾーンとレコード、および BIND エクスポート	デフォルトで有効
home_assistant	Home Assistant のエンティティ、自動化、スクリプト、システム情報	デフォルトで無効。有効にするには HOMELAB_HOME_ASSISTANT_ENABLED=true を設定
uptime	Uptime Kuma のモニター：ステータスの一覧表示と読み取り（読み取り専用）	デフォルトで無効。有効にするには HOMELAB_UPTIME_ENABLED=true を設定
tunnel	Cloudflare Tunnel のルート：一覧表示、追加、削除	デフォルトで無効。有効にするには HOMELAB_TUNNEL_ENABLED=true を設定
dns_filter	AdGuard Home：フィルターのステータス、クエリログ、フィルタールール	デフォルトで無効。有効にするには HOMELAB_DNS_FILTER_ENABLED=true を設定
sso	Authentik：アプリケーションの一覧表示、1 つのホスト向けのプロキシプロバイダーとアプリケーションの作成	デフォルトで無効。有効にするには HOMELAB_SSO_ENABLED=true を設定

コアツールは常に有効です：homelab_modules、homelab_health、expose_service、teardown_service、service_status、infrastructure_overview、diagnose_service。

Homelab は、Claude Desktop、Claude Code、Cursor、VS Code、Sonique、Hermes、OpenClaw など、あらゆる MCP クライアントで使用できます。お使いのマシン上で動作し、独自のデータを保持しません。通信するのは、設定したサービスのみです。

インストール

Homelab の実行には Python 3.11 以降が必要です。uv を使えば、事前にインストールするものはありません。更新は必要なときだけ適用できるよう、バージョンを固定してください：

uvx homelab-infra-mcp==2.1.1 --version

または pip を使います：

pip install homelab-infra-mcp==2.1.1

2.0 からアップグレードしますか？ バージョン 2.1 には破壊的変更はありません。新しい 4 つのモジュールはデフォルトで無効です。CHANGELOG.md の 2.1.0 のセクションをお読みください。

1.x からアップグレードしますか？ バージョン 2.0 では、ツール名と環境変数名が変更されました。まず CHANGELOG.md の移行表をお読みください。

クイックインストール

MCP クライアントにサーバーを追加し（MCP クライアントへの追加を参照）、使用するモジュールの変数を設定して、クライアントを再起動します。次に、アシスタントに homelab_modules を呼び出すよう依頼します。返される内容には、各モジュールの一覧、有効かどうか、不足している設定が表示されます。

Doctor

開始前、および設定を変更した後に、ターミナルで homelab-infra --doctor を実行します：

homelab-infra --doctor

doctor は、有効な各モジュールの設定と接続状態、Docker ソケットへのアクセス、TLS チェックを確認します。問題ごとに FIX の行を出力し、修正が必要な場合はステータス 1 で終了します。

設定

MCP クライアントの設定で環境変数として設定するか、設定ファイルに記述してください（下記参照）。使用するモジュールの設定だけが必要です。Homelab は設定がなくても起動し、ツールを呼び出したときに不足している設定を知らせます。

変数	モジュール	内容
HOMELAB_PROXY_URL	proxy	Nginx Proxy Manager のアドレスです。デフォルトは http://localhost:81 です。
HOMELAB_PROXY_EMAIL / HOMELAB_PROXY_PASSWORD	proxy	API で使用する NPM 管理者のログイン情報です
HOMELAB_DOCKER_HOST	docker	Docker エンジンのアドレスです。デフォルトは unix:///var/run/docker.sock です。
HOMELAB_DOCKER_PORTAINER_URL / HOMELAB_DOCKER_PORTAINER_TOKEN	docker	ソケットの代わりに Portainer を使用します。両方とも必要です。
HOMELAB_DOCKER_PORTAINER_ENDPOINT_ID	docker	Portainer のエンドポイント ID です。デフォルトは 1 です。
HOMELAB_DNS_API_TOKEN	dns	ゾーンの DNS 編集権限を持つ Cloudflare API トークンです
HOMELAB_DNS_ZONE_ID	dns	デフォルトのゾーン ID です。ツールで zone_id を空欄にできます
HOMELAB_HOME_ASSISTANT_URL	home_assistant	Home Assistant のアドレスです。デフォルトは http://homeassistant.local:8123 です。
HOMELAB_HOME_ASSISTANT_TOKEN	home_assistant	長期間有効なアクセストークンです
HOMELAB_UPTIME_URL	uptime	Uptime Kuma のアドレスです
HOMELAB_UPTIME_API_KEY	uptime	Uptime Kuma の API キーです。/metrics から読み取り、list と get に使用します。
HOMELAB_TUNNEL_API_TOKEN	tunnel	トンネルの編集権限を持つ Cloudflare API トークンです
HOMELAB_TUNNEL_ACCOUNT_ID	tunnel	トンネルを所有する Cloudflare アカウント ID です
HOMELAB_TUNNEL_TUNNEL_ID	tunnel	Cloudflare Tunnel ID です
HOMELAB_DNS_FILTER_URL	dns_filter	AdGuard Home のアドレスです
HOMELAB_DNS_FILTER_USERNAME / HOMELAB_DNS_FILTER_PASSWORD	dns_filter	AdGuard Home のログイン情報です
HOMELAB_SSO_URL	sso	Authentik のアドレスです
HOMELAB_SSO_TOKEN	sso	Authentik API トークンです
HOMELAB_SSO_FLOW_SLUG	sso	新しいプロキシプロバイダーが使用する認可フローのスラッグです
HOMELAB_<MODULE>_ENABLED	任意	true または false です。モジュールの有効・無効を切り替えます。例：HOMELAB_UPTIME_ENABLED=true。
HOMELAB_<MODULE>_ALLOW_WRITES	任意	デフォルトは false で、変更のたびに確認を求めます。true にすると、アシスタントは確認なしでそのモジュールに変更を加えられます。安全性を参照してください。
HOMELAB_READ_ONLY	すべて	true にすると、ほかの設定にかかわらずすべての変更を拒否します。読み取りとドライランは引き続き実行できます。
HOMELAB_<MODULE>_<KEY>_FILE	任意	代わりにファイルからシークレットを読み込みます。例：HOMELAB_DNS_API_TOKEN_FILE=/run/secrets/cf_token
HOMELAB_CONFIG	コア	設定ファイルのパスです。デフォルトは ~/.config/homelab/config.toml です。
HOMELAB_APPROVAL_LOG	コア	承認ログのパスです。デフォルトは ~/.local/state/homelab/approvals.jsonl です。XDG_STATE_HOME が設定されている場合は $XDG_STATE_HOME/homelab/approvals.jsonl です。

設定ファイル（任意）。 Homelab は ~/.config/homelab/config.toml、または HOMELAB_CONFIG で指定されたファイルも読み込みます。各モジュールには専用のテーブルがあります。環境変数は設定ファイルより優先されます。

[proxy]
email = "[email protected]"
password = "change-me"

[dns]
api_token = "your-cloudflare-token"
zone_id = "your-zone-id"

同じファイルの enabled キー、または環境変数の HOMELAB_<MODULE>_ENABLED=true でモジュールを有効にできます。

MCP クライアントに追加する

ほとんどのクライアントで同じ JSON 形式を使用します。サーバーがテスト済みのリリースを実行するように、バージョンを固定してください。クライアントが MCP サーバーを保持する場所にブロックを配置します。

{
  "mcpServers": {
    "homelab": {
      "command": "uvx",
      "args": ["homelab-infra-mcp==2.1.1"],
      "env": {
        "HOMELAB_PROXY_EMAIL": "[email protected]",
        "HOMELAB_PROXY_PASSWORD": "change-me",
        "HOMELAB_DNS_API_TOKEN": "your-cloudflare-token",
        "HOMELAB_DNS_ZONE_ID": "your-zone-id"
      }
    }
  }
}

クライアント	設定の場所
Claude Desktop	claude_desktop_config.json（Settings → Developer → Edit Config）
Claude Code	claude mcp add homelab -- uvx homelab-infra-mcp==2.1.1 を実行してから、env の値を追加するか、プロジェクトの .mcp.json に追加します
Cursor	~/.cursor/mcp.json、またはプロジェクト内の .cursor/mcp.json
VS Code	.vscode/mcp.json。"mcpServers" の代わりに "servers" を使用します
Sonique、Hermes、OpenClaw、その他	stdio MCP サーバーを起動する任意のクライアントで使用できます。コマンドは uvx、引数は ["homelab-infra-mcp==2.1.1"]、これに加えて env の値を指定します

Claude Code プラグインとして使用する場合。 プラグインがサーバーとスキルをまとめてインストールします。その .mcp.json では homelab-infra-mcp==2.1.1 が固定されています。環境変数または設定ファイルで変数を設定してください。

HTTP 経由で使用する場合。 プロセスを起動する代わりに URL に接続するクライアント向けです。

homelab-infra --transport http --port 8200

ストリーミング可能な HTTP を http://127.0.0.1:8200/mcp で提供します。デフォルトでは、自分のマシンからのみ接続できます。ほかの場所に公開する前に、認証を設定してください。

ツール

デフォルトのインストールには 16 個のツールが含まれます。各モジュールを有効にすると、そのモジュール独自のツールが追加されます。

ツール	機能
homelab_modules	有効なモジュール、不足している設定、および各ツールの機能を確認します。最初に呼び出してください。
homelab_health	有効なすべてのモジュールの接続状態とバージョン
expose_service	コンテナを確認し、DNS レコード（任意）とプロキシホストを追加します。承認済みのプランを 1 つ実行します。
teardown_service	サービスのプロキシホストと、任意で DNS レコードを削除します。承認済みのプランを 1 つ実行します。
service_status	サービスのコンテナ、プロキシホスト、DNS レコードをまとめて表示します
infrastructure_overview	Docker、プロキシ、DNS の各項目数
diagnose_service	読み取り専用です。ドメインからサービスまでの各ホップを、ホップごとに 1 行で確認します。最初に失敗したホップとその修正方法を返します。
proxy_hosts	プロキシホストの list、get、create、update、delete
proxy_redirections	HTTP リダイレクトの list、create、delete
proxy_certificates	Let's Encrypt 証明書の list、request
proxy_access_lists	IP アクセスリストの list、create、delete
docker_containers	list、get、start、stop、restart、remove、logs、stats、prune
docker_images	list、pull、remove、prune
docker_inventory	volumes、networks、または Portainer の stacks（スタックの compose ファイルを含む）
dns_zones	ゾーンの list、または BIND 形式での export
dns_records	レコードの list、get、create、update、delete
ha_entities	list、get、search、call_service、turn_on、turn_off、toggle（Home Assistant）
ha_automations	オートメーションまたはスクリプトの list、trigger、reload。オートメーション YAML の create はプレビューを返します（Home Assistant）
ha_system	設定、利用可能なサービス、check_config（Home Assistant）
uptime_monitors	list、get：読み取り専用（Uptime Kuma）。一時停止と再開は 2.1 では利用できません。
tunnel_routes	list。add と remove には承認が必要です（Cloudflare Tunnel）
dns_filter_status	フィルターの状態、クエリ数、ブロック数（AdGuard Home、読み取り専用）
dns_filter_queries	ページ分割されたクエリログ（AdGuard Home、読み取り専用）
dns_filter_rules	ブロックされたサービスとカスタムルールの list。add と remove には承認が必要です（AdGuard Home）
sso_applications	list。create は 1 つのホストにプロキシプロバイダーとアプリケーションを作成します。承認が必要です（Authentik）

各ツールは公開済みのスキーマを持つ構造化データを返すため、アシスタントはその結果を使ったコードを記述できます。リストでは limit と offset を指定できます。変更を行う各ツールでは dry_run=true を指定でき、変更内容を正確に表示し、実際の変更は行いません。エラーは常に homelab.<module>.<code>: <message> Fix: <hint> の形式です。

スキル

スキルは、作業の前にアシスタントが読む短いガイドです。Homelab は、Agent Skills を読み込むアプリ向けに skills/ フォルダーでスキルを提供し、それ以外の各クライアント向けには、それぞれを MCP プロンプトとして提供します。

Homelab 向けに作成

スキル	内容
getting-started	有効なモジュール、各モジュールに必要な設定、最初に行う確認、承認の仕組み
expose-a-service-safely	1 つのコンテナーを公開用の名前で公開する方法：ドライラン、承認、各ホップの診断、外部からの確認
homelab-health-check	モジュール、コンテナー、証明書、モニター、DNS フィルタリングの読み取り専用チェック
homelab-troubleshooting	サービスの障害原因を、一度に 1 つの仮説ずつ調査
fix-and-deploy	元の症状に照らした修正の検証、デプロイ、稼働中のターゲットの確認
containers	Docker コンテナーのステータス、ログ、再起動、統計情報、イメージ
runbook	稼働中のツールから取得した情報を使った、サービスごとの運用手順書
diagram	説明から編集可能な draw.io ファイルを作成
network-diagram	サービス、Docker ネットワーク、プロキシ、DNS 経路を示す draw.io マップ

サードパーティ製（各自のライセンスに基づく）

スキル	作者	ライセンス
systematic-debugging	Jesse Vincent、obra/superpowers	MIT
cloudflare、cloudflare-one	Cloudflare、cloudflare/skills	Apache-2.0
dashmotion	csthink、csthink/dashmotion	MIT
architecture-diagram	Cocoon-AI、architecture-diagram-generator	MIT

各サードパーティ製スキルには、それぞれのライセンスファイルが含まれています。固定された上流コミットについては、CREDITS.md を参照してください。

こちらをお試しください

1. Call homelab_modules and tell me which modules are on and which settings are missing.
2. Show every container that is restarting or unhealthy, with its last ten log lines.
3. Dry-run expose_service for wiki-app on wiki.example.com, port 8080, and show me the plan.
4. Diagnose wiki.example.com and fix the first failing hop.
5. Run the homelab health check and give me one table.

安全性

• 読み取り専用ツールは一切変更を加えません。 アシスタントは自由に一覧表示、確認、検索、ログの読み取りができます。diagnose_service は読み取り専用の呼び出しのみを行います。
• 変更にはすべて承認が必要です。 アシスタントが変更を依頼すると、Homelab は MCP クライアントを通じて直接確認し（MCP elicitation）、変更内容を正確に表示します。ドメイン、対象、コンテナ、DNS レコードが示されます。アシスタントがあなたの代わりに回答することはできません。アシスタントが設定した引数は、承認として扱われません。
• すべての判断が記録されます。 承認、却下、拒否のそれぞれが、ローカルの承認ログに記録されます。デフォルトのパスは ~/.local/state/homelab/approvals.jsonl です。別のパスを選ぶには HOMELAB_APPROVAL_LOG を設定してください。
• ドライランで計画を確認できます。 すべての変更ツールは dry_run=true を受け付けます。変更予定の内容を表示し、実際には何も変更しません。
• 信頼できるものだけを事前承認してください。 HOMELAB_<MODULE>_ALLOW_WRITES=true を設定すると、アシスタントはそのモジュール内で確認を求めずに変更できます。自動化してもよいモジュールに使用し、それ以外では無効のままにしてください。
• 質問できないクライアントもあります。 その場合、変更を実行すると approval_unavailable が返され、事前承認する設定、または変更せずにおく設定がメッセージに示されます。
• 読み取り専用モード。 HOMELAB_READ_ONLY=true を設定すると、事前承認済みの変更も含め、すべての変更が拒否されます。
• シークレットが応答に含まれることはありません。 トークン、パスワード、キーは環境変数、ファイル、または設定ファイルから読み込まれます。homelab_modules は設定済みかどうかだけを報告し、値は報告しません。
• Docker ソケットへのアクセス権限は、ホスト上の root 権限に相当します。 確認だけが必要な場合はソケットを読み取り専用でマウントし、ソケットをまったくマウントしたくない場合は Portainer を使用してください。
• トンネルと SSO の変更はパブリックインターネットに影響します。 承認する前に、各 tunnel_routes および sso_applications の計画を確認してください。
• Homelab は、設定したサービスのみを呼び出します。それ以外には何も送信せず、データも保持しません。

シークレットの一覧、承認ログ、報告手順については、SECURITY.md を参照してください。

セキュリティカード
ネットワーク	設定したサービスのみです。Nginx Proxy Manager、Docker エンジンまたは Portainer、api.cloudflare.com（DNS と Tunnel）、および設定した Uptime Kuma、AdGuard Home、Authentik、Home Assistant のアドレスが対象です。diagnose_service は、アップストリームおよびパブリックドメインへの TCP 接続と TLS 接続も確立します。テレメトリーはありません。
ファイル	設定ファイル（/.config/homelab/config.toml）を読み込みます。ローカルの承認ログ（/.local/state/homelab/approvals.jsonl）を 1 つ書き込みます。このログがマシンの外部に送信されることはありません。
シークレット	API キー、トークン、パスワードは環境変数または設定ファイルから読み込まれます。ツールの引数として渡されることも、モデルに返されることもありません。
読み取り専用ツール	7 個：docker_inventory、dns_zones、service_status、infrastructure_overview、diagnose_service、homelab_modules、homelab_health
承認が必要	proxy_hosts、proxy_redirections、proxy_certificates、proxy_access_lists、docker_containers、docker_images、dns_records、expose_service、teardown_service：アプリで変更ごとに承認するか、設定でモジュールを事前承認してください。AI があなたの代わりに承認することはできません。
起動時のコスト	約 10,200 トークン（16 個のツール、14 個のスキルプロンプト）
変更	ツールの説明はハッシュ（tool-manifest.lock.json）によって固定されています。説明が通知されないまま変更されると、CI は失敗します。

開発

uv venv -p 3.11 .venv && uv pip install -e '.[dev]'
.venv/bin/pytest -q
python3 scripts/scan_identifiers.py --patterns <file> .

テストが実際のネットワークや Docker エンジンに接続することはありません。HTTP には httpx.MockTransport を使用し、Docker クライアントにはフェイクを使用します。

ライセンス

MIT。LICENSE を参照してください。サードパーティのスキルはそれぞれ独自のライセンスに従います。CREDITS.md を参照してください。

---

Seaynic Labs 制作

発行元	Seaynic Labs
ソース	github.com/seayniclabs/homelab-infra-mcp
脆弱性の報告	GitHub の非公開脆弱性報告（SECURITY.md を参照）
クレジット	CREDITS.md