ha-mcpをHome Assistantに入れる前に読む、87ツールのMCPサーバー

このサーバーが埋めるのは、自然言語とHome AssistantのAPIのあいだの隙間

Home Assistantには長らく、音声アシスタントやチャットからエンティティを操作する手段があった。ただしその多くは、あらかじめ定義したインテントや定型文に対応する範囲に限られる。ha-mcpが狙うのはその外側で、READMEでは「control smart home devices, query states, execute services and manage your automations」と説明されている。つまり状態の照会だけでなく、サービス呼び出しとオートメーションの管理までをツールとして公開する。対象読者は、Home Assistantをすでに運用していて、Claude DesktopやClaude.ai、ChatGPTなどのMCP対応クライアントから自宅の状態を触りたい人である。逆に、Home Assistantをこれから始める人が最初に入れるものではない。87個のツールをAIに渡すということは、それだけの操作権限を渡すということで、既存のエンティティ設計と権限管理が固まっている環境のほうが扱いやすい。

in-process方式が推奨される理由と、そこで失うもの

READMEが第一に挙げるのはHA-MCP Custom Componentで、HACSからインストールし、Home Assistantのプロセス内でサーバーを動かす。Home Assistant OS、Supervised、Container、Coreのいずれでも動作し、機能差がないとされる。アクセストークンを管理しなくてよい点が最大の利点で、認証情報を別途保管してローテーションする運用から解放される。代わりに受け入れる制約が2つある。1つは、このin-processサーバーが単体で完結したインストールであり、add-on、Docker、uvx/PyPI（stdio）の各方式を置き換えるという点。READMEは「Run only one; do not run the in-process server alongside another install」と明記しており、併用は想定されていない。もう1つは、ファイルとYAMLの編集ツールを使う場合だけ、2つ目のエントリ種別であるHA-MCP File & YAML Toolsを追加する必要があること。これはデフォルトで無効なフィーチャーフラグで、後から追加できる。

セットアップはHACSのバッジから始まり、Configure画面のURLで終わる

手順はREADMEに具体的に書かれている。HACSでIntegrations → ⋮ → Custom repositoriesを開き、https://github.com/homeassistant-ai/ha-mcp-integration をカテゴリIntegrationで追加してDownloadする。次にHome Assistantを再起動し、Settings → Devices & Services → Add IntegrationでHA-MCP Custom Componentを検索し、HA-MCP Serverを選んでSubmitする。この時点でサーバーが起動する。接続URLはエントリのConfigure画面（Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure）に表示され、Home Assistantのログにも出力される。通知でもサーバー起動と参照先が案内される。リモートクライアント向けには https://<your-ha-domain>/api/webhook/<webhook-id> 形式のWebhook URLが渡され、ローカルでは http://<ha-host>:8123/api/webhook/<webhook-id> になる。同一ネットワーク上のクライアントは http://<ha-ip>:9584/private_<random> で直接到達できる。HACSを使わない場合はcustom_components/ha_mcp_tools/をconfig/custom_components/にコピーして再起動する。

Webhookの扱いと、ローカル限定に切り替える設定

リモートアクセスはデフォルトでWebhook経由になり、URLの秘密部分がそのまま資格情報として機能する。これが気になる場合の選択肢が2つ用意されている。1つはエントリのオプションでRemote access via webhookをオフにする方法で、READMEによればWebhookは一切登録されず、直接ポートとサイドバーパネルは動作し続ける。もう1つはWebhook authenticationをha_authに設定し、秘密URLの代わりにHome Assistantアカウントのサインインを要求する方法である。ここは設計上のトレードオフがはっきり出ている。URLを貼るだけで繋がる手軽さは、URLが漏れれば誰でも繋がるという意味でもある。ha_authを選べばそのリスクは下がるが、クライアント側でサインインの手間が増える。なお、サーバー稼働中は管理者限定のHA-MCPパネルがサイドバーに現れ、ツール、フィーチャーフラグ、バックアップ、テーマを管理できる。パネルが見えないアカウントでは管理操作ができない点は把握しておきたい。

代替手段としてのadd-on方式、選び分けは導入環境で決まる

READMEはHome Assistant app（旧add-on）方式を「close second」と位置づける。Home Assistant OSとSupervisedでは動くが、ContainerとCoreでは使えない。in-process方式との違いは実行場所で、add-onはHome Assistant本体の外側でサーバーが動く。そのためアクセストークン管理が不要な点は共通しながら、本体の再起動とサーバーの再起動を切り離せる。ログの確認もLogsタブから行う。READMEの手順では、リポジトリ https://github.com/homeassistant-ai/ha-mcp を追加し、Settings → Apps → Install appからHome Assistant MCP ServerをインストールしてStartを押す。Home Assistant 2026.2でAdd-onsがAppsに改称されたため、それ以前のバージョンではAdd-on storeと読み替える必要がある。Docker/PyPIとstdioはさらに別系統で、これらはHome Assistantの外で完結する。どの方式も「Configure exactly one install method per client」という原則の下にある。

87ツールという粒度がもたらす運用上の負担

ツール数はREADMEのバッジで87と示されている。この粒度は利点であると同時に、AIクライアント側のコンテキストを消費する。サイドバーのHA-MCPパネルでツールを管理できるとされているが、どのツールを外すべきかの判断基準はREADMEには書かれていない。また、破壊的な操作が含まれる可能性についても、提供された資料からは確認できない。ファイルとYAMLの編集ツールがデフォルト無効のフィーチャーフラグになっている点は、少なくとも設定ファイルを書き換える操作が通常の操作と別扱いされていることを示す。ここは導入時に自分で線を引く必要がある領域で、ドキュメントが薄いと感じる部分でもある。リリースはv8.4.3.dev2608のようなdevビルドが短時間に複数出ており、活発に動いている反面、追従コストを見込んでおくべきリポジトリだと言える。

MITライセンスと、非公式であることの意味

ライセンスはMITで、リポジトリにLICENSE.mdが置かれている。MITは商用利用を含めて寛容な条件だが、無保証である点は他のMITプロジェクトと変わらない。ここで法的助言はできないが、ライセンス条項そのものは自分で確認する必要がある。もう1つ見落とせないのは、このプロジェクトが「Unofficial」を自称していることだ。Home Assistantの公式アドオンでも公式インテグレーションでもない。Home Assistant本体のバージョンアップで動かなくなる可能性は、公式コンポーネントより高いと考えるのが自然である。Home Assistant 2026.2のApps改称のような変更が、READMEの記述と実際のUIのずれを生む例はすでに出ている。導入後の追従は、リリースノートとリポジトリの更新を自分で追う前提で考えるべきで、放置したまま使い続けられる類のものではない。

編集部の結論

すでにHome Assistant OSかSupervised、あるいはHACSを導入済みのContainer/Core環境で、AIクライアントから家電操作や状態照会をさせたい人には、カスタムコンポーネント方式が最も摩擦が少ない。逆に、Home Assistant本体を触らずに済ませたい、あるいは複数のインストール方法を併用して可用性を確保したい場合は向かない。導入前に確認すべきは、Home Assistantのバージョンが2026.2以降かどうか（Apps改称の影響を受ける）、サイドバーにHA-MCPパネルが出る権限を持っているか、そしてRemote access via webhookを有効にする場合はWebhook authenticationをha_authに切り替えるかどうかである。判断の分かれ目はトークン管理を捨てられるかどうかで、捨てられないならadd-on方式かstdio方式を選ぶことになる。

公式情報源

1. homeassistant-ai/ha-mcp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases