ロボ図鑑

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

公開: 2026-08-09

なぜ Home Assistant が「最初の1台」なのか

AIに物理世界を触らせたいとき、デバイスを1つずつAPI接続していくのは筋が悪い。Home Assistant(以下HA)は数千種類のデバイスを統合して単一のAPIに抽象化するハブであり、2025.2以降は公式にMCPサーバーを内蔵している。つまりHAを1台立てれば、家中のデバイスがまとめてClaudeのツールになる。AIから操作できるデバイス全体の見取り図はAI手足マップ、HA自体の評価はHome Assistantのデバイスページと評価基準を参照。本稿はHAが既に動いている前提で、Claudeから操作できるようにする接続部分だけを扱う。

前提

Step 1: Long-Lived Access Token の発行

HAの画面左下のユーザー名からプロフィールを開き、「セキュリティ」タブ → 「長期アクセストークン」→「トークンを作成」(英語UIでは User profile > Security > Create token)。トークン文字列は作成時に一度しか表示されないので控えておく。なおHA公式はOAuth(IndieAuth)接続を推奨としており、トークン方式はその代替という位置づけ。

Step 2: 公式 MCP Server integration の有効化

設定 > デバイスとサービス > 統合を追加で「Model Context Protocol Server」を検索して追加する。設定項目は特にない。これでHAの /api/mcp にMCPエンドポイントが生える。トランスポートは Streamable HTTP。LLM APIごとのエンドポイントは /api/mcp/<api_id> で、組み込みのAssist APIは常に /api/mcp/assist から利用できる。

注意点として、2025.2の追加当初はSSEトランスポート(/mcp_server/sse)だったが、MCP仕様自体が2025-03-26版でStreamable HTTPに移行したのに伴い、現行の公式ドキュメントは /api/mcp のみを案内している。SSEエンドポイントを使う古い解説記事は読み替えが必要だ。

公開範囲の設定: MCPクライアントが見える・操作できるのは「Assistに公開」したエンティティだけ。設定 > 音声アシスタント > 公開(Expose)タブで、エンティティ単位で公開/非公開を制御する。鍵やガレージのような触られたくないものは公開しない、が大原則。

Step 3a: Claude Code から接続する

最短はBearerトークン付きのHTTPトランスポート追加。

claude mcp add --transport http home-assistant \
  http://homeassistant.local:8123/api/mcp \
  --header "Authorization: Bearer <長期アクセストークン>"

追加後、Claude Code内で /mcp を実行し、サーバーが connected になっていることを確認する。failed の場合は詳細にHTTPステータスが出る(401ならトークン誤り)。なおHA公式ドキュメントには claude mcp add-json でOAuth(clientIdにlocalhostのコールバックURLを指定)を使う手順も載っているので、トークンを設定ファイルに置きたくない場合はそちらを使う。

Step 3b: Claude Desktop から接続する

経路は2つある。

ローカルネットワーク内のHAにつなぐ場合(mcp-proxy経由): mcp-proxy をインストールし、claude_desktop_config.json に以下を追記する(HA公式ドキュメント記載の設定)。

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

HAをインターネット公開している場合(リモートコネクタ): Claude側のコネクタ設定からOAuthで直接接続できる。HA公式の案内ではOAuth Client IDに https://claude.ai を指定しクライアントシークレットは空欄。細部は変わりうるので公式ドキュメントで最新を確認してほしい。

Step 4: 動作確認

Claudeに自然文で聞くだけでよい。

  1. 「Home Assistantが見えているか確認して」— ツール一覧が返れば接続成功
  2. 「リビングの照明の状態を教えて」— 公開済みエンティティの状態が読めるか
  3. 「リビングの照明をつけて」— 操作の往復が通るか

401 Unauthorized が出る場合は長期アクセストークンの誤りが原因(公式トラブルシューティングに明記)。

できること — 読み取り→判断→操作のループ

公式MCPサーバーがClaudeに渡すのはAssist APIのツール群だ。これはHA組み込みの音声アシスタントと同等の能力で、インテント(定型操作)ベース。公開エンティティの状態取得と、照明・スイッチ・空調などの操作ができる一方、管理系操作(オートメーション作成・設定変更)は意図的にできない設計になっている(開発者ドキュメントに "No administrative tasks can be performed" と明記)。

この範囲でも「読み取り→判断→操作」のループは組める。

  1. 読み取り: 室温センサー・在室状態を状態取得ツールで読む
  2. 判断: 「28度超で在室なら冷房を26度設定、不在なら切る」をClaudeが判断
  3. 操作: エアコンのエンティティを操作
  4. 確認: 再度状態を読んで反映を確認

LLMを挟む価値があるのは判断が曖昧なケース(「なんか蒸すから何とかして」「来客モードにして」)で、条件が固定の定型処理はHA側のオートメーションに書くべき、という切り分けは意識したい。毎ターンLLMを通すのはレイテンシもコストも高くつく。

公式 integration とコミュニティMCPサーバーの違い

公式 MCP Server hass-mcp (voska) ha-mcp (homeassistant-ai)
導入 HA標準統合 Docker / uvx(stdio) HACS / アドオン
能力 Assist API(公開エンティティの状態取得と操作のみ) 履歴取得・オートメーション一覧/制御・エラーログ検索など 92以上のツール。オートメーション/スクリプト/ダッシュボード編集・バックアップ・統計まで
管理操作 不可(安全側の設計) 一部可 広範に可

「照明・エアコンを文字で動かしたい」なら公式で十分。「ClaudeにHAの構成管理までさせたい(オートメーションを書かせる・ダッシュボードを作らせる)」ならコミュニティ実装が必要になる。ただし後者はAIに設定への書き込み権限を渡すことを意味する。バックアップを取ってから使うこと。

ハマりどころ

参考情報

いずれも2026年8月時点で実確認。

他のガイド