home-assistant-mcp

home-assistant-mcp

Model Context Protocol（MCP）サーバーです。Cursor、VS Code（Copilot）、Claude Desktop など、MCP に対応するコーディングエージェントが、Home Assistant や（任意で）ESPHome のダッシュボードと直接やり取りできるようにします。

エージェントにエンティティ ID、YAML、現在値をコピーして貼り付ける代わりに、エージェントがエンティティを見つけ、ライブ状態を読み取り、テンプレートをレンダリングし、サービスを呼び出し、自らオートメーションを編集して、コードが実際に動作するまで反復できます。

Claude Code では、4つのサイドペインに、Claude が家に対して行っていることがリアルタイムで表示されます。作業中のオートメーション、構築中の ESPHome デバイス、家の健全性スコア、そして動作するダッシュボードです。1つのコマンドですべてをインストールできます（以下を参照）。

Vome ファミリーの一部であり、VomeHome（マネージド Home Assistant）に付属するオープンソースのコンパニオンです。あらゆる Home Assistant ユーザーが単独で利用することもできます。

---

特長

一般的な「オートメーションを変更する」作業の流れは、今では次のようになっています。エージェントに既存のエンティティを伝え、現在値を貼り付け、YAML を貼り付け、変更を適用し、動作したかどうかを手動で確認します。このサーバーを使えば、エージェントがそのすべてを実行します。

• 確認 — エンティティ／エリア／デバイスの一覧表示、正確な状態と属性の読み取り、履歴とログブックの取得。
• 試行 — ライブ状態を使った Jinja テンプレートのレンダリング、設定の確認、エラーログの読み取り。
• 変更 — サービスの呼び出し、オートメーションの作成／更新／削除／トリガー、および（ESPHome の場合）デバイスファームウェアの編集、検証、コンパイル、書き込み。

すべての書き込み操作はデフォルトで無効になっており、明示的な安全ポリシーによって制御されます（安全性を参照）。

---

ツール

Home Assistant — 読み取り

ツール	説明
ha_get_config	コア設定：バージョン、場所、タイムゾーン、読み込み済みコンポーネント。
ha_list_entities	エンティティを一覧表示します（ドメイン、フリーテキスト検索、エリアで絞り込み）。
ha_get_state	1つ以上のエンティティの状態と属性をすべて取得します。
ha_get_history	指定した時間範囲内の状態変更履歴。開始時刻のみを指定すると、現在まで取得します（Home Assistant単体では開始から24時間後に停止します）。ha_get_logbook も同様に動作します。
ha_list_services	利用可能なサービス（指定したドメインのフィールドも含む）。
ha_list_areas	エリア（部屋／ゾーン）。
ha_list_devices	デバイスレジストリ（エリア／検索で絞り込み）。
ha_get_entity_registry	レジストリのメタデータ：プラットフォーム、エリア、デバイス、無効化／非表示。
ha_render_template	ライブ状態をもとにJinja2テンプレートをレンダリングします。
ha_list_helpers	保存済みヘルパー（input_boolean、input_number、counter、timer、…）を一覧表示します。
ha_list_automations	entity_id、unique id、状態、最終トリガー時刻を含むオートメーション。
ha_get_automation	オートメーション設定全体（トリガー／条件／アクション）。
ha_check_config	設定を検証します（設定のチェック）。
ha_get_system_log	重複を除いた構造化エラー — レベル、ロガー、ソース、件数、初回／最終検出時刻。まずはこちらを確認してください。
ha_get_error_log	Home Assistantの生のエラーログの末尾。
ha_get_supervisor_log	アドオン／Core／Supervisor／ホストのログ（HAOSまたはSupervised）。
ha_list_media_files / ha_read_media_file	/media を読み取り専用で参照します。保存済みのカメラ画像は画像として返されます（ha:files と、ホーム側のVomeアドオン 0.3.66／インテグレーション 0.9.51が必要です）。
ha_camera_image	カメラの現在の静止画像を、エージェントが確認できる画像として取得します。VomeHome経由の場合は、キーで Cameras を有効にする必要があります。
ha_camera_frame	カメラの静止画像をデコードし、RGBピクセルの小さなグリッドに縮小します。テキストで画像を描画するクライアント向けです。
ha_view_snapshot	ダッシュボードのビューに表示されるすべての情報を1回の呼び出しで取得します：状態、レンダリング済みテンプレート、少数のポイントでの履歴、カメラのフレーム。ダッシュボードクライアント向けです。
ha_watch_states	ポーリングの代わりに状態変更を待ち受けます：ホームのVomeコンポーネントが、変更の発生時に送信します（VomeHome経由）。
ha_get_logbook	人が読みやすいログブックのエントリ。
ha_get_energy_prefs	Energyダッシュボードの設定（電力網、太陽光、バッテリー、ガス、水、追跡対象デバイス）。ダッシュボード独自の検証も行います。
ha_list_traces	最近のオートメーション／スクリプトの実行履歴と、それぞれの停止理由。
ha_get_trace	1回の実行の手順ごとの詳細。処理を妨げたステップは failed_at で示されます。

Home Assistant — 書き込み（書き込みゲート制御）

書き込みゲート制御の動作はモードによって異なります。direct モードでは MCP が唯一のガードとなるため、HA_ALLOW_WRITE=true を設定するまでこれらの操作は拒否されます。brokered モードでは、VomeHome API キーにインスタンスごとの ha:write / ha:config スコープが設定され、サーバーがそれを強制するため、クライアントのフラグはローカル限定の制限として任意で設定できます。

ツール	説明
ha_call_service	任意のサービス（turn_on、set_temperature、…）を呼び出します。
ha_clear_system_log	構造化エラーストアを空にします（HA_ALLOW_WRITE のみ必要です）。
ha_set_log_level	実行時に特定のインテグレーションのログレベルを変更します（HA_ALLOW_WRITE のみ必要です）。
ha_set_automation	オートメーションを作成または更新します（HA_ALLOW_CONFIG_WRITE も必要です）。
ha_set_helper	ヘルパーを作成または更新します。configuration.yaml の編集も再起動も必要ありません。
ha_read_config_file	設定ディレクトリ内のファイルを読み取ります。デフォルトではテキストとして読み取り、バイナリーアセットの場合は encoding: 'base64' を指定します（ha:files が必要です）。
ha_write_config_file	設定ディレクトリ内のファイルを置き換えます。デフォルトではテキストとして書き込み、バイナリーアセットの場合は encoding: 'base64' を指定します。設定を検証し、失敗した場合はファイルを復元します（ha:files が必要です）。
ha_delete_config_file	設定ディレクトリ内のファイルを1つ削除します。ディレクトリ、および configuration.yaml、secrets.yaml、Home Assistant のデータベースは削除できません。書き込みと同様に対象のホームを指定します（ha:files、およびそのホームの Vome アドオン 0.3.55 / インテグレーション 0.9.39 が必要です）。
ha_edit_config_file	テキストファイルの一部をその場で変更します。完全一致する検索・置換を指定し、各編集がそれぞれ1回だけ一致する必要があります。その後、書き込みと同じ検証と復元を行います。大きなファイルの3行を変更する場合に使います（ha:files が必要です）。
ha_list_config_files	設定ディレクトリ内のディレクトリを一覧表示します（ha:files が必要です）。
ha_move_config_file	設定ディレクトリ内のファイルを移動または名前変更します。途中のフォルダーも作成します。明示的に指定しない限り、上書きはしません。書き込みと同様に対象のホームを指定します（ha:files、および Vome アドオン 0.3.66 / インテグレーション 0.9.51 が必要です）。
ha_delete_helper	保存済みのヘルパーを削除します。ID が configuration.yaml のヘルパーと共有されているように見える場合は拒否します。Home Assistant がそのエンティティも削除してしまうためです。
ha_delete_automation	オートメーションを削除します（HA_ALLOW_CONFIG_WRITE も必要です）。
ha_get_script / ha_set_script / ha_delete_script	ID を指定してスクリプトを操作します。オートメーションと同じ方法で、複数のオートメーションで共有するステップを1つのスクリプトにまとめられます。書き込みには HA_ALLOW_CONFIG_WRITE が必要です。
ha_update_entity	レジストリ内のエンティティの名前変更、ID の再設定、移動、アイコンの変更、無効化、または非表示化を行います（HA_ALLOW_CONFIG_WRITE が必要です）。
ha_update_device	デバイスの名前変更、エリアへの移動、無効化、またはラベルの設定を行います（HA_ALLOW_CONFIG_WRITE が必要です）。
ha_expose_entities	Assist、Alexa、Google Assistant で表示・操作できる内容を一覧表示または変更します。一覧表示は読み取り権限のみで可能です（変更には HA_ALLOW_CONFIG_WRITE が必要です）。
ha_set_energy_prefs	Energy ダッシュボードの設定を変更します。渡した各リストはそのリスト全体を置き換え、その後検証されます（HA_ALLOW_CONFIG_WRITE が必要です）。
ha_get_statistics	長期統計情報（Energy ダッシュボードに表示されるデータ）を5分単位から月単位で読み取ります。largest_changes では、Outliers ボタンのように最も大きなバケットが一覧表示されます。
ha_adjust_statistic	Developer Tools → Statistics と同様に、新しい値または調整量を指定して、統計の5分バケットを1つ修正します（HA_ALLOW_CONFIG_WRITE が必要です）。
ha_remove_entity	孤立したレジストリエントリーを削除します（HA_ALLOW_CONFIG_WRITE が必要です）。
ha_matter_reinterview	ファームウェア更新後にエンドポイントが変更されたデバイスに対して、Matter デバイスページの再インタビューを実行します（HA_ALLOW_CONFIG_WRITE が必要です）。
ha_trigger_automation	オートメーションを今すぐ手動で実行します。
ha_reload_automations	再起動せずにオートメーションを再読み込みします。

Lovelace ダッシュボード（HA への直接接続、または VomeHome 経由）

ツール	内容
ha_list_dashboards	ダッシュボードを一覧表示します（url_path、タイトル、モード、サイドバー）。
ha_get_dashboard	1 つのダッシュボードの設定全体（ビュー、カードなど）を読み取ります。
ha_save_dashboard	ダッシュボードの設定を保存／置換します（HA_ALLOW_CONFIG_WRITE が必要です）。
ha_create_dashboard	ストレージモードのダッシュボードを新規登録します（HA_ALLOW_CONFIG_WRITE が必要です）。
ha_delete_dashboard	ID を指定してダッシュボードを削除します（HA_ALLOW_CONFIG_WRITE が必要です）。

ダッシュボードは Home Assistant の WebSocket API を使用します。ブローカー経由モードでは、VomeHome が許可リストに登録された一部の機能を POST /api/v1/instances/<id>/ha/ws/command 経由でプロキシします。 | ha_fire_event | イベントバスでカスタムイベントを発生させます。 |

ESPHome（リレーに接続された HA 経由）

ツール	説明
esphome_dashboard_info	ESPHome への接続方法と、現在ファームウェアの書き込みやログの取得が可能かどうかを確認します。
esphome_list_devices	ダッシュボードの設定／デバイスを一覧表示し、名前の変更が必要な設定にフラグを付けます。
esphome_list_migrations	名前が変更された ESPHome の表記のうち、設定でまだ使われているものを一覧表示します。
esphome_get_config	設定の YAML を読み取ります。
esphome_save_config	設定の YAML 全体を書き込みます。新しいファイルの場合に使用します（書き込みには許可が必要です）。
esphome_edit_config	完全一致する検索・置換編集で設定の一部をその場で変更します。長いファイルを再送せずに済みます（書き込みには許可が必要です）。
vome_health_report	家全体の Vome ヘルススコアと、各検出事項を表示します。各検出事項には重大度、根拠、推奨事項、関連するエンティティが含まれます。
vome_health_check	修正後にスコアを再評価できるよう、新たにヘルスチェックを実行します（書き込みには許可が必要です）。
esphome_validate	設定を検証します。
esphome_compile	ファームウェアをコンパイルします。
esphome_upload	まず検証を行い、ファームウェアをコンパイルしてデバイスに無線で書き込みます（書き込みには許可が必要です）。
esphome_logs	デバイスのライブログ（起動、Wi-Fi、センサー、クラッシュ）を読み取ります。
esphome_clean	古いビルドによるコンパイル失敗の後、キャッシュされたビルドファイルを削除します（書き込みには許可が必要です）。

設定は不要です。ビルドやログを含むすべてのコマンドは VomeHome リレー経由で実行されるため、ブローカー経由の Home Assistant が利用できる場所ならどこでも ESPHome が動作し、ポートを開放する必要はありません。

別の接続経路もありません。ESPHome アドオンはホストネットワークを使用し、Web ポートは無効になっています。また、Supervisor と localhost だけを許可する Ingress の背後にあるため、ホーム内でダッシュボードに接続できるのは Vome コンポーネントだけです。以前はダッシュボードに直接接続するモード（ESPHOME_DASHBOARD_URL）がありましたが、0.6.0 で削除されました。ESPHome がそのプロトコルをすでに廃止しており、デフォルトのインストールではいずれにしても接続できなかったためです。

Node-RED（NODERED_URL）

Node-RED は Home Assistant アドオンとして提供される、フローベースのエディターです。高機能ですが手作業での編集は扱いにくいため、エージェントにフロー JSON の読み書きを任せましょう。フローはタブごとにグループ化されたノードの JSON 配列として保存されます。これらのツールはタブ単位（安全）または設定全体（慎重に実行）で操作します。書き込みには、HA オートメーションの編集と同じスイッチ（HA_ALLOW_WRITE + HA_ALLOW_CONFIG_WRITE）による許可が必要です。

ツール	説明
nodered_get_flows	すべてのタブを含むフロー設定全体と、現在のリビジョンを取得します。
nodered_get_flow	ID を指定して、1 つのフロー（タブ）とそのノードを取得します。
nodered_list_nodes	インストール済みのノードモジュール／型（パレット）を一覧表示します。
nodered_create_flow	既存のフローに影響を与えずに新しいタブを追加します（書き込みには許可が必要です）。
nodered_update_flow	ID を指定して 1 つのタブを置き換え、ほかのタブはそのままにします（書き込みには許可が必要です）。
nodered_delete_flow	タブとそのノードを削除します（書き込みには許可が必要です）。
nodered_set_flows	フロー設定全体を置き換えてデプロイします（書き込みには許可が必要です）。

VomeHome（VOMEHOME_TOKEN が必要です）

VomeHome は、管理型の Home Assistant ホスティングサービスです。GitHub でポータルにログインし、Account → API tokens で個人用アクセストークンを発行すると、エージェントがエディターからインスタンスを管理できるようになります。高度な管理には、引き続きポータルでの完全なブラウザーログインが必要です。

ツール	説明
vomehome_list_instances	ステータス、ティア、URL、リアルタイムのヘルス状態、アクティブなインスタンス、インスタンスごとのクライアントの書き込み／設定アクセス権とともに、HA インスタンスの一覧を表示します。
vomehome_get_instance	1 つのインスタンスの詳細とリアルタイムのステータスを取得します。
vomehome_use_instance	ha_* ツールの対象インスタンスを切り替えます（複数インスタンスについては、1 つのトークンで複数のインスタンスを利用するを参照）。
vomehome_reboot_instance	インスタンスの VM を再起動します（書き込み権限が必要です）。
vomehome_create_instance	一時的なテスト／サンドボックスインスタンスを作成します（API キーに作成スコープが必要です。作成に使用したキーには新しいインスタンスへの完全な HA アクセス権が付与され、新しいインスタンスがアクティブな対象になります）。
vomehome_get_login_url	新しいタブで開ける、ワンクリック HA ログイン URL を発行します。
vomehome_list_backups	ホームの Vome バックアップ保存先にあるバックアップを一覧表示します（ha:files が必要です）。
vomehome_backup_download_link	1 つのバックアップの .tar をダウンロードするリンクを取得します。有効期間は約 15 分です（ha:files が必要です）。
vomehome_create_guest_link	共有用に、管理者以外の HA ユーザーとワンクリックログイン URL を作成します（HA_ALLOW_CONFIG_WRITE が必要です）。Vome ホスティングのインスタンスのみが対象です。
vomehome_list_guest_links	取り消し済みのものも含め、インスタンスのゲストリンクを一覧表示します。
vomehome_revoke_guest_link	ゲストリンクをただちに取り消します。

ゲストリンクは、ユーザー自身で発行・取り消しができる共有機能です。所有者自身の認証情報を渡すことなく、必要に応じて管理者以外の Home Assistant アカウント（admin: true を渡さない場合）とワンクリックログイン URL を発行・無効化できます。この機能を使えるのはVome ホスティングのインスタンスのみです。所有者以外のユーザー向けトークンを発行するには VM への直接のネットワークアクセスが必要ですが、セルフホスト／リレー接続のインスタンスではポータルからそのアクセスを利用できません。

Home Assistant の権限モデルは大まかなものです。 管理者以外のゲストは設定と開発者ツールにアクセスできませんが、ダッシュボードに表示されるすべてのエンティティに対してサービスを呼び出すことはできます。Home Assistant 自体には、ゲストに対するエンティティ単位の制限はありません。ゲストリンクは、自由に操作できるよう設計された専用のデモ／サンドボックスインスタンスであれば安全に使えます。誰かが実際に暮らす家のアクセス制御の代わりにはなりません。そのような家のインスタンスには使用しないでください。リンクは自動的に期限切れになります（expires_in の既定値は 24 時間、上限は 30 日です。Home Assistant 独自の長期トークンは自然に期限切れにならないため、Vome がこの制限を適用します）。また、いつでも手動で早期に取り消せます。

インテグレーションと設定エントリー

ツール	説明
ha_list_config_entries	インストール済みのインテグレーション（設定エントリー）を一覧表示します。ドメインで絞り込むこともできます。
ha_delete_config_entry	ID を指定して設定エントリーを削除します。デバイスの削除後に残った孤立／重複エントリーを解消します。これを削除しないと、デバイスを再追加したときにエンティティ名に _2 のサフィックスが付くことがあります。HA_ALLOW_CONFIG_WRITE が必要です。
ha_list_discovery_flows	Home Assistant がネットワーク上で検出したものの、まだ追加していないインテグレーションを一覧表示します。
ha_config_flow	インテグレーションの設定フローを開始（handler）、既存のエントリーを再設定（entry_id）、または続行（flow_id + user_input）します。HA_ALLOW_CONFIG_WRITE が必要です。
ha_config_entry_options	ESPHome の allow_service_calls を含む、インテグレーションのオプションを読み取るか設定します。
ha_integration_setup_vome	既定の設定で Vome（vomesync）の設定エントリーを冪等に追加します。

Supervisor / Vome アドオン（HAOS / Supervised）

ツール	説明
ha_supervisor_api	supervisor/api 経由で Supervisor エンドポイントを呼び出します（ストア、アドオンなど）。…/logs の読み取りはログルートから処理されます。supervisor/api ではプレーンテキストを扱えないためです。また、アドオンの起動／停止／再起動は、Home Assistant の 10 秒ではなく 50 秒待機します。
ha_addon_install_vome	ストアに https://github.com/Vortitron/VomeSync を追加し、Vome をインストールして起動します。

HACS（Home Assistant Community Store）

ツール	説明
ha_hacs_info	HACS のバージョン、ステージ、保留中のバックグラウンドタスクの有無を確認します。
ha_hacs_list_repositories	HACS が認識しているリポジトリを一覧表示します（カテゴリで絞り込むこともできます）。
ha_hacs_add_repository	owner/repo とカテゴリを指定してカスタムリポジトリを追加します。HACS は追加に失敗しても応答するため、再度一覧を取得して確認します。HA_ALLOW_CONFIG_WRITE が必要です。
ha_hacs_download_repository	登録済みリポジトリをインストール（または更新）します。実際にファイルを書き込む手順です。HA_ALLOW_CONFIG_WRITE が必要です。
ha_hacs_remove_repository	リポジトリのファイルをアンインストールし、追跡を停止します。HA_ALLOW_CONFIG_WRITE が必要です。

HACS リポジトリの管理には、REST API もサービス呼び出しもありません。上記の Supervisor ツールと同様に、HACS 独自の WebSocket コマンド（hacs/*）を使用します。リポジトリの追加は登録のみを行います。インストールするには、その後 ha_hacs_download_repository を呼び出してください。また、新しい統合またはアドオンドメインの場合は Home Assistant を再起動してください。

ユーザー

ツール	説明
ha_list_users	すべてのユーザーを一覧表示します：ID、名前、ユーザー名、ロール、有効／所有者の状態。
ha_create_user	ロール（admin／user／read_only）を指定してユーザーを作成しますが、ログインはまだ作成しません。HA_ALLOW_CONFIG_WRITE が必要です。
ha_update_user	ユーザーの名前、ロール、有効状態、またはローカル限定の制限を変更します。HA_ALLOW_CONFIG_WRITE が必要です。
ha_delete_user	ユーザーとそのログインを完全に削除します。HA_ALLOW_CONFIG_WRITE が必要です。
ha_set_user_credentials	まだログインがないユーザーにユーザー名とパスワードを設定します。HA_ALLOW_CONFIG_WRITE が必要です。
ha_change_user_password	すでにログインがあるユーザーのパスワードをリセットします。HA_ALLOW_CONFIG_WRITE が必要です。
ha_remove_user_credentials	ユーザーを削除せずにログインを削除します。HA_ALLOW_CONFIG_WRITE が必要です。
ha_provision_service_login	プログラム（MQTT クライアント、Zigbee ブリッジ、ESPHome デバイス）専用の非管理者ログインを作成し、パスワードをアドオンのオプションまたはシークレットファイルに直接書き込みます。パスワードはここで生成され、返されることはありません。HA_ALLOW_CONFIG_WRITE と、シークレットファイルには ha:files が必要です。

これらのツールが作成するユーザーとパスワードは、VomeHome API キーとは独立した、永続的な Home Assistant ログインです。 作成に使ったキーを無効にしてもアカウントは削除されません。このサーバーのその他の機能はすべて呼び出し元のキーを介して動作し、キーが無効になると機能しなくなる点とは異なります。インスタンスで ha:config を許可することは、そのホームで永続的なアカウントを作成する権限を保有者に委ねることと同等です。ha_create_user では role にデフォルト値がありません。暗黙のうちに admin になることがないよう、明示的に選択する必要があります。

プログラム向けログイン：ha_provision_service_login。 デバイスをホームに接続する作業は、通常、ある手順で止まります。誰かがパスワードを考えて、2 か所に入力する必要があるからです。ha_set_user_credentials では呼び出し元がパスワードを選ぶ必要があり、エージェントが行うべきではありません。このツールは代わりにパスワード（128 ビット）を生成し、利用先のアドオンオプション（例：mqtt.user／mqtt.password）やシークレットファイルに書き込み、保存先だけを返します。パスワード自体は返しません。Mosquitto アドオンは Home Assistant ログインを受け入れるため、1 回の呼び出しで MQTT クライアントを接続できます。何かを作成する前にすべての書き込み先を確認し、書き込み先がない新しいログインは削除します。管理者アカウントは作成せず、デフォルトでローカル限定です。また、rotate=true の場合は、このツール自身が作成したログイン（ユーザー名に (service login) と表示）だけを再発行し、個人のアカウントには触れません。Home Assistant の外部にあるプログラムで、アドオンオプションもシークレットファイルもないものには対応できません。

ha_config_entry_options は、API のほかの場所には存在しない設定にアクセスします。よく求められる設定は、ESPHome の 「デバイスによる Home Assistant アクションの実行を許可」（allow_service_calls）です。これがないとデバイスは HA サービスを呼び出せません。また、UI の奥深くにあるため、設定を忘れられがちです。ha_list_config_entries を domain=esphome と指定してエントリ ID を取得し、entry_id だけを指定してフォームを読み取ります。その後、user_input を指定して再度呼び出します。送信するとフォーム上のすべてのフィールドが設定されるため、読み取った値を送り、変更したい項目だけを変更してください。

Supervised／HAOS のターゲットが必要です（例：vomehome_create_instance で作成した VomeHome サンドボックス、または ha-plc-sandbox MCP エントリ）。ブローカー経由のモードでは API キーのスコープで決まるため、HA_ALLOW_WRITE／VOMEHOME_ALLOW_CREATE の環境フラグは不要です。コンテナーのみの HA にはアドオンストアがありません。その場合は HACS を使ってインテグレーションを導入してください。

一般的な開発フロー：vomehome_create_instance → 起動するまで待機 → ha_addon_install_vome → Core を再起動 → Vome インテグレーションを追加。

---

インストール

Node.js ≥ 20 が必要です。手動でインストールするものはありません。エディターが必要に応じて npx でサーバーを起動するため、同じ設定をすべてのマシンで使用できます（絶対パスは不要です）。

ワンクリック（Cursor）

クリックして、あらかじめ入力されている HA_URL と HA_TOKEN を編集します。（ボタンをクリックしても何も起きない場合は、このセクションのソースにある cursor:// リンク をブラウザーのアドレスバーにコピーしてください。）

1 行の設定

これを ~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1 つのプロジェクト）に追加し、トークンを入力すればインストールは完了です。

{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"HA_URL": "http://homeassistant.local:8123",
				"HA_TOKEN": "paste-your-long-lived-token",
				"HA_ALLOW_WRITE": "false"
			}
		}
	}
}

確認／ソースから

npx -y @vortitron/home-assistant-mcp doctor   # one-off connectivity check

# or hack on it:
git clone https://github.com/Vortitron/home-assistant-mcp.git
cd home-assistant-mcp && npm install && npm run build

LAN TCP トンネル（RDP など）

npx -y @vortitron/home-assistant-mcp tunnel --token <jwt> --local-port 3390

127.0.0.1:<local-port> でローカルリスナーを開き、Vome がすでに使用している同じアウトバウンドリレー経由で、Vome とリンクされた Home Assistant 上の tcp スキームの LAN ルート（例：RDP ホスト）に転送します（ルーターでのポートフォワーディングは不要です）。mstsc／Remmina／任意の TCP クライアントで、このローカルアドレスに接続します。Home Assistant でトークンを取得してください：開発者ツール → アクション → vomesync.mint_lan_tcp_token（または Vome App の ingress パネル → LAN トンネル → 「トンネルトークンを取得」）。トークンは有効期間が短く、1 つのインスタンスと 1 つのルートに限定されます。

---

設定

設定は環境変数で行います（ローカルの .env も読み込まれます）。.env.example を .env にコピーして値を入力するか、エディターの MCP 設定で変数を設定してください。

変数	デフォルト	説明
HA_URL	—（必須）	ベース URL。例：http://homeassistant.local:8123。
HA_TOKEN	—（必須）	長期アクセストークン（プロフィール → セキュリティ）。
HA_ALLOW_WRITE	off（直接接続）／permissive（ブローカー経由）	ローカルの書き込みガードです。ブローカー経由モードでは、API キーのインスタンスごとのスコープによって決まります（サーバー側で適用）。false に設定すると、ローカルの制限が追加されるだけです。直接接続モードではマスタースイッチとなり、デフォルトは off です。
HA_DENY_DOMAINS	lock,alarm_control_panel,cover,valve,camera（直接接続）／空（ブローカー経由）	書き込みを常に禁止するドメインです。ブローカー経由モードでは、API キーの Sensitive devices 設定によってサーバー側で決まります。ローカルの制限を追加する場合にのみ設定してください。
HA_ALLOW_DOMAINS	(任意)	設定すると、これらのドメインへの書き込みのみが許可されます。
HA_ALLOW_CONFIG_WRITE	off（直接接続）／permissive（ブローカー経由）	オートメーション設定の編集に対するローカルガードです。動作は HA_ALLOW_WRITE と同じです。
NODERED_URL	(無効)	Node-RED エディター／管理用のベース URL。例：http://homeassistant.local:1880。nodered_* ツールが有効になります。
NODERED_TOKEN	—	Node-RED の adminAuth が有効な場合に使用するベアラートークンです。
NODERED_USERNAME / NODERED_PASSWORD	—	トークンを手動で発行したくない場合に、/auth/token 経由でトークンと交換する認証情報です。
VOMEHOME_API_URL	https://vome.io	VomeHome ポータルのベース URL です。
VOMEHOME_TOKEN	(無効)	VomeHome の個人用アクセストークンです。設定すると vomehome_* ツールが有効になります。
VOMEHOME_INSTANCE_ID	(直接接続モード)	HA 呼び出しのブローカー先となるアクティブ／デフォルトのインスタンスです。トークンが設定され、HA_TOKEN が設定されていない場合、HA ツールは VomeHome 経由でルーティングされます（ブローカー経由モード：実際の境界を参照）。実行できる操作は、ポータルで設定されたトークンのインスタンスごとのスコープによって決まります（サーバー側で適用）。
VOMEHOME_INSTANCES	(なし)	起動時に複数のインスタンスを登録するための任意の JSON レジストリです。例：[{"id":"rly-house","label":"home"},{"id":"sbx"}]。インスタンスごとの write／config は任意のローカル制限です（省略するとサーバー側の設定が適用されます）。vomehome_use_instance でインスタンスを切り替えます。1 つのトークンから複数のインスタンスを利用するを参照してください。
VOMEHOME_ALLOW_CREATE	(キー設定に従う)	インスタンス作成に対する任意のローカルガードです。実際の権限は API キーのアカウント全体に適用される作成スコープによって決まります。false に設定すると、ローカルでは作成が常にブロックされます。作成したインスタンスには、そのキーで HA への完全なアクセス権が付与され、セッションのアクティブな接続先になります。
HA_TIMEOUT_MS	15000	HTTP／WebSocket リクエストのタイムアウトです。
MAX_RESULTS	500	リストツールが切り詰める前に返す最大項目数です。
LOG_LEVEL	info	error | warn | info | debug（ログは stderr に出力されます）。

トークンの取得

Home Assistant で、ユーザー名（左下）→ セキュリティタブ → 長期アクセストークン → トークンを作成をクリックします。

---

エディターの設定

これは標準的な stdio MCP サーバーなので、同じバイナリをどこでも使用できます。

Cursor

上記のワンクリックボタンを使うか、プロジェクト内に .cursor/mcp.json を作成します（すべてのプロジェクトで使用する場合は ~/.cursor/mcp.json を作成します）。examples/cursor.mcp.jsonを参照してください。

{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"HA_URL": "http://homeassistant.local:8123",
				"HA_TOKEN": "paste-your-long-lived-token",
				"HA_ALLOW_WRITE": "false"
			}
		}
	}
}

VS Code

.vscode/mcp.json を作成します（examples/vscode.mcp.jsonを参照）。VS Code では、トークンをファイルに保存せずに済むよう、入力を求めることができます。

{
	"inputs": [
		{ "id": "ha_token", "type": "promptString", "description": "Home Assistant token", "password": true }
	],
	"servers": {
		"home-assistant": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"HA_URL": "http://homeassistant.local:8123",
				"HA_TOKEN": "${input:ha_token}"
			}
		}
	}
}

Claude Desktop

claude_desktop_config.json の mcpServers に同じブロックを追加します。

Claude Code：サイドペイン

Claude Codeでは、.mcp.json の同じブロックを使用するか、claude mcp add-json <name> '<entry>' でサーバーを1つずつ追加できます。Vome経由なら、Vomeアプリの Agent タブで取得したキーを使って、2つのコマンドを実行します。

/plugin install vome-connect --marketplace Vortitron/home-assistant-mcp
/plugin install vome-panes --marketplace Vortitron/home-assistant-mcp

最初のコマンドでホームに接続します（キーの入力を求められます）。2つ目のコマンドで4つのペインすべてをインストールします。1つずつ選ぶこともできます。

vome-automation ペインには、Claudeが作業中のオートメーション、保存による変更内容、最新の実行で通ったステップが表示されます。

/plugin install vome-automation --marketplace Vortitron/home-assistant-mcp

これにはClaude Code 2.1.275以降が必要です。それより古いバージョン向けの2コマンド形式、更新を有効にする方法、自動モードで許可する読み取り専用ツールについては、READMEをご覧ください。

ホームのヘルスについては、vome-health にVomeのスコアとチェックで見つかった項目が表示され、Claudeが修正するたびに項目に印が付き、ロールと花火とともに再採点されます。

/plugin install vome-health --marketplace Vortitron/home-assistant-mcp

使いやすいダッシュボードには、vome-dash のペインに自分のダッシュボードを表示できます。ライブ状態、切り替えや調光ができるコントロール、半ブロック表示のカメラ、Claudeが変更したカードが点灯表示されます。

/plugin install vome-dash --marketplace Vortitron/home-assistant-mcp

ESPHome向けの vome-esphome は、Claudeが作業中のデバイスのYAMLから描画したマップと、ビルドの進行状況をリアルタイムで表示するペインを追加します。

/plugin install vome-esphome --marketplace Vortitron/home-assistant-mcp

そして、楽しみのための vome-doom は、house.wad をペインでプレイできるようにします。家がDoomのレベルになり、ランプを撃つと実際に消灯します。

/plugin install vome-doom --marketplace Vortitron/home-assistant-mcp

さらに、楽しみのためだけに、dont-panic はGuideを追加します。エージェントの動作をアニメーション表示するペインで、気ままなGuideの記録をリアルタイムで作成します。料金レベルはREADMEをご覧ください。/guide canned は無料です。

/plugin install dont-panic --marketplace Vortitron/home-assistant-mcp

上記の設定をせずにVome経由でClaude Codeをホームに接続するには、同じマーケットプレイスから vome-connect をインストールしてください。必要なのはキー1つだけです。Home AssistantのVomeアプリにあるAgentタブから、サインアップなしで取得できます。

/plugin install vome-connect --marketplace Vortitron/home-assistant-mcp

複数のHome Assistant

mcpServers 配下の各エントリは、それぞれ独自の環境を持つ個別のサーバープロセスです。そのため、複数のHome Assistantを制御する場合は、それぞれ異なるトークンを使って、インスタンスごとにエントリを追加し、異なる名前を付けます。名前はエディター上のツール名に接頭辞として付加されるため（例：ha-home: ha_list_entities）、エージェントはどの家と通信しているかを常に把握できます。examples/cursor.multi.mcp.json をご覧ください。

{
	"mcpServers": {
		"ha-home": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_token-for-home",
				"VOMEHOME_INSTANCE_ID": "rly-aaaaaaaaaaaa"
			}
		},
		"ha-cottage": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_token-for-cottage",
				"VOMEHOME_INSTANCE_ID": "rly-bbbbbbbbbbbb"
			}
		}
	}
}

ブローカー経由と直接接続のエントリは自由に組み合わせられます（例：ブローカー経由の自宅と、直接接続する HA_URL／HA_TOKEN を使ったラボ環境）。各エントリには、それぞれ独自の安全フラグを設定できます。たとえば、家族が暮らす自宅には読み取り専用トークンを、テストベンチでは書き込みを有効にできます。

1つのトークンで複数のインスタンスを利用する

呼び出しのたびにホームを指定してください。 vomehome_* 以外の各ツールは、オプションの instance_id を受け取ります。指定すると、このセッションが別のホームを対象にしている場合、そのホームから回答するのではなく、呼び出しが拒否されます。ファイルへの書き込みとログインでは、すでに指定が必須です。読み取りでも必要です。再接続したセッションが別のウィンドウで選択されたホームを引き継ぐことがあり、対象外のホームからの「エンティティが見つかりません」や空の履歴は、実際の回答のように見えてしまうためです。

上記のマルチプロセス構成では、トークンごとに1つのプロセスを使用します。同じ VomeHome アカウント（同じトークン）で複数のインスタンスを利用する場合は、代わりに1つのサーバーからすべてを操作し、実行時に切り替えられます。権限はキーに紐づいています。ポータルでインスタンスごとに ha:write / ha:config を付与し、サーバーがそれを適用します。そのため、以下の設定は起動時に把握するインスタンスを指定するものです（さらに、必要に応じてローカルで追加の制限を設定できます）。

{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_your-account-token",
				"VOMEHOME_INSTANCE_ID": "rly-house",
				"VOMEHOME_INSTANCES": "[{\"id\":\"rly-house\",\"write\":false,\"label\":\"home (locked read-only here)\"},{\"id\":\"sbx-plc\",\"label\":\"PLC sandbox\"}]"
			}
		}
	}
}

• VOMEHOME_INSTANCE_ID は、起動時に ha_* ツールが対象とする アクティブ／デフォルト のインスタンスです（自動的に "default" としてレジストリに登録されます）。操作可能な内容は、ポータルで設定したトークンのインスタンスごとのスコープによって決まります。
• VOMEHOME_INSTANCES は、起動時に把握するインスタンスを指定します。トークンはすでにそれらのインスタンスにアクセスできるため、一覧の指定は任意ですが、アクティブな対象を固定したり、ローカル制限を追加したりできます。ここでインスタンスごとに write / config を設定するのは、任意のローカル限定の制限です。省略するとサーバーの設定に従います。false を設定すると、キーで許可されている内容にかかわらず、このマシンではそのインスタンスを読み取り専用にできます（この例では、ローカルでホームをロックしています）。
• vomehome_use_instance は、以降の ha_* 呼び出しで使用するアクティブなインスタンスを切り替えます。vomehome_list_instances は、アクティブなインスタンスと、各インスタンスで有効なアクセス権を表示します。
• インスタンスの作成（vomehome_create_instance）には、キーに作成スコープが必要です。作成したものの所有者はあなたです。 ポータルは、作成に使用したキーに、新しいインスタンスでの Home Assistant へのフルアクセス（ha:read、ha:write、ha:config、ha:files）を付与します。そのため、トークンのページに戻らなくても ha_* ツールを使用できます。他のキーや他のホームの設定は、チェックした内容のままです。このインスタンスも、セッションのアクティブな対象になります。再起動後も把握した状態を保つには、その ID を VOMEHOME_INSTANCES に追加してください。

API キーが唯一の信頼できる情報源であり、最終的な判断はサーバーが行います（キーに必要なスコープがない場合は 403 を返します）。上記のクライアント側フラグは、このマシンでさらに制限することしかできず、トークンで可能な操作の範囲を広げることはありません。

Vome のホスト型エンドポイント（https://vome.io/mcp。インストール不要）では、同じ仕組みを1つの URL で利用できます。セッションは、そのクライアントで最後に切り替えたインスタンスから開始し、その選択はサーバーの再起動後も記憶されます。プロジェクトを常に特定のホームから開始するには、URL に固定してください。

{ "mcpServers": { "vome": { "type": "http", "url": "https://vome.io/mcp?instance=rly-house",
	"headers": { "Authorization": "Bearer vh_your-account-token" } } } }

固定するのはセッションの開始先であり、ロックではありません。vomehome_use_instance で引き続き切り替えられます。この設定が有効なのは、トークンがそのインスタンスにアクセスできる場合に限られます。

検証

npx -y @vortitron/home-assistant-mcp doctor

doctor は REST、WebSocket レジストリ、および（設定されている場合は）ESPHome ダッシュボードを確認し、ヘルスサマリーを表示します。MCP サーバーを起動することはないため、いつでも安全に実行できます。

---

安全性

実際の自宅を対象にしても安全な設計です。

1. デフォルトでは読み取り専用（ダイレクトモード）。 生の HA_TOKEN を使う場合、MCP だけが保護策となるため、HA_ALLOW_WRITE=true になるまで、状態を変更するすべてのツールが実行を拒否します。ブローカーモードでは、権限は VomeHome API キーに設定され、インスタンスごとにサーバー側で適用されます（ブローカーモードを参照）。
2. ドメイン拒否リスト。 書き込みを有効にしていても、機微なドメイン（ロック、アラーム、カバー、バルブ、カメラ）はブロックされます。ダイレクトモードでは HA_DENY_DOMAINS から削除します。ブローカーモードでは、VomeHome API トークンのページにある Sensitive devices で、該当するドメインにチェックを入れます。
3. 任意の許可リスト。 HA_ALLOW_DOMAINS を設定すると、特定のドメインのみを許可できます。
4. ドメイン横断ガード。 ha_call_service は、data 内のどこにネストされていても、ターゲットエンティティ ID を含む、すべてのターゲットエンティティのドメインをチェックします。そのため、汎用サービス（例：homeassistant.turn_on）を使って拒否されたドメインにアクセスすることはできません。拒否リストまたは許可リストが有効な場合、エリア／デバイス／ラベルを対象とする汎用サービスは拒否されます。これらのセレクターはサーバー側で解決され、ここではチェックできないためです。代わりに、ターゲットエンティティ ID を指定するか、ドメイン固有のサービス（例：light.turn_on）を使用してください。
5. 設定書き込み用の独立したスコープ。 自動化 YAML の編集には、専用の ha:config スコープ（ブローカーモード）または HA_ALLOW_CONFIG_WRITE=true（ダイレクトモード）が必要です。
6. VomeHome のガード。 インスタンスの再起動や作成には、API キーに対応するスコープが必要です（サーバー側で適用）。任意の VOMEHOME_ALLOW_CREATE クライアントフラグを使って、ローカルでさらに制限することもできます。VomeHome トークンのスコープはサーバー側で適用され、自分のアカウントのみに限定されます。

また、ツールには MCP ヒント（readOnlyHint、destructiveHint）が付与されており、クライアントが破壊的な呼び出しの前に警告できます。

書き込みガードが保護する範囲と、保護しない範囲

このガードはこれらのツールが実行できることを制限します。MCP サーバーがエージェントにとって Home Assistant への唯一のアクセス経路である場合、強力な保護策になります。ただし、これは暗号学的な境界ではありません。Home Assistant の長期トークンは完全なアクセス権を付与するため、そのトークンも持つエージェントは、Home Assistant API を直接呼び出してガードを迂回できます。そのため、トークンはエディターの MCP 設定（できれば ~/.cursor/mcp.json のように、エージェントが読み取れるリポジトリの外）に保管し、エージェントが参照するファイルには置かないでください。

本当の境界を設けるには、代わりにエージェントの接続先としてVomeHomeを指定します。エージェントが保持するのは失効可能な VOMEHOME_TOKEN のみで、強力な HA 認証情報は、アクセス制御と監査が行われるサーバー側に保管されます。これにより、エージェントがポリシーを迂回できなくなります。ブローカーモードを参照してください。

---

ブローカーモード（本当の境界）

ダイレクトモードは便利ですが、エージェントが HA トークンも同時に持っていない場合に限り、書き込みガードが役立ちます。ブローカーモードなら、その抜け道を塞げます。エージェントに渡すのは、失効可能でスコープが設定された VomeHome トークンとインスタンス ID だけです。Home Assistant トークンは一切渡しません。すべての HA の読み取り／書き込みは VomeHome ポータル経由でプロキシされます。ポータルでは次の処理が行われます。

• HA の認証情報をサーバー側に保管するため、エージェントがそれを見ることはありません。
• トークンごと、インスタンスごとに読み取り／書き込み／設定の権限を適用します。あるインスタンスに対する ha:write を持たないトークンでは、どのような使い方をしても、そのインスタンスを実際に変更することはできません。
• 汎用サービス経由の場合も含め、機微なドメイン（ロック、アラームなど）をサーバー側でブロックします（homeassistant.turn_on でロックにアクセスすることはできません）。
• 呼び出しの許可／拒否を問わず、すべての呼び出しを実行したトークンと紐付けて監査します。

ポリシーはサーバー側にあるため、エージェントが迂回することはできません。これが、保護策と境界の違いです。

{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_paste-your-token",
				"VOMEHOME_INSTANCE_ID": "your-instance-id"
			}
		}
	}
}

ポータルの Account → API tokens でトークンを発行します。ここで、インスタンスごとに Home Assistant の操作（ha:write）やオートメーション設定の編集（ha:config）を許可するかどうかを設定できます。また、キーの発行後も許可内容を編集できます。キーが唯一の信頼できる情報源であり、MCP はキーを渡すだけです。インスタンス ID はダッシュボードまたは vomehome_list_instances ツールで確認してください。（ポータルのトークンページでは、このトークンのみを使うスニペットが自動生成されます。）

vomehome_* ツールのトークンスコープ。 インスタンス管理ツール（vomehome_list_instances、_get_instance、_use_instance、_get_login_url）には instances:read スコープが必要です。また、vomehome_create_instance には instances:write が必要です（このスコープには読み取り権限も含まれます）。HA スコープ（ha:read／ha:write／ha:config）だけで発行されたトークンは、Home Assistant の呼び出しを仲介できますが、インスタンス管理ツールでは 403 … missing required scope(s): instances:read が返されます。エージェントにサンドボックスを起動させる場合は、instances:write を含めてトークンを発行してください。インスタンスを作成すると、そのキーには新しいインスタンスに対する完全な ha:* アクセス（ha:read、ha:write、ha:config、ha:files）が自動的に付与されます。既存のホームには、選択した許可内容が引き続き適用されます。仲介モードでは、ローカルの VOMEHOME_ALLOW_CREATE 環境変数フラグは不要です（ローカルでブロックしたい場合のみ false を設定してください）。 デフォルト（読み取り専用）トークンには、すでに instances:read が含まれています。403 が発生するのは、インスタンススコープなしで HA アクセスだけに制限したトークンの場合です。

仲介モードでは、日常的な操作（エンティティの一覧表示／取得、サービスの一覧表示、サービスの呼び出し、設定の読み取り、テンプレートのレンダリング）に加えて、オートメーションの編集もプロキシ経由で実行できます。 ha_get_automation、ha_set_automation、ha_delete_automation、ha_check_config が対象です。Lovelace ダッシュボードも仲介されます。 ha_list_dashboards、ha_get_dashboard、ha_save_dashboard、 ha_create_dashboard、ha_delete_dashboard（書き込みには ha:config が必要です）が対象です。オートメーションの読み取りには ha:read が必要です。オートメーションの書き込みには、そのインスタンスのトークンに別途 ha:config スコープが必要で、サーバー側で強制されます。クライアント側の書き込みガード（HA_ALLOW_WRITE／HA_ALLOW_CONFIG_WRITE）は仲介モードではデフォルトで許可されており、追加のローカル制限として任意で設定できます。レジストリツール（エリア／デバイス）、ログ、履歴を使うには、現時点では引き続きダイレクトモードが必要です。

リレー経由の ESPHome。 リレー接続済みの Home Assistant（Vome コンポーネントのアウトバウンドトンネル経由で接続された自分の HA）に仲介接続すると、ESPHome も利用できます。デバイスの一覧表示、YAML の読み取りと書き込み、ストリーミングコマンド（esphome_validate／_compile／_upload／_logs／_clean）が含まれ、これらはポーリングジョブとしてリレー経由で実行されます。読み取りには ha:read が必要です。YAML の書き込み、ビルド、フラッシュには、インスタンスの ha:config スコープが必要です。利用できるのはこの方法のみです。詳しくはESPHomeを参照してください。

ご自身の Home Assistant を接続する。 仲介先のインスタンスは VomeHome VM である必要はありません。VomeHome ポータルの Account → Connect HA で、長期アクセストークンを使って、ご自身でホストする Home Assistant（パブリック URL／外部 IP、または Nabu Casa Remote UI）を接続できます。接続すると、vomehome_list_instances に ext-… ID で表示されます。これを VOMEHOME_INSTANCE_ID に設定すると、同じスコープ制限、拒否リスト、監査の境界が適用されます。HA トークンは VomeHome サーバー上に保持され、エージェントに渡されるのは失効可能な VomeHome トークンのみです。

エージェント向けの情報。 VomeHome は、これらすべての情報（登録方法、トークンの発行方法、試用 VM の起動方法、ホーム HA の接続方法、/api/v1 の仕様）を機械可読なインデックスとして公開しています。Gopher-over-HTTPS メニューは https://vome.io/.well-known/agent.gopher、llms.txt 形式は https://vome.io/llms.txt で確認できます。これを読んでいるエージェントは、まずこちらを参照してください。

---

エージェントのワークフロー例

• 「リビングの照明は点いていますか？」 → ha_list_entities（ドメイン light、 エリア living room）。
• 「日没後にのみ true を返すよう、このテンプレートを修正してください」 → ha_render_template で反復します。
• 「玄関の照明を 30% にしてください」 → ha_call_service（light.turn_on、 brightness_pct: 30）。書き込みの有効化が必要です。
• 「朝のオートメーションを修正してください」 → ha_get_automation → 編集 → ha_set_automation → ha_check_config → ha_trigger_automation。
• 「この ESPHome ノードにセンサーを追加して、書き込んでください」 → esphome_get_config → esphome_edit_config（新しいファイルの場合は esphome_save_config）→ esphome_validate → esphome_upload。
• 「Node-RED の『Heating』タブを整理してください」 → nodered_get_flows（タブ ID を確認） → nodered_get_flow → ノードを編集 → nodered_update_flow。
• 「サンドボックスを起動して開いてください」 → vomehome_create_instance → vomehome_get_instance（ステータスをポーリング）→ vomehome_get_login_url（リンクを開く）。
• 「Hue のインテグレーションでエラーが発生するのはなぜですか？」 → ha_get_system_log （logger: "hue"）→ exception_summary を確認 → include_exception: true を指定して ha_get_system_log を再度実行し、 スタック全体を取得します。
• 「朝のオートメーションが実行されなかったのはなぜですか？」 → ha_get_trace （item: "automation.morning"）→ failed_at を確認します。

---

ログを使ったデバッグ

確認する順序のおおよその目安として、次の 4 つの場所があります。

質問	ツール
現在、何が壊れていますか？	ha_get_system_log
このオートメーションが何もしなかったのはなぜですか？	ha_get_trace
アドオン／ホストでは何が起きましたか？	ha_get_supervisor_log
このエンティティに何が起き、いつ発生しましたか？	ha_get_logbook / ha_get_history

ha_get_error_log ではなく、まず ha_get_system_log を使ってください。 Home Assistant の構造化エラーストアを読み取るため、500 回記録された同じ障害も、count: 500、 source のファイル名と行番号、初回／最終確認時刻を含む 1 つのレコードになります。 生ログを末尾まで読み取ると、より少ない情報を得るために、はるかに多くのトークンを消費します。 完全なトレースバックはデフォルトでは省略されますが、実際の例外名を示す最終行である exception_summary は取得できます。どのエントリが重要かわかったら、include_exception: true を指定してください。

再現ループ。 問題を任意のタイミングで発生させられる場合、履歴を調べる必要はありません。再現時の内容だけがログに残るようにします。

1. ha_set_log_level（integration: "hue", level: "debug"）— ログレベルをグローバルではなく、 対象のインテグレーションだけでデバッグに設定します。
2. ha_clear_system_log。
3. 問題を再現します（ha_call_service、ha_trigger_automation など）。
4. ha_get_system_log — 返された内容はすべてステップ 3 によって発生したものです。

ログレベルは実行時のみ有効で、再起動するとリセットされます。直接モードでは、書き込みツールの両方に HA_ALLOW_WRITE=true が必要ですが、HA_ALLOW_CONFIG_WRITE は不要です。また、ドメインの拒否／許可リストは適用されません。これらはエンティティではなく、ログの処理方法を変更するものだからです。

トレースならログでわからないことも確認できます。 条件が false を返したオートメーションは、 ログをまったく出力しませんが、トレースには記録されます。ha_get_trace はデフォルトで直近の実行を対象とし、 トリガーと順序どおりのステップに加えて、エラーが発生した、または false と評価された最初のステップを示す failed_at を返します。Home Assistant が保持するトレースはアイテムごとに数件（デフォルトで 5 件）に限られ、 最後の再起動より前のトレースは残りません。そのため、ha_list_traces が何も返さない場合は、 通常「トリガーしてから、もう一度確認してください」ということです。

ESPHome に関する注意事項

• REST エンドポイント（/devices、/edit）は、YAML の一覧表示と読み書きに使用されます。これらは VomeHome リレー経由でも直接でも動作します。
• validate、compile、upload、logs、clean は、ダッシュボードの多重化された /ws API 経由で実行されます。リレー経由では ジョブ として仲介されます。ポータルがジョブを開始し、このクライアントがポーリングするため、間の通常の HTTP タイムアウトを超える数分間のコンパイルも完了できます。
• ダッシュボードプロトコルは Vome コンポーネントが管理します。 ESPHome はダッシュボードを esphome-device-builder に分割し、コマンドごとの WebSocket（/validate、/logs、…）と /edit REST エンドポイントを単一の /ws ソケットに置き換えました。残っているレガシーエンドポイントは、上流のドキュメントで非推奨とされています。このコンポーネントは /ws を、リレーが転送する安定した行／終了コードのストリームに変換するため、このクライアント、ポータル、リレーが ESPHome の変更を意識することはありません。ビルドはダッシュボードのジョブキューを通じて実行されるため、エージェントが開始したビルドも、エージェント自身の「ファームウェアタスク」パネルに表示されます。
• Vome アドオン 0.3.30 以降が必要です。古いコンポーネントは、ダッシュボードが応答しなくなったプロトコルを使用します。エラーには ESPHome のせいにするのではなく、その旨と必要なバージョンが示されます。
• ダッシュボードに直接接続するより、リレーを使う方法が推奨されます。どちらでも動作する場合も同様です。直接接続すると、ポータルによるインスタンスごとのスコープチェックと監査ログを迂回してしまいます。トークンが無効化されても、エージェントとネットワークを共有していたデバイスをフラッシュできてしまいます。また、アドオンの Web ポートが無効で、Supervisor と localhost からしかアクセスできないデフォルトの HAOS インストールで使えるのは、この方法だけです。
• 検出機能（src/esphome/discovery.ts）は、リレーがなく、迂回するポリシーレイヤーもない直接接続モードで、ダッシュボードを検出します。有効なモードを確認するには esphome_dashboard_info を呼び出してください。接続可能な対象がない場合は、試行したすべてのアドレスと、それぞれの失敗理由も確認できます。
• ダッシュボードパスワードが設定されている場合、ダッシュボードは独自の Cookie／XSRF で WebSocket コマンドを認証します。そのため、これらのコマンドが動作するのは、パスワードが設定されていないダッシュボード、または信頼できるネットワーク上／認証を終端するプロキシの背後からアクセスできるダッシュボードです。ここでのトークン／ベーシック認証は、後者の場合にのみ役立ちます。
• esphome_upload はフラッシュ前に検証を行います。不適切なビルドを適用したデバイスは、ケーブルで接続できる人が現れるまでオフラインになるため、先に手軽なチェックを実行します。省略するには skip_validate: true を渡してください。

---

Node-RED に関する注意事項

• HA の Node-RED アドオンは、ポート 1880（http://homeassistant.local:1880）でエディターを公開します。NODERED_URL にその URL を指定してください。
• アドオンに**認証情報シークレット／adminAuth**が設定されている場合は、NODERED_TOKEN を指定してください（または NODERED_USERNAME／NODERED_PASSWORD を指定すると、クライアントがトークンと交換します）。信頼できるネットワーク上のみから、または HA ingress／認証を終端するプロキシの背後からアクセスできるアドオンでは、ここで認証を設定する必要はありません。
• nodered_set_flows はすべてを書き換えます。日常的な編集には nodered_create_flow／nodered_update_flow を使用してください。nodered_get_flows から取得した rev を渡すと、エディターで同時に行われた変更を検出でき、黙って上書きするのを防げます。
• Node-RED のフローはプレーンな JSON なので、代替フロントエンド（PLC 形式のラダー、Scratch／Blockly）の対象として自然です。この検討は VomeHome リポジトリ（docs/alt_interfaces_plan.md）にあります。

開発

npm run dev          # run from source with tsx (watch)
npm run build        # compile to dist/
npm test             # vitest
npm run lint         # eslint
npm run typecheck    # tsc --noEmit

構成：

src/
	index.ts              # entry: MCP stdio server + `doctor`/`tunnel` CLI
	config.ts             # env parsing + validation
	safety.ts             # write-guard policy
	logger.ts             # stderr logger
	ha/                   # Home Assistant REST + WebSocket + brokered clients
	esphome/              # ESPHome dashboard client
	nodered/              # Node-RED admin API client
	vomehome/             # VomeHome portal client
	tools/                # one module per tool group
	cli/doctor.ts         # connectivity check
	cli/tunnel.ts         # raw-TCP LAN tunnel client (RDP, etc.)
tests/                  # vitest unit tests

---

ロードマップ

• VomeHome 仲介による HA アクセス（真の境界）— リリース済み（MVP）。 HA の読み取り／書き込みを、取り消し可能な VOMEHOME_TOKEN を使って VomeHome 経由でプロキシできるため、HA の認証情報がエージェントに渡ることはなく、読み取り専用／ドメイン拒否／監査ポリシーがサーバー側で適用されます。オートメーションの編集と ESPHome REST のサブセットも仲介されます（後者はリレー接続された HA 経由です）。仲介モードを参照してください。次の予定：仲介経由のレジストリ（エリア／デバイス）と、ポータルでのトークンごとの監査ビュー。
• VomeHome のテスト用インストール。 vomehome_* ツールでは、インスタンスの一覧表示、作成、再起動、起動がすでにできます。次の予定：新しく作成したサンドボックスを自動的に HA_URL／HA_TOKEN に設定し、実際の自宅環境に変更を加える前に、エージェントがそこで変更を試してから、うまくいったものを反映できるようにします。（project_outline.md に記載されたポータル API エンドポイントが必要です。）
• リレー経由の ESPHome — リリース済み。 ビルド、フラッシュ、デバイスログはポーリングジョブとして仲介されるため、リモートエージェントはインバウンドへの露出なしに、すべてのコマンドの前にスコープチェックと監査を行ったうえでハードウェアにフラッシュできます。次の予定：デバイスの導入（/import ＋ウィザードのフロー）。これにより、エージェントは UI 操作なしで、新品のボードを未フラッシュの状態から動作するエンティティにできます。
• Node-RED — フローの読み取り／書き込み／デプロイはリリース済みです。次の予定：管理 API を VomeHome 経由で仲介し（HA および ESPHome REST のサブセットと同様に）、リレー接続された自宅環境で直接到達可能な Node-RED URL を不要にすることと、デプロイ前のフローの 差分／検証 ステップ。
• エンティティ／エリア用の MCP リソース（ツールに加えて）。
• リモート利用向けのオプションの HTTP/SSE トランスポート。

---

ライセンス

MIT © Vortitron