ロボ図鑑

ClaudeからHome Assistantを動かす — MCPサーバー接続ガイド

公開: 2026-08-08 / 更新: 2026-09-07

Home Assistantの公式MCP Server integrationは、HAのAssist APIをMCPクライアントへ公開する接続口である。接続できたからといって家中のエンティティが自動で見えるわけではない。MCPクライアントが読める・操作できる範囲は、HA側でAssistへ公開したエンティティと、選択したLLM APIの権限で決まる。

本稿は2026年9月7日にHome Assistant 2026.9.1の公式MCP文書、LLM API開発者文書、Assistの公開設定文書を確認した。HA本体や実機への接続は行っていない。対象クライアントはClaude CodeとClaude Desktopに限定し、公開URLを使うリモート接続と、ローカル網/VPN内のHAへmcp-proxyでつなぐ経路を分けて説明する。

前提

1. Home Assistant側で公式MCPを追加する

HAで 設定 → デバイスとサービス → 統合を追加 を開き、「Model Context Protocol Server」を追加する。公式MCPサーバーのURLは/api/mcpで、トランスポートはStreamable HTTPである。古い記事にある/mcp_server/sseを現行経路として使わない。

設定画面には Control Home Assistant の選択がある。MCPクライアントにHAの制御を許可するかをここで決める。クライアントが情報取得や操作をできるのは、Assistへ公開したエンティティだけである。

2. Assistへ公開するエンティティを絞る

設定 → 音声アシスタント → 公開(Expose) を開き、MCPから扱わせるエンティティだけを選ぶ。公開しないエンティティはMCPのツールからも対象にならない。鍵、ガレージドア、暖房、給湯、医療・防犯に関わる機器は、名前だけでなく「AIから状態を読ませる必要があるか」「操作を許可するか」を個別に決める。

公開範囲は安全境界であると同時に、LLMへ渡すコンテキスト量を決める設定でもある。まず一つの部屋・少数の照明などに絞り、必要なエンティティだけ追加する。

3. 接続先のAPIを分ける

基本のエンドポイントは次の3つである。

Assist APIは、公開エンティティの状態取得と定型的な制御を提供するが、管理系操作はできない。オートメーション作成や設定変更まで必要なら、別のLLM APIまたはコミュニティ実装など、管理範囲を広げる設計が別に要る。権限を広げることを「MCP接続の成功」と混同しない。

4. Claude CodeからOAuthで接続する

HAが公開URLを持つ場合、Claude Codeの公式MCP設定でOAuth接続を使える。

claude mcp add-json "HA" '{
  "type": "http",
  "url": "https://<your_home_assistant_url>/api/mcp",
  "oauth": {
    "clientId": "http://localhost:12345",
    "callbackPort": 12345
  }
}' --client-secret

ここでclientIdはClaude CodeのローカルOAuthコールバックであり、Home AssistantのURLに置き換えない。追加後に/mcpを開き、ブラウザでHAへログインして許可する。リモート経路はHAをインターネットへ公開するため、HTTPS、アカウント保護、公開範囲を先に整える。

5. Claude Desktopから接続する

公開URLを使うリモートコネクタ

Claude DesktopのCustom Connectorへ、次を登録する。

Remote MCP Server URL: https://<your_home_assistant_external_url>/api/mcp
OAuth Client ID: https://claude.ai
OAuth Client Secret: 空欄

Anthropicのクラウド経由で接続されるため、HAがインターネットから到達可能でなければならない。Client Secretを必須入力にするフォームではランダム文字列を入れられるが、Home Assistantはそれを使わない。認証後、Claude Desktop側で使うツールを選ぶ。

ローカル網またはVPN内のHA

Claude DesktopからローカルのStreamable HTTPへつなぐ場合、公式文書はmcp-proxyを使う構成を案内している。長期アクセストークンを作成し、設定ファイルへ直接書く場合はファイルの権限と保管場所を管理する。プロジェクトのgit管理ファイルへ入れない。

{
  "mcpServers": {
    "Home Assistant": {
      "command": "mcp-proxy",
      "args": [
        "--transport=streamablehttp",
        "--stateless",
        "http://<HAのIPまたはURL>:8123/api/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<長期アクセストークン>"
      }
    }
  }
}

Long-Lived Access Tokenは、HAの ユーザープロフィール → セキュリティ → 長期アクセストークン → トークンを作成 から発行する。OAuthを使えないクライアントの代替であり、トークンが見える設定ファイルの管理責任は利用者側に残る。

6. 接続後の確認

最初は読み取りで確認する。

  1. 接続先が/api/mcpまたは/api/mcp/assistであることを確認する
  2. 公開した少数のエンティティだけがツールやコンテキストに出ることを確認する
  3. 状態取得が通ることを確認する
  4. 操作を許可した照明など、結果を目視できる1台だけで操作を試す
  5. API応答、HA上の状態、接続先機器の実際の変化を別々に確認する

404はMCP統合が未設定、401はトークンが誤っているか期限・権限の扱いが合っていない可能性がある。Assist以外のapi_idへ接続して403になる場合は、管理者要件を確認する。実機未接続の状態で「動いた」と判定しない。

公式MCPでできないこと

公式Assist APIは、公開エンティティの状態取得・操作を目的にした安全側のAPIで、管理系タスクはできない。MCPのToolsとPromptsは利用でき、ResourcesはAssist APIのライブコンテキストがある場合に限られる。SamplingとNotificationsは現行統合では未対応である。

オートメーション、スクリプト、ダッシュボード、バックアップなどの構成管理までAIに任せる必要がある場合は、公式Assist APIの範囲を越える。コミュニティ実装やHAの別APIを検討する前に、バックアップ、管理者権限、復元手段を用意する。

参考情報

いずれも2026年9月7日に実確認した。

他のガイド