Home Assistant

Home Assistant MCP サーバー

AI アシスタントから Home Assistant のエンティティ、エリア、履歴、ログブックを参照できます。テンプレートで回答できることなら何でも質問でき、ライトを暗くする、サーモスタットを設定する、スクリプトを実行するといったアクションも実行できます。何かを変更するのはアクションを実行したときだけです。また、ロック、警報パネル、カバー、バルブに対するアクションは、実行前に呼び出しごとにあなたが承認します。ここで金銭が動くことはありません。

必要なものは、このマシンからアクセスできる Home Assistant（ネットワーク経由、またはリモートアドレス経由）と、長期間有効なアクセストークンです。管理者ではないユーザーのトークンを推奨します。render_template を除くすべてのツールが使え、Home Assistant に問い合わせることなく、管理者だけに許可されている一部のアクション（再読み込み、再起動など）はサーバーが独自に拒否します。管理者のトークンを使うと、それらのアクションも実行できます。アカウントを開設する必要も、料金もありません。トークンが誤っているとログインに失敗し、数回失敗すると Home Assistant がアドレスを禁止することがあるため、サーバーは拒否されたトークンを二度と送信しません。

質問できること

• 「現在、点灯しているライトはどれですか？」
• 「一晩でリビングの温度はどう変化しましたか？」
• 「今朝、誰が、または何が玄関のドアを解錠しましたか？」
• 「廊下にあるデバイスはどれですか？」
• 「キッチンのライトを30パーセントの明るさにしてください。」
• 「玄関のドアを施錠してください。」（事前に承認します）

インストール

Claude Code を使用する場合：

claude mcp add home-assistant -e HOME_ASSISTANT_URL="<Home Assistant address>" -e HOME_ASSISTANT_TOKEN_FILE="<path to Long-lived access token file>" -- npx -y @foreverworks/mcp-home-assistant

Claude Desktop（Settings、Developer、Edit Config）や、ほとんどの他のクライアントでは、同じコマンドを JSON として読み込みます。

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["-y", "@foreverworks/mcp-home-assistant"],
      "env": {
        "HOME_ASSISTANT_URL": "<Home Assistant address>",
        "HOME_ASSISTANT_TOKEN_FILE": "<path to Long-lived access token file>"
      }
    }
  }
}

それぞれ Node 22.19 以降で公開済みパッケージを実行します。VS Code と Claude Desktop バンドルでは、サーバーの追加時に各設定を尋ねられます。省略可能な設定は空欄のままにしてください。Cursor では各設定を環境変数（${env:HOME_ASSISTANT_URL} など）から読み取るため、Cursor を起動する前に設定してください。上記のコマンドでは必須項目のみを設定しています。その他の項目については設定を参照してください。

クローンから実行

git clone https://github.com/foreverworks/mcps.git && cd mcps
npm ci && npm run build
claude mcp add home-assistant -e HOME_ASSISTANT_URL="<Home Assistant address>" -e HOME_ASSISTANT_TOKEN_FILE="<path to Long-lived access token file>" -- node "$PWD/servers/home-assistant/dist/index.js"

JSON 設定では、コマンドは node、引数は servers/home-assistant/dist/index.js のフルパスです。複数のクライアントで 1 つの実行中のコピーを HTTP 経由で共有する方法については、docs/deploying.mdを参照してください。

設定

変数	必須	意味
HOME_ASSISTANT_URL	はい	Home Assistant を開くアドレスです。例：http://homeassistant.local:8123 または https://ha.example.com。/api は含めません。プロキシの背後にあるインスタンスの場合、パスプレフィックスは保持されます。
HOME_ASSISTANT_TOKEN_FILE	はい	長期アクセストークンのみを格納したファイルです（ローカルで実行する場合は、HOME_ASSISTANT_TOKEN にトークンそのものを指定します）。
HOME_ASSISTANT_CONFIRM_DOMAINS	いいえ	呼び出しごとに承認するアクションのドメインを、カンマ区切りで指定します。デフォルトは lock,alarm_control_panel,cover,valve です。何も指定しない場合は none です。ドメインのリストでない値が指定されると、修正されるまであらゆるアクションが拒否されます。そのため、入力ミスによって承認が無効になることはありません。

これらの値は呼び出しのたびに再読み込みされるため、値を修正すれば再起動せずに次の呼び出しから反映されます。未設定でもサーバーは起動してツールの一覧を表示しますが、各ツールは不足している項目を示す config エラーを返します。

デプロイ環境で MCP_EGRESS_ALLOW を設定する場合は、HOME_ASSISTANT_URL のホスト（上記のアドレスでは homeassistant.local）を許可してください。サーバーは HTTP または WebSocket 経由で、それ以外の場所には接続しません。プライベートネットワークを遮断するサンドボックス（systemd の IPAddressDeny など）では、インスタンスのアドレスを許可する必要があります（docs/deploying.md）。すべてのサーバーで共通する変数については、docs/configuration.md を参照してください。

長期アクセストークンの取得

1. 設定の「ユーザー」からアシスタント用のユーザーを作成してログインを許可し、管理者はオフのままにして、そのユーザーとしてサインインします。ログブックには操作の原因としてそのユーザーが記録されます。また、Home Assistant 自体を変更する操作を除き、ホーム内のエンティティに対するすべての操作が可能です。render_template と管理者限定のアクションを使用する場合に限り、管理者を使ってください。Home Assistant は、それ以外のユーザーからのこれらの要求に対して 401 を返し、ログイン失敗として記録します。そのため、このサーバーはトークンの所有者を確認し、管理者以外のユーザーにはこれらの要求を送信しません。

2. プロフィール（サイドバーの下部にある自分の名前）を開き、「セキュリティ」タブを選択します。

3. 「長期アクセストークン」で「トークンを作成」を選択し、「MCP server」などの名前を付けて、トークンをコピーします。Home Assistant で表示されるのは一度だけです。削除しない限り、10 年間有効です。

4. 自分だけが読み取れるファイルにトークンだけを保存し、HOME_ASSISTANT_TOKEN_FILE にそのファイルを指定します。

   umask 077 && printf '%s\n' '<the token>' > home-assistant-token
   

初回実行

1. health を呼び出します。正常な応答には、ok: true、バージョン、state: RUNNING、タイムゾーン、websocket: ok、トークンのユーザーとそのユーザーが管理者かどうか（管理者でない場合、unavailable_tools に render_template が表示されます）、および各ドメインのエンティティ数が含まれます。
2. エリア内にあるものや、点灯中のライトを尋ねて、list_areas と list_entities の動作を確認し、その後ライトに対するアクションを試します。
3. health が auth を返す場合は、ほかのことをする前にトークンを修正してください。トラブルシューティングを参照してください。

ツール

read は何も変更しません。write はホームでアクションを実行します。太字の write は呼び出しのたびにあなたの承認が必要です（以下）。

ツール	アクセス	内容
health	読み取り	インスタンスでサーバーが動作しているかを確認します。バージョン、状態、タイムゾーン、WebSocket API のサインイン状況、ドメインごとのエンティティ数を返します。問題がある場合は ok: false を返します。
list_entities	読み取り	ドメイン、エリア、または単語でエンティティを検索します。各行に ID、名前、状態、単位、エリアを表示します（最大 1,000 件、既定値は 100 件）。
get_states	読み取り	最大 50 件のエンティティについて、属性と最終変更日時を含む状態を取得します。
list_areas	読み取り	Home Assistant のレジストリから、すべてのエリア（または 1 つのエリア）と、そのフロア、デバイス、エンティティを取得します。
history	読み取り	最大 20 件のエンティティについて、期間内の状態の変化を取得します（既定では過去 24 時間、最大 31 日間）。最新の変化を保持します。
logbook	読み取り	期間内に起きたことを取得します。必要に応じて 1 つのエンティティに絞り込み、各記録の原因（ユーザー、アクション、自動化）も表示します。
list_actions	読み取り	利用可能なアクションを取得します。すべてのドメインのアクション名、または 1 つのドメインのアクションとそのフィールドを表示します。
render_template	読み取り	Home Assistant のテンプレートを状態およびヘルパーとともにレンダリングします。管理者のトークンがある場合に限ります。
call_action	書き込み	対象（エンティティ、デバイス、エリア、フロア、ラベル）に対して指定したデータでアクションを実行し、変化した状態を返します。呼び出しごとに承認が必要なアクションと、トークンのユーザーが管理者でない場合に管理者のみ実行できるアクションは拒否します。
call_action_confirmed	書き込み	呼び出しを承認した後に、任意のアクションを実行します。

承認

call_action は、承認が必要なアクションを、何も送信する前に needs_confirmation とともに拒否します。

• HOME_ASSISTANT_CONFIRM_DOMAINS のいずれかに含まれるアクション（lock.unlock、cover.open_cover、alarm_control_panel.alarm_disarm、valve.open_valve）。
• 他のドメインのアクションで、そのいずれかに属するエンティティを対象とするもの（cover.garage_door に対する homeassistant.toggle）。
• デバイス、エリア、フロア、ラベル、または all を対象とする homeassistant アクションで、これらのいずれかに到達できるもの。

これらは call_action_confirmed を通じて実行されます。支払いと同様に承認が必要ですが、支払いは発生しません。クライアントは呼び出しのたびに確認を求めます（Claude Code は、すべての権限モードで確認を求めます）。MCP_CONFIRM=elicit を設定すると、サーバー自身が実行される呼び出しから生成した 1 行の内容で、コードまたは **** と表示されるパスワードを求めます。

home-assistant: run the Home Assistant action lock.unlock on lock.front_door, with code=****

MCP_MAX_ACCESS=read を設定すると、両方のアクションツールが無効になり、読み取りツールのみが残ります。各クライアントの確認方法については、docs/security.md を参照してください。

トラブルシューティング

auth、ステータス 401。 Home Assistant がトークンを拒否しました。トークンが削除された、ユーザーが削除または無効化された、あるいはコピーが途中で切れた可能性があります。 新しいトークンを作成し（上記）、トークンファイルに設定してください。ファイルに別のトークンが設定されるか、サーバーが再起動するまでは、すべての呼び出しに sent: false を伴う auth が返され、何も送信されません。Home Assistant は拒否をログイン失敗として記録し、アドレスを禁止することがあるためです。

auth、ステータス 403。 Home Assistant、またはその前段のプロキシが、このマシンのアドレスを拒否しています。通常、ログイン失敗の後に Home Assistant がアドレスを禁止したことが原因です。Home Assistant の設定フォルダーにある ip_bans.yaml からそのアドレスを削除し、Home Assistant を再起動して、トークンを確認してから、このサーバーを再起動してください。

unreachable。 HOME_ASSISTANT_URL で応答がありませんでした。Home Assistant が稼働していることと、このマシンから接続できることを確認してください。このマシンのブラウザーで同じアドレスを開ける必要があります。メッセージにはネットワークから返された内容が示されます（ECONNREFUSED：そのポートで待ち受けているものがありません。ENOTFOUND：この環境では名前を解決できません）。

unavailable。 Home Assistant がサーバーエラーを返しました。起動中、停止中、または再起動中です。1 分ほど待ってから health を呼び出してください。

needs_admin。 トークンのユーザーは管理者ではありませんが、この操作には管理者が必要です。該当するのは render_template、または Home Assistant が管理者にのみ実行を許可するアクションです。sent: false の場合、サーバーが独自に拒否しており、Home Assistant には何も届いていません。このトークンで他のすべてのツールは利用できます。これらの操作が必要な場合に限り、管理者のトークンを使用してください。

permission。 トークンは有効ですが、Home Assistant が管理者専用の WebSocket コマンドを返しました。このサーバーのコマンドに管理者権限が必要なものはないはずです。health が示すバージョンとともに報告してください。

needs_confirmation。 このアクションは、呼び出しごとに承認が必要です。アシスタントは call_action_confirmed を呼び出してください。最初に確認が求められます。

outcome_unknown。 アクションは送信されましたが、明確な応答がありませんでした。実行された可能性があります。再度実行する前に、エンティティ（get_states）を確認してください。サーバーがアクションを独自に二重送信することはありません。

エンドポイントの not_found。 history または logbook の背後にあるインテグレーションが読み込まれていません。configuration.yaml の default_config: を使うと、recorder とともに両方が読み込まれます。

drift。 Home Assistant 以外のものが応答しました。プロキシのサインインページなどがよくある例です。HOME_ASSISTANT_URL を Home Assistant 自体、または独自のサインインを行わずに /api をそのまま通すプロキシに設定してください。

https:// での証明書エラー。 このサーバーはブラウザーと同じように証明書を検証します。独自の認証局を持つインスタンスの場合は、NODE_EXTRA_CA_CERTS を使ってその認証局の証明書を Node に渡すか、信頼できるネットワーク上でインスタンスの http:// アドレスを使用してください。

動作の仕組み

2 つの API を使用します。 状態、アクション、履歴、ログブック、テンプレートは REST API から取得します。エリア、フロア、デバイス、エンティティのレジストリは WebSocket API にしかないため、list_areas と list_entities はそれらを取得するために短時間のセッションを開きます。トークンでサインインし、コマンドをまとめて送信して、接続を閉じます。

拒否されたトークンは二度と送信されません。 Home Assistant は、無効なトークンによるリクエストをすべてログイン失敗として記録し、「Login attempt failed」通知を発し、IP アドレスの禁止が有効な場合は、わずか 1 回の試行でもそのアドレスを永久に禁止することがあります。そのため、401 または 403 を受け取るとただちに処理を中止し、再試行や更新は行いません。また、サーバーは拒否されたトークンをその SHA-256 で記憶します。後続の呼び出しは、トークンファイルが変更されるかプロセスが再起動されるまで、リクエストを送信せずに失敗します。トークンが一度受け入れられるまでは、リクエストは一度に 1 つずつ送信されるため、誤ったトークンによるログイン失敗は、ツールが実行中だったリクエストごとではなく 1 回だけです。

アクションは 1 回だけ送信されます。 読み取りは、ネットワークエラー、502、503、504 の後にもう 1 度だけ試行されます。アクションは再試行されません。タイムアウトまたはサーバーエラーの後では、すでに実行されている可能性があるため、結果は outcome_unknown になります。Home Assistant は、存在しないアクションとデータの検証に失敗したアクションに同じ簡素な 400 を返すため、サーバーは 400 の後にアクション一覧を読み取り、どちらだったかを判別します。

保持しているトークンの所有者を把握します。 有効なトークンであっても、管理者ではないユーザーのトークンは、管理者しか実行できない操作を要求すると、ログイン失敗としてカウントされる 401 を返します。そのため、最初のテンプレートまたはアクションの実行前に、サーバーは WebSocket API にトークンの所有者を問い合わせ（auth/current_user）、その回答をトークンの SHA-256 に紐付けて保持し、管理者権限が必要な操作を独自に拒否します。管理者権限が必要な操作は Home Assistant のソースから読み取ります。テンプレートエンドポイント、すべての reload アクション、そして約 50 のインテグレーションが登録する管理者専用アクション（homeassistant.restart、recorder.purge、すべての hassio アクションなど）が該当します。管理者専用だと把握していなかったアクションは、Home Assistant が返す 401 を受けて一度だけ判定され、そのトークンに対して記録され、以降は送信されません。トークンは引き続き使用できます。health は呼び出しのたびに再確認するため、その間に管理者になったユーザーも認識されます。

認証情報が応答に含まれないようにします。 カメラの access_token 属性は削除され、entity_picture などのプロキシアドレスに含まれる token= は、状態がモデルに渡される前に [redacted] に置き換えられます。

制限事項

• 読み取りと実行は行いますが、設定は行いません。オートメーション、スクリプト、シーン、ダッシュボード、ヘルパー、インテグレーション、ユーザーの設定は、Home Assistant 自身のインターフェースで行います。
• ライブ更新には対応していません。呼び出しごとに現在の状態を読み取り、イベントをサブスクライブすることはありません。
• 承認はドメイン単位です。ドアを解錠するスクリプト、シーン、オートメーションは、それぞれ script、scene、automation アクションとして実行されます。そのような操作を行う場合は、それらのドメインを HOME_ASSISTANT_CONFIRM_DOMAINS に追加してください。 homeassistant.restart はデフォルトでは承認されません。再起動も含め、すべてのドメイン横断アクションを承認するには、homeassistant を追加してください。
• サーバーごとに 1 つのインスタンスを使用し、トークンは長期間有効なものを使用します。Home Assistant の OAuth サインインは使用しません。
• 2026-10-26 以降に管理者専用アクションを追加するインテグレーションでは、管理者ではないユーザーのトークンでそのアクションを初めて要求すると、ログイン失敗が 1 回発生します。Home Assistant で読み取りのみ許可され、制御は許可されていないユーザーは、制御権限のないエンティティに対する各アクションで 401 を受け取ります。アシスタントには一般ユーザーを割り当ててください。
• 履歴とログブックを参照できる期間は、recorder の保持期間までです（別途設定しない場合は 10 日間）。

Home Assistant 向けのその他のサーバー

2026-10-26 に検索しました（Home Assistant のドキュメント、GitHub、PyPI、npm、ウェブ）。見つかったもの：

• Home Assistant 独自の Model Context Protocol Server インテグレーション（2025.2 以降）：Assist API のツールを /api/mcp で提供し、OAuth でクライアントをサインインさせ（デフォルトでは管理者）、Assist に公開されたエンティティにのみアクセスします。ドキュメントには、履歴、ログブック、レジストリ、テンプレートについての記載はありません。
• ha-mcp（Python）：約 90 個の ツールを備え、自動化、ダッシュボード、履歴、トレース、バックアップなどに対応します。 カスタムインテグレーション、アドオン、またはトークンを使うプロセスとしてインストールできます。
• hass-mcp（Python）：エンティティ、 アクション、履歴、統計、エラーログ、ダッシュボードに対応し、長期間有効なトークンを使用します。
• homeassistant-mcp （TypeScript）：デバイス制御、アドオン、自動化設定に対応します。

このサーバーは、ここにある他のサーバーと同じツールキットを使いながら、小規模で読み取り中心の構成を求める読者向けです。各ツールを読み取りまたは書き込みに分類し、MCP_MAX_ACCESS とクライアントごとの上限を設定し、呼び出しごとに監査ログを記録します。ホームを開くアクションは、正確な行を添えて呼び出しごとに承認し、Home Assistant が拒否したトークンは再送せず、送信先をそのインスタンスのみに制限します。Home Assistant には何もインストールしません。