ha-mcp — ClaudeやChatGPTからHome Assistantを操作・設定するMCPサーバー

概要

ha-mcpは、オープンソースのスマートホーム基盤である「Home Assistant」を、ClaudeやChatGPTといったAIアシスタントから設定・自動化できるようにするModel Context Protocol（MCP）サーバーです。

近年策定されたMCP（Model Context Protocol）に準拠しており、LLMを備えたクライアントアプリケーションからHome Assistantの各種エンティティや設定へアクセスするためのインターフェースを提供します。自然言語を用いて家電の制御指示を出したり、複雑なオートメーションの設定をAIと対話しながら行ったりしたい開発者やスマートホーム愛好家に向いています。Pythonで実装されており、Home Assistantのカスタム統合（Custom Component）やアドオン（App）、Dockerコンテナなど、環境に応じた複数の形態で動作させることができます。

主な特徴

多様な実行方式に対応: Home Assistant内で直接動作するインプロセス統合（カスタムコンポーネント）をはじめ、Home Assistant OS向けのアドオン（App）、Dockerコンテナ、uvx/PyPI経由での実行など、環境に合わせた柔軟なデプロイが可能です。
Model Context Protocol（MCP）準拠: Claude Desktop、Claude.ai、ChatGPTなど、MCPに対応したAIクライアントと直接連携して動作します。
インプロセスサーバーによる広範な互換性: 推奨構成であるインプロセス統合を利用する場合、Home Assistant OS、Supervised、Container、Coreの全インストールタイプで同等の機能が動作します。
Home Assistant管理パネルの提供: サーバー起動中、Home Assistantのサイドバーに管理者向けの「HA-MCP」パネルが追加され、利用するツールの一覧、フィーチャーフラグ、バックアップ、テーマなどをGUIから管理できます。
複数のアクセス経路と認証オプション: ローカルネットワーク経由での直接接続に加え、Nabu Casaやリバースプロキシを介したWebhookによるリモートアクセスに対応しています。認証方式もシークレットURL方式、Home Assistantアカウント認証、外部IdPを用いたOIDC認証などが選択可能です。
ファイルおよびYAML編集ツールのオプトイン提供: オプション機能として、Home Assistantの設定ファイルやYAMLを直接編集するためのツール群がフィーチャーフラグ形式で用意されています（デフォルトは無効）。

使い方

READMEでは、Home Assistant 2026.8.0以降を対象とした「HA-MCP integration（インプロセス統合）」が推奨構成として案内されています。

1. 統合のインストール

Home Assistant 2026.11以降の場合: 「設定」→「マーケットプレイス（Marketplace）」を開き、「HA-MCP」を検索して「インストール」を選択します。
Home Assistant 2026.8〜2026.10の場合: HACSを開き、「HA-MCP」を検索してダウンロードします。

インストール完了後、Home Assistantを再起動します。

2. アカウントとアクセストークンの準備

サーバーがHome Assistant上で操作を行うための管理者アカウントを決定します。

自身の既存アカウントで長期アクセストークン（Long-lived access token）を発行するか、または
セキュリティ上の推奨策として、「設定」→「担当者」から「ローカルアクセスのみ」「管理者」を有効にしたHA-MCP専用の人物アカウントを新規作成します。

3. 統合の追加と接続設定

「設定」→「デバイスとサービス」→「統合を追加」を開きます。
「HA-MCP」を検索し、「HA-MCP Server」を選択します。
事前に用意したトークンを貼り付けるか、作成した専用アカウントのユーザー名とパスワードを入力します。
クライアントの接続方法（リモートアクセスまたはローカルネットワークアクセス）を選択し、送信します。
統合の「構成」画面を開き、表示された接続用URL（Webhook URLまたはローカル接続用URL）をコピーします。

4. AIクライアントへの登録

コピーしたURLを、Claude DesktopやChatGPTなどのMCPクライアント設定へ貼り付けて接続します。

なお、Home Assistant OSやSupervised環境を利用している場合は、アクセストークンの手動管理が不要なアドオン（App）形式でのセットアップも選択できます。

技術的なポイント

実装とトランスポートアーキテクチャ: ha-mcpはPythonで開発されており、MCPの通信方式としてHTTP（Streamable HTTP）を主軸に設計されています。stdioトランスポートも存在しますが、接続上の課題が報告されているため、本番運用ではHTTPベースのインプロセス統合やアドオンの利用が推奨されています。
Home Assistant内部への統合: カスタムコンポーネントとして動作するインプロセス型では、Home Assistantのプロセス内で直接サーバーが駆動するため、余分なコンテナや外部プロセスの起動オーバーヘッドを削減しつつ、コアAPIへの高速なやり取りを実現しています。
Webhookとリバースプロキシ連携: リモートアクセス時にはHome AssistantネイティブのWebhookエンドポイント（/api/webhook/）を活用するため、Nabu Casa Cloudや既存のリバースプロキシ構成をそのまま利用して外部のAIクライアント（Web版ClaudeやChatGPTなど）と安全に通信できます。
安全性を考慮した権限制御: 管理者トークンを用いた全体制御だけでなく、YAMLやファイル操作といった危険度の高い操作系ツール（HA-MCP File & YAML Tools）は個別のエントリーかつフィーチャーフラグとして切り離されており、誤操作によるシステム破損リスクを低減する設計となっています。

注意点

必須環境: インプロセス統合を利用するには、Home Assistant 2026.8.0以降が必要です。
接続方式の重複設定: 同一クライアントに対して複数の接続方式（例: アドオン経由のURLと、ローカルのuvxコマンドによるstdio接続の両方）を同時に登録すると接続ハングの原因となるため、クライアントごとに必ず1つの接続方式に絞って設定する必要があります。
stdioトランスポートの制限: ローカルstdio方式には既知のトランスポート問題（リポジトリのIssue #1713など）が存在するため、デモやテスト目的以外ではHTTPベースの構成が推奨されています。
仕様変更（Breaking Change）: バージョン7.3.0において、ha_config_set_yamlツールがベータ機能へ移行されたことが明記されています。アップデート時には過去のツール呼び出し定義に注意が必要です。
ライセンス: 本プロジェクトはMITライセンスのもとで公開されています。