Home Assistant MCP Server

Home Assistant MCP Server とは？

この Home Assistant MCP サーバーは、tevonsb が開発したコミュニティ製の Node.js サーバーです。LLM がローカルの Home Assistant インスタンスにアクセスし、デバイスの操作と監視、オートメーション・アドオン・HACS パッケージの管理、リアルタイム更新の受信を行えるようにします。

TypeScript で書かれており、長期アクセストークンで Home Assistant に接続し、ソースからでも Docker でも実行できます。公式の統合ではありません。Home Assistant は現在、公式の Model Context Protocol Server 統合を標準で搭載しています（比較は後述）。

Home Assistant MCP Server の使い方

前提条件：

• Node.js 20.10.0 以降と npm
• 稼働中の Home Assistant インスタンスと長期アクセストークン
• 任意：Docker Compose、HACS（パッケージ管理用）、Supervisor へのアクセス（アドオン管理用）

ソースからインストール：

git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp
npm install
npm run build

.env ファイルを設定します（.env.example をコピー）。

HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
PORT=3000
NODE_ENV=production
DEBUG=false

Claude Desktop

ビルドした dist のエントリーを Claude Desktop に指定し、同じ変数を渡します。README によると、この方法では MCP サーバーが Claude の中で動作し、Docker 構成は使いません。

{
  "mcpServers": {
    "homeassistant": {
      "command": "node",
      "args": ["/path/to/homeassistant-mcp/dist/index.js"],
      "env": {
        "NODE_ENV": "development",
        "HASS_HOST": "http://homeassistant.local:8123",
        "HASS_TOKEN": "your_home_assistant_token",
        "HASS_SOCKET_URL": "ws://homeassistant.local:8123/api/websocket",
        "PORT": "3000",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Cursor と VS Code

README には記載がありません。stdio サーバーなので、同じ node /path/to/homeassistant-mcp/dist/index.js コマンドと env の値を .cursor/mcp.json や .vscode/mcp.json に追加できます。

Docker

README では、HTTP サーバーの実行に Docker Compose を推奨しています。

cp .env.example .env
docker compose up -d

サーバーは http://localhost:3000 で待ち受け、/health でヘルスチェックできます。

Home Assistant MCP Server の主な機能

• 照明（明るさ、色温度、RGB）、空調、カバー、スイッチ、ファン、ロック、掃除機、メディアプレーヤー、カメラのデバイス操作。
• エリア・フロア単位のグループ化と履歴アクセスを備えた状態の監視と照会。
• Server-Sent Events（SSE）によるリアルタイム更新。ドメインやエンティティで絞り込み可能。
• オートメーション管理：複雑なトリガーや条件を持つオートメーションの作成、編集、複製、有効化・無効化、手動実行。
• Supervisor 経由のアドオン管理：一覧、インストール、アンインストール、起動、停止、再起動。
• カスタム統合、テーマ、Python スクリプト、AppDaemon・NetDaemon アプリの HACS パッケージ管理。
• トークンベースの認証、レート制限、Docker 対応。

Home Assistant MCP Server のツール

サーバーは、アクション型のコンパクトなツール群を登録しています。

• デバイスと状態：list_devices は利用可能なデバイスを一覧表示し、control は entity_id に対して turn_on、turn_off、toggle などのコマンドを実行します（照明では brightness や rgb_color なども指定可能）。get_history は過去の状態を読み取ります。
• オートメーションとシーン：automation は既存のオートメーションを管理し、automation_config は作成・更新・複製を行い、scene はシーンを管理・実行します。
• システム管理：addon は Supervisor のアドオンを扱い（list、install、start、stop、restart）、package はカテゴリー別に HACS パッケージをインストール・一覧表示します。
• イベントと通知：subscribe_events と get_sse_stats は SSE ストリームを扱い、notify は通知を送ります。

Home Assistant MCP Server のユースケース

• 自然言語でデバイスを操作：「リビングの照明を明るさ 50% で点けて、暖かい白にして。」
• 空調の調整：「サーモスタットを 21 度にして、暖房モードに切り替えて。」
• 説明するだけでオートメーションを作成：「人感センサーが反応したら廊下の照明を点けるオートメーションを作って。」
• 家の状態を確認：「今開いているドアや鍵はどれ？」
• システムのメンテナンス：「インストール済みのアドオンを一覧にして、File editor アドオンを再起動して」「この HACS 統合をインストールして」。
• SSE で状態の変化を受け取り、オートメーションの実行をリアルタイムで確認する。

Home Assistant MCP Server と代替ツールの比較

公式の Model Context Protocol Server 統合は Home Assistant に組み込まれています。Settings > Devices & services で有効にすると、OAuth 2.0 + PKCE 対応の MCP エンドポイントが提供されます。Claude Code からは claude mcp add --transport http home-assistant <your_mcp_server_url> で接続し、続けて claude mcp login home-assistant を実行します。アシスタントに公開したエンティティだけが対象となり、デフォルトでは管理者アカウントが必要です。Claude などのクラウド型クライアントを使う場合は、インスタンスにインターネットからアクセスできる必要があります。多くのユーザーにとっては、公式統合のほうがシンプルでサポートも受けられます。このコミュニティ版サーバーは、公式の LLM API の範囲を超えるアドオン、HACS、オートメーション編集のツールを追加で提供します。ほかにもコミュニティ製の Home Assistant MCP サーバーがいくつか存在します。

Home Assistant MCP Server のトラブルシューティング

• toSorted is not a function：Node.js が古すぎます。20.10.0 以降に更新してください（例：nvm install 20.10.0）。
• 接続できない：Home Assistant が動作していること、サーバーを動かすマシンから HASS_HOST にアクセスできること、トークンの権限が正しいことを確認します。リアルタイム更新には HASS_SOCKET_URL も確認します。
• アドオン系ツールが失敗する：アドオン管理には Supervisor へのアクセスが必要です。お使いの環境で利用できるか、アドオンの互換性とあわせて確認してください。
• HACS 系ツールが失敗する：HACS がインストールされ、その統合が正常に動作しているか確認します。
• オートメーションのエラー：参照しているエンティティが存在するか確認し、トリガー条件とサービス呼び出しを見直し、ログを確認します。