Home Assistant MCP

OAuth で保護された Model Context Protocol (MCP) サーバーで、ChatGPT、Codex、その他の MCP クライアントを Home Assistant に安全に接続します。

このプロジェクトは、ディスカバリー、ダッシュボード、スケジュール、気候、エネルギー、メディア、掃除、灌漑、自動化、診断、および慎重に制限されたデバイス制御のための 99 個の型付きツールを公開します。Home Assistant の API を非公開に保ち、汎用シェル、ログリーダー、ネットワークスキャナー、無制限のサービスプロキシになることを意図的に回避します。

[!IMPORTANT] これは、自己ホスト型 Home Assistant インストール向けのセキュリティに配慮したリファレンス実装です。セキュリティモデルを読み、すべてのサンプル値を置き換え、実際のホームに接続する前に許可リストを確認してください。

ハイライト

• 型付き Home Assistant アクセス: エンティティ、デバイス、エリア、履歴、天気、カレンダー、スケジュール、統計、統合、ダッシュボード、To-Do リスト、自動化、バックアップ、システムヘルス。

• 制限付き書き込み: 気候、照明、シーン、メディアプレーヤー、掃除機、カバー、ロック、サイレン、通知、ダッシュボード、スケジュール、カレンダー、To-Do 項目、自動化は、検証済みの入力と狭いサービス許可リストを使用します。

• スプリンクラーサポート: ライブコントローラーステータス、ゾーンメタデータ、設定、散水履歴、テレメトリ更新、ゾーンまたはシーケンスの開始、および冪等な停止操作。

• エネルギーと SolarEdge: 発電量、モジュール比較、電力フロー、エネルギー内訳、ストレージ概要、テレメトリ、アラート、およびオプションの Home Assistant ブリッジ統合。

• 永続的な機能同期: Home Assistant の現在のサービスレジストリを、レビュー済みのリリースベースラインと 5 分ごとに比較し、動的に新しい書き込みを公開せずにドリフトを報告します。

• サニタイズされた診断: オプションの固定ルート、ホスト/ランタイム、障害、固定サブネット LAN の証拠。厳密な制限があり、生のアドレス、任意のターゲット、コマンド、デバイス制御はありません。

• OAuth ネイティブのリモートアクセス: 認可コードフローと S256 PKCE、動的クライアント登録、スコープ付きアクセストークン、MCP リソースメタデータ。

バージョン 2.6.1 は現在 99 個のツールを宣伝しています。リリース履歴は CHANGELOG.md を参照してください。

アーキテクチャ

flowchart LR
    Client[ChatGPT, Codex, or MCP client]
    Edge[HTTPS edge<br/>Cloudflare Worker, tunnel, or reverse proxy]
    MCP[Home Assistant MCP<br/>OAuth + typed tools]
    HA[Private Home Assistant API]
    Data[(OAuth, audit, and<br/>capability-sync state)]
    Collector[Optional root-owned<br/>diagnostics collector]
    Export[Sanitized read-only export]

    Client -->|HTTPS + OAuth/PKCE| Edge
    Edge -->|loopback or shared-secret origin| MCP
    MCP -->|long-lived service token| HA
    MCP --> Data
    Collector --> Export --> MCP

リファレンスデプロイメントは MCP サービスを 127.0.0.1:8000 にバインドします。公開されるのは HTTPS エッジのみです。Home Assistant はホストに対してローカルに保つことも、プライベートネットワーク経由で到達可能にすることもできます。

ツールサーフェス

リスクの高いアクションは破壊的として注釈され、明示的な確認引数が必要です。正確なレジストリが権威です。デプロイ後に認証済み MCP クライアントから検査してください。

要件

• MCP ホストから到達可能な Home Assistant。

• 専用の Home Assistant 長期アクセストークン。可能な場合は別のサービス ID を使用してください。

• Python 3.12 以降と開発およびテスト用の uv。

• リファレンスコンテナデプロイメント用の Docker と Compose。

• リモート MCP クライアント用の公開 HTTPS URL。

• ループバック経由で MCP に到達するか、設定されたオリジン共有シークレットを注入する HTTPS エッジ。同梱の Caddy と Cloudflare の例は、これら 2 つのパターンを示しています。

• オプションのホスト診断コレクターを使用する場合のみ、Linux と systemd。

同梱の Compose ファイルは、普遍的なワンコマンドインストーラーではなく、本番リファレンスです。ホストネットワーキング、/opt/homeassistant/config の既存の Home Assistant 設定、および /var/lib/ha-host-diagnostics/export にインストールされた診断エクスポートを想定しています。Home Assistant API や Docker ソケットを公開せずに、これらのマウントをインストールに合わせて調整してください。

開発用クイックスタート

リポジトリをクローンし、ロックされた依存関係をインストールします:

git clone https://github.com/shogun301/ha-chatgpt-mcp.git
cd ha-chatgpt-mcp
uv sync --frozen

テストスイートと公開ソース監査は本番資格情報を必要としません:

uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

サービスを実行するには、.env.example を無視された .env にコピーし、すべてのサンプルドメインとエンティティ ID を置き換え、以下で説明する必要なランタイムパスとシークレットファイルを提供します。アプリケーションは .env を自動的にロードしません。プロセスマネージャーで変数をエクスポートするか、uvicorn --env-file .env を使用するか、Docker Compose にロードさせてください。

環境を設定した後のローカルプロセス用:

uv run uvicorn app.server:app --host 127.0.0.1 --port 8000 --no-proxy-headers

マウントとオプションの統合を調整した後のリファレンスコンテナデプロイメント用:

docker compose build --pull
docker compose up -d
curl --fail http://127.0.0.1:8000/healthz

Uvicorn を公開インターフェースに直接バインドしないでください。

設定

コア設定

.env.example のエンティティ固有の変数は、汎用ツールサーフェスを 1 つのデプロイメントのプレゼンス、通知、掃除機、スプリンクラー、サーモスタット、スケジュールエンティティにマッピングします。実際のエンティティ ID は Git ではなくローカル設定に保持してください。

必要なシークレットファイル

サーバーは環境値ではなくファイルからシークレットを読み取ります:

暗号的に安全なジェネレーターでランダムな値を生成します。Argon2 パスワードハッシュは、パスワードをシェル履歴に置かずに生成できます:

uv run python -c "from argon2 import PasswordHasher; from getpass import getpass; print(PasswordHasher().hash(getpass('OAuth password: ')))"
uv run python -c "import secrets; print(secrets.token_urlsafe(48))"

出力を所有者のみがアクセスできる別々のファイルに保存します。secrets/、.env、トークン、パスワード、ハッシュ、プライベートドメイン、エンティティインベントリ、スケジュール、ネットワークトポロジをコミットしないでください。

オプションの SolarEdge 設定

SolarEdge サポートは、オプションのクライアント資格情報、暗号化されたトークンストア、ブリッジシークレット、リダイレクト URI、および保護されたポータルフォールバック資格情報を使用します。SolarEdge を使用しない場合は、対応する SOLAREDGE_*_FILE 変数を省略してください。リファレンス Compose ファイルはこれらのパスを設定するため、ファイルを提供するか、ローカルオーバーライドでそれらのエントリを削除してください。

OAuth スコープ

• mcp:read は読み取りツールを許可します。

• mcp:write はレビュー済みの書き込みサーフェスを許可し、現在の最強の互換性付与も満たします。

• mcp:diagnostics は mcp:read と一緒に、デバイス書き込みを許可せずに特権的な読み取り専用のホストおよび LAN 診断を許可します。

クライアントを https://your-mcp-host.example/mcp に接続します。サーバーは、同じオリジンで OAuth 認可サーバー、保護リソース、OpenID 設定、動的クライアント登録メタデータを公開します。

エッジオプション

アプリケーションは、非ループバックリクエストが設定されたオリジン共有シークレットを運ぶことを要求します。2 つの例が含まれています:

• cloudflare/ には、狭い Cloudflare Worker プロキシが含まれています。MCP、OAuth、ヘルス、SolarEdge コールバックパスのみを転送し、1 MiB のリクエスト制限を適用し、オリジンシークレットを追加し、不要なヘッダーを削除します。

• Caddyfile は、ループバック MCP リスナーへの同一ホスト HTTPS リバースプロキシを提供します。

同梱の cloudflared サービスはトークンファイルを使用し、ループバックのみでメトリクスを公開します。すべてのサンプルルートを置き換え、MCP オリジン、Home Assistant API、メトリクスリスナーを公開ネットワークから遠ざけてください。

機能同期

Home Assistant 統合は、このプロジェクトとは独立してサービスを追加または削除できます。したがって、サーバーは Home Assistant のサービスレジストリを 5 分ごとにポーリングし、リリースにバインドされたベースラインを /data/ha-capability-sync.json に永続化します。

get_capability_sync_status は、再起動をまたいで追加または削除されたサービスとフィールドスキーマの変更を報告します。モニターは意図的に観察専用です。サービスを呼び出すことはなく、レビューされていない Home Assistant サービスを新しい MCP 書き込みツールに変えることもありません。新しい機能は、レビューされ、型付きツールとして実装され、テストされ、Git を通じてリリースされるべきです。

オプションのホストおよび LAN 診断

collector/ の下の systemd コレクターにはリスナーがなく、呼び出し元が選択したコマンド、パス、コンテナ、ログ式、URL を受け入れません。固定ディレクトリに制限付きのサニタイズされたスナップショットと台帳を公開します。MCP コンテナは、そのディレクトリのみを読み取り専用マウントとして受け取ります。Docker ソケット、ホストジャーナル、procfs、sysfs、systemd 制御は決して受け取りません。

LAN ツールは、設定された 1 つの /24 内でのみ動作し、不透明なノード ID を返し、閉じた TCP サービス許可リストを使用し、アプリケーションペイロードを送信せず、生のアドレスを省略します。任意のネットワークをスキャンしたり、デバイスを制御したりすることはできません。

完全なデータモデル、保持制限、デプロイメント、検証、インシデント、ロールバック手順については、docs/operations.md と collector/README.md を参照してください。

セキュリティモデル

このサーバーは、Home Assistant APIよりも意図的に範囲を絞っています：

• シェル実行、任意のWebSocketパススルー、任意のファイル、生のログ、Docker管理、サービス再起動、シャットダウン、資格情報の取得、カメラ映像、アラームの解除は行いません。

• 一般的なHome Assistantサービス呼び出しは、ドメインとサービスごとに許可リストで制御され、専用の型付きツールが優先されます。

• 入力はスキーマ検証され、結果サイズは制限され、機密性の高い診断フィールドは再帰的に編集されます。

• 破壊的または物理的な操作には、明示的な注釈と確認ゲートが使用されます。

• 監査記録には、ツール名と制限付きメタデータが含まれ、資格情報や返された診断証跡は含まれません。

• コンテナは非特権ユーザーとして読み取り専用ファイルシステムで実行され、すべてのLinuxケーパビリティが削除され、no-new-privilegesが有効になっています。

• 公開リリース時の監査では、公開前に現在のツリーとGit履歴の両方がスキャンされます。

サーモスタット、照明、ロック、掃除機、スプリンクラー、カメラ、スピーカー、テレビ、バックアップ、通知、その他の物理的な副作用を接続テストとして使用しないでください。

脆弱性の報告および機密性の高いデプロイ情報の取り扱いについては、SECURITY.mdをお読みください。

デプロイと検証

scripts/deploy-production.ps1にあるPowerShellデプロイスクリプトは、AWS Lightsailを前提とした参考実装です。明示的なAWSプロファイル、リージョン、インスタンス、フロントエンドURL、MCP URLのパラメータを必要とし、レビュー済みソースをパッケージ化し、バックアップを作成し、コレクターとコンテナをデプロイし、検証を実行し、ロールバックをサポートします。別のホストに適用する前に、慎重にレビューしてください。

公開プッシュまたは本番リリースの前に：

uv sync --frozen
uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

次に、デバイスの状態を変更せずに検証します：

1. /healthz がローカルおよびパブリックエッジ経由で成功すること。

2. 未認証および無効なトークンのMCPリクエストが拒否されること。

3. 認証済みディスカバリーが期待されるバージョンとツール数を報告すること。

4. 読み取り専用の概要、ケイパビリティ同期、ルート、統合チェックが成功すること。

5. 公開Gitコミット、デプロイされたアーティファクト、報告されたサービスバージョンが同一であること。

本番手順とロールバックゲートの詳細は、docs/operations.mdに記載されています。

コントリビューション

プロジェクトの境界を定めたセキュリティモデルを維持する場合、Issueとプルリクエストを歓迎します。

新しいツールの場合：

1. 汎用パススルーよりも、狭い型付き操作を優先します。

2. 読み取り専用、冪等、書き込み、または破壊的の注釈を正確に定義します。

3. エンティティドメイン、列挙型、長さ、時間枠、結果制限を検証します。

4. 重大な物理的または管理操作には明示的な確認を要求します。

5. 認可、ネガティブパス、編集、回帰テストを追加します。

6. ケイパビリティドキュメントを更新し、公開履歴監査を実行します。

実際の家庭の設定、プライベートURL、資格情報、ログ、トークン、スケジュール、トポロジー、プロバイダー応答をIssue、フィクスチャ、スクリーンショット、コミット、またはプルリクエストに含めないでください。

ライセンス

現在、オープンソースライセンスは含まれていません。公開されているからといって、コードのコピー、変更、再配布の許可が与えられるわけではありません。リポジトリ所有者は、再利用や再配布を受け入れる前に明示的なライセンスを追加する必要があります。

参考

• Model Context Protocol

• OpenAI: Build an MCP server

• OpenAI: Authenticate users

• Cloudflare Tunnel monitoring

• Cloudflare Tunnel metrics