homeassistant-ai/ha-mcp

📚 ha‑mcp とは何ですか？

ha‑mcp（Home Assistant Model Context Protocol サーバー）は、大規模言語モデルアシスタント（Claude、ChatGPT、Gemini など）が Home Assistant インスタンスとやり取りできるようにする非公式だが完全機能のサーバーです。Model Context Protocol（MCP）を実装しており、AIクライアントが以下の操作を実行できます：

任意のエンティティ（照明、センサー、カメラなど）の状態を照会。
Home Assistant の任意のサービスを通じてデバイスを制御。
自動化、スクリプト、ダッシュボード、ヘルパー、ゾーン、グループ、ブループリント、HACS アドオン、バックアップなどを作成・編集・デバッグ。
ログ、履歴、自動化トレースを読み取り、AIが問題をトラブルシューティングするのを支援。
セーフティ機能（読み取り専用モード、ツールごとの権限、自動編集バックアップ）を切り替え、AIが変更できる範囲を制御可能に。

要するに、会話型AIを、単に電気をつける・消す以上の、スマートホーム構成を構築・維持できる完全なHome Assistant管理者に変えるのです。

🚀 どうやって実行する？

ha‑mcp は 4通りの方法でインストールでき、いずれもAIクライアントが接続するための1つのURLを公開します。

方法	実行場所	一般的な用途
HA‑MCP カスタムコンポーネント（推奨）	Home Assistant 内部でカスタム統合（HACS経由でインストール）	OS、Supervised、Container、Core すべてのHome Assistantインストールタイプで動作。追加トークン不要。
Home Assistant アプリ / アドオン	Home Assistant OS / Supervised 上の別プロセスとして	オンラインアクセス用の組み込みWebhookを活用したい場合に適しています。
Docker / PyPI / uvx HTTPサーバー	Home Assistant 外部（任意のホスト）	アドオンが使えないContainerまたはCoreインストール、または別のマシンにサーバーをホストしたい場合に有用。
ローカル stdio	ラップトップ/デスクトップ上で直接実行（プロダクションには非推奨）	すぐにデモや試行錯誤を行う場合に便利。ただし既知の通信バグあり。

すべての方法で、秘密のWebhook URL（またはローカルポート）が生成され、AIクライアントのMCP設定に貼り付ける必要があります。

🔧 クイックスタート（カスタムコンポーネント）

HACS経由で統合を追加 – READMEのバッジを使用するか、リポジトリ https://github.com/homeassistant-ai/ha-mcp-integration をカスタムリポジトリとして追加。
Home Assistant を再起動。
設定 → デバイスとサービス → 統合の追加 で、HA‑MCP カスタムコンポーネントを検索し、HA‑MCP Server エントリを追加。
サーバー起動後、設定画面を開く。Webhook URL（例：https://my‑ha.duckdns.org/api/webhook/abcd1234）が表示され、Home Assistantログにも表示されます。
このURLをAIクライアントのMCP設定に貼り付け – これでAIアシスタントがHome Assistantとやり取りできるようになります。

この統合は、ツール、機能フラグ、バックアップ、テーマの管理ができるサイドバーパネルも追加し、オプションのWebhook認証（ha_auth）も有効化可能です。

🛠️ AIは実際に何ができる？

ha‑mcp は 87の「ツール」 を提供しており、機能別にグループ化されています。READMEで紹介されている代表的な操作は以下の通りです：

カテゴリ	例のツール
制御	`ha_call_service`, `ha_bulk_control` – デバイスのオン/オフ、気候調整など
自動化＆スクリプト	`ha_config_get_automation`, `ha_config_set_automation`, `ha_config_get_script`, `ha_config_set_script` – 自動化やスクリプトの作成・編集
ダッシュボード／UI	`ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_get_dashboard_screenshot` – カードの追加、Lovelaceレイアウトの編集
ファイル＆YAML (ベータ)	`ha_read_file`, `ha_write_file`, `ha_config_get_yaml`, `ha_config_set_yaml` – 設定ファイルの直接編集
システム＆メンテナンス	`ha_manage_backup`, `ha_manage_updates`, `ha_restart`, `ha_reload_core` – バックアップ/リストア、Home Assistantの更新、サービス再起動
デバッグ＆監視	`ha_get_history`, `ha_get_logs`, `ha_get_automation_traces` – ログの取得、エンティティ履歴の表示、失敗した自動化のデバッグ
セキュリティ	`ha_manage_security_policy`, `Read Only Mode toggle` – AIが変更できる範囲を制限

たとえば「日没時にポーチライトを点灯する自動化を作成して」という質問に対して、AIは裏で適切な ha_config_set_automation ツールを呼び出し、YAMLを書き込み、設定を再読み込みします。

🌐 リモートアクセスオプション

組み込みWebhook（カスタムコンポーネントで使用） – Nabu Casa、Cloudflare Tunnel、または任意のリバースプロキシと連携可能。
Webhookプロキシアプリ – アドオン方法用。既存のHome Assistant Webhook経由でMCPトラフィックを転送。
OpenAI Tunnel – コミュニティメンテナンスのトンネル。ローカルホストサーバーにChatGPT風の接続を可能にし、パブリックURLを公開せずに済む。
OIDC認証 – 外部IDプロバイダー（Keycloak、Auth0など）でWebhookを保護するオプションモード。

📦 デモ＆セットアップウィザード

リポジトリには、macOS、Linux、Windows用のワンコマンドデモスクリプトが用意されており、ホストされたデモ用Home Assistantに接続された一時的な stdio サーバーを起動できます。スクリプト実行後、Claude、ChatGPT、または任意のMCP対応クライアントに「私のHome Assistantが見えますか？」と尋ねて、統合の動作を確認できます。

また、ウェブベースのセットアップウィザード（https://homeassistant-ai.github.io/ha-mcp/setup/）では、すべての対応クライアント（Claude Code、Gemini CLI、ChatGPT、VS Code、Cursorなど）に特化した設定を自動生成します。

🆚 Home Assistantの組み込みMCPサーバーとの違い

機能	組み込みMCPサーバー	ha‑mcp
デバイス制御・状態照会	✅（Assistに公開されたエンティティのみ）	✅（すべてのエンティティ）
自動化、スクリプト、シーンの編集	❌	✅
ダッシュボード／Lovelace UIの編集	❌	✅
ログ、履歴、自動化トレースのアクセス	❌	✅
ヘルパー、エリア、ゾーン、グループ、ラベルの管理	❌	✅
バックアップ/リストア、アプリ管理、HACS、デバイスレジストリ	❌	✅

シンプルな音声コマンド用途には組み込みサーバーを使用し、ha‑mcp はAIが全体のHome Assistant設定を構成・維持したい場合に最適です。

📚 もっと学びたい方へ

ドキュメントサイト – https://homeassistant-ai.github.io/ha-mcp/
セットアップウィザード – https://homeassistant-ai.github.io/ha-mcp/setup/
FAQ & トラブルシューティング – https://homeassistant-ai.github.io/ha-mcp/faq/
GitHubリポジトリ – https://github.com/homeassistant-ai/ha-mcp（イシュー、貢献ガイド、リリースノート）

TL;DR

ha‑mcp は、大規模言語モデルアシスタントとHome Assistantを橋渡しする本格的でプロダクション対応のサーバーであり、AIにHome Assistant全体の設定に対する完全な読み書きアクセスを提供します。HA‑MCPカスタムコンポーネント（最も簡単な方法）でインストールし、生成されたWebhook URLを取得して、任意のMCP対応AIクライアントに接続すれば、自然言語で自動化の作成、ダッシュボードの編集、問題のデバッグなどを可能にします。