ha-mcp

破壊的変更（v7.3.0）： ha_config_set_yaml はベータ版に移動しました。

---

---

🚀 はじめに

ha-mcp の実行には、HA-MCP カスタムコンポーネントを推奨します。HACS を通じて Home Assistant にインストールすると、サーバー全体がプロセス内で動作し、Home Assistant OS、Supervised、Container、Core を含むすべての Home Assistant インストールタイプで、すべての機能を利用できます。どの場合でも最も簡単にセットアップでき、セットアップ時に管理者アクセストークンと、クライアントの接続方法を指定します。

HACS 経由で Home Assistant に追加する（推奨インストール方法）：

クイックスタート：

以下のセットアップ手順はバージョン 9.0.0（2026 年 10 月 28 日）以降を対象としています。それ以前のバージョンでは、管理者アカウントの手順がない、より短いセットアップフォームが表示されます。

1. HACS から HA-MCP Custom Component をインストールします。上記のバッジをクリックするか、HACS で Integrations → ⋮ → Custom repositories を開き、https://github.com/homeassistant-ai/ha-mcp を追加して（カテゴリ：Integration）、Download をクリックします。 以前の homeassistant-ai/ha-mcp-integration リポジトリからすでにインストールしていますか？同じリリースが引き続き提供されるため、変更は不要です。
2. Home Assistant を再起動します。
3. サーバーがどの管理者アカウントとして動作するかを決めます。自分のアカウントで有効期間の長いアクセストークンを作成する方法（プロフィール → Security → Long-lived access tokens → Create token。漏えいするとどこからでも使用でき、サーバーによる変更は自分の名前で表示されます）と、より安全な方法として、Settings → People → Add person から HA-MCP 専用のアカウントを作成し、Allow login、Local access only、Administrator を有効にする方法があります。後者の場合、自分のログイン情報は絶対に使用しないでください。
4. Settings → Devices & Services → Add Integration に移動し、HA-MCP Custom Component を検索して HA-MCP Server を選択します。トークンを貼り付けるか、HA-MCP 用に作成したアカウントのユーザー名とパスワードを入力します（HA-MCP がトークンを作成します）。クライアントの接続方法を選択します。Remote access through Home Assistant（まずは最も簡単な Secret URL をお使いください。Home Assistant sign-in を選ぶとログインが必要になります）および／または Network access: Local network を選択し、Submit をクリックします。どちらも初期状態では無効になっているため、別のデバイス上のクライアントには、いずれかを有効にする必要があります。
5. エントリーの Configure 画面（Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure）から接続 URL をコピーします。サーバーの起動を知らせる通知にも、この画面へのリンクが表示されます。
6. その URL を AI クライアントに貼り付ければ完了です。

接続 URL。 Configure 画面には、リモートクライアント用の Home Assistant webhook URL が表示されます。Nabu Casa 経由、または Home Assistant にすでに向けられているリバースプロキシ経由の場合は https://<your-ha-domain>/api/webhook/<webhook-id> です（ローカルでは http://<ha-host>:8123/api/webhook/<webhook-id>）。同じネットワーク上のクライアントからは、サーバーに http://<ha-ip>:9584/private_<random> で直接接続することもできます。

• 他のインストール方法の代わりになります： インプロセスサーバーは、単独で動作する完全な ha-mcp インストールです。アプリ（アドオン）、Docker、uvx/PyPI（stdio）方式の代わりとなります。実行するのは 1 つだけにしてください。インプロセスサーバーと別のインストールを同時に実行しないでください。
• ローカルのみで使用しますか？ セットアップ時にリモートアクセスを無効のままにするか、エントリーのオプションで Remote access via webhook をオフにしてください。webhook は一切登録されず、直接ポートとサイドバーパネルは引き続き使用できます。
• 設定パネル： サーバーの実行中は、ツール、機能フラグ、バックアップ、テーマを管理するための管理者専用 HA-MCP パネルが Home Assistant のサイドバーに表示されます。
• 任意の認証： Authentication mode を ha_auth に設定すると、認証情報としてシークレット URL を使わず、Home Assistant アカウントへのサインインが必要になります。
• 手動インストール（HACS を使用しない場合）： このリポジトリから custom_components/ha_mcp_tools/ を Home Assistant の config/custom_components/ ディレクトリにコピーしてから、Home Assistant を再起動し、上記の手順でインテグレーションを追加します。

2 つ目のエントリータイプである File & YAML services entry（HA-MCP File & YAML Tools）が必要なのは、ha-mcp のオプトイン方式のファイル編集ツールと YAML 編集ツール（機能フラグ。初期状態では無効）を有効にする場合のみです。それ以外の場合は追加しないでください。必要になったときにいつでも追加できます。どのサーバータイプ（インプロセス、アプリ、Docker、stdio）でも動作します。

インプロセスサーバーのドキュメント全文 → · クライアント固有の設定用セットアップウィザード →

🏠 Home Assistant アプリ（アドオン）

ha-mcp を Home Assistant の**アプリ（アドオン）**として実行したいですか？ Home Assistant OS および Supervised インストールでは、次善の方法です。アクセストークンの管理は不要で、ローカルネットワーク上、またはリモートアクセス用に設定された Claude Desktop、Claude.ai、ChatGPT、その他の MCP クライアントで動作します。

1. Home Assistant インスタンスにリポジトリを追加します。

   

   アプリストアが開き、リポジトリ追加ダイアログが表示されない場合（既知の Home Assistant の問題）、手動で追加してください。設定 → アプリ → アプリをインストール → ⋮ → リポジトリを開き、https://github.com/homeassistant-ai/ha-mcp を貼り付けます。

2. 設定 → アプリ → アプリをインストールから**「Home Assistant MCP Server」**をインストールし、開始をクリックします。（Home Assistant 2026.2 では「アドオン」が「アプリ」に名称変更されました。旧バージョンでは「アドオンストア」です。）

3. ログタブを開き、固有の MCP URL を確認します。

4. AI クライアントをその URL に接続します。トークンや認証情報の設定は不要です。

アプリのドキュメント全文 →

⚠️ クライアントごとに、インストール方法は必ず1つだけ設定してください。 カスタムコンポーネント、アプリ、Docker/PyPI、ローカル stdio は、同じサーバーを実行するための独立した方法です。いずれか1つを選び、その単一の URL を AI クライアントに指定してください。同じクライアントに同一サーバーのエントリーを2つ残しておくと（たとえば、アプリまたはコンポーネントの URL に加えて、HOMEASSISTANT_URL / HOMEASSISTANT_TOKEN を設定したローカルの uvx ha-mcp@latest エントリーを残すなど）、接続がハングする既知の原因になります。

その他のインストール方法

Home Assistant の外部でサーバーを実行します。アプリを実行できない Container／Core インストールや、別のホストを使う場合に便利です。セットアップウィザードでは、それぞれのクライアントに合わせた正確な設定を生成できます。

• Docker（HTTP サーバー）： ghcr.io/homeassistant-ai/ha-mcp を HTTP モードで実行し、Home Assistant の URL と長期間有効なトークン（管理者のトークンを推奨します。管理者以外のトークンも制限付きで使用できます）を指定して、クライアントをシークレット URL に接続します。完全なコマンドとクライアントごとの設定については、セットアップウィザードを参照してください。

• PyPI／uvx（HTTP サーバー）： 公開されている ha-mcp パッケージを uvx ha-mcp@latest（または pip）で実行し、同じ方法でストリーミング可能な HTTP サーバーとして使用します。詳細はセットアップウィザードを参照してください。

• ローカル stdio（推奨しません）： 自分のマシン上で stdio 経由で ha-mcp を実行します。以下の デモサーバー セクションにあるワンコマンドインストーラーは、この方法を使用します。セットアップウィザードでは、自分の Home Assistant への接続方法を説明しています。

• OIDC 認証： シークレット URL の代わりに、外部の ID プロバイダー（Authentik、Keycloak、Auth0 など）でリモートアクセスを保護します。認証済みのユーザーは全員、サーバーの Home Assistant 認証情報を共有します。OIDC モードを参照してください。

  ⚠️ stdio には既知のトランスポートの問題があります。 stdio トランスポートには、ストリーミング可能な HTTP では発生しない接続の問題があります（#1713）。デモやテスト目的で試す場合にのみ推奨します。実際の環境では、カスタムコンポーネントまたは上記の HTTP 方式を使用してください。

🌐 リモートアクセス（Nabu Casa／Webhook Proxy アプリ／OpenAI Tunnel）

HA-MCP カスタムコンポーネントを使用していますか？ Webhook Proxy は不要です。コンポーネントには、リモートアクセス用の Webhook が組み込まれています（上部の はじめに クイックスタートを参照）。プロキシは アプリ 用です（mcp_server_url オプションを使って、別の外部サーバーの前段に置くこともできます）。以下の OpenAI Tunnel は別のもので、Home Assistant にまったくパブリックアクセスできない場合（Nabu Casa もリバースプロキシもない場合）に、どのインストール方法でも使用できます。

Home Assistant を指す Nabu Casa または別のリバースプロキシをすでにお持ちですか？Webhook Proxy アプリは既存の設定を経由して MCP トラフィックをルーティングするため、別のトンネルやポートフォワーディングは不要です。

1. MCP Server アプリ（上記を参照）と、同じストアから Webhook Proxy アプリをインストールします
2. Webhook Proxy を起動し、プロンプトが表示されたら Home Assistant を再起動します
3. アプリのログから Webhook URL をコピーします：

   MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx
   

4. その URL を使って AI クライアントを設定します

その他のリモートアクセス方法（Cloudflare Tunnel、カスタムリバースプロキシ）については、セットアップウィザードを参照してください。

ファイアウォールの背後にある ChatGPT／Codex（OpenAI Tunnel）。 ChatGPT コネクターでは通常、パブリックアクセス可能な URL が必要です。URL を公開できない（または公開したくない）場合は、コミュニティ製の OpenAI Tunnel for HA-MCP 統合（@norpol 作）が、Home Assistant 内で OpenAI の tunnel-client を実行し、ローカル MCP サーバーの URL を送信専用接続で OpenAI がホストするトンネルに接続します。ポートフォワーディング、リバースプロキシ、パブリック URL は不要です。ha-mcp の URL を指定し、同じトンネル ID に ChatGPT コネクターを接続します。FAQ の項目と #1811を参照してください。

Webhook Proxy のドキュメント →

### 🧪 デモサーバー（Windows / macOS / Linux）

ご自身の Home Assistant に接続する前に ha-mcp を試してみませんか？ 有料サブスクリプションは不要です。 以下のワンコマンドスクリプトを使うと、ホストされたデモ環境へのローカルな stdio 接続がセットアップされ、数分で動作を確認できます。各スクリプトの ご自身の Home Assistant に接続リンクでは、お使いのインスタンスへの接続方法を確認できます。

🍎 macOS

1. claude.ai にアクセスしてサインインします（または無料アカウントを作成します）
2. ターミナルを開き、次を実行します：

   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh
   

3. Claude Desktop をダウンロードします（または再起動します：Claude メニュー → 終了）
4. Claude に次のように尋ねます：「Home Assistant が見えますか？」

これでデモ環境に接続できました！ご自身の Home Assistant に接続 →

🐧 Linux

Anthropic は Linux 用の Claude Desktop を提供していないため、次のいずれかの方法を選んでください：

Claude Desktop — コミュニティビルドを使えば無料です：

1. コミュニティ版の Linux 用 Claude Desktop をインストールし、無料の claude.ai アカウントでサインインします
2. ターミナルを開き、次を実行します：

   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh
   

3. Claude Desktop を再起動してから、次のように尋ねます：「Home Assistant が見えますか？」

Claude Code — 公式 CLI。有料の Claude プランが必要です：

1. Claude Code をインストールします：curl -fsSL https://claude.ai/install.sh | bash
2. ha-mcp を設定してから、claude を実行します：

   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code
   

3. claude を起動し、/mcp を実行して接続を確認してから、次のように尋ねます：「Home Assistant が見えますか？」

Linux の詳細ガイド →

🪟 Windows

1. claude.ai にアクセスしてサインインします（または無料アカウントを作成します）
2. Windows PowerShell（スタートメニューから）を開き、次を実行します：

   irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex
   

3. Claude Desktop をダウンロードします（または再起動します：ファイル → 終了）
4. Claude に次のように尋ねます：「Home Assistant が見えますか？」

これでデモ環境に接続できました！ご自身の Home Assistant に接続 →

🧙 15 以上のクライアント向けセットアップウィザード

Claude Code、Gemini CLI、ChatGPT、Open WebUI、VSCode、Cursor などに対応しています。

問題が発生しましたか？ **よくある質問とトラブルシューティング**をご確認ください。

---

💬 これを使って何ができますか？

Claude に自然な言葉で話しかけるだけです。実際の例をいくつか紹介します：

あなたの指示	実行される内容
「日没時に玄関の照明をつけるオートメーションを作成して」	適切なトリガーとアクションを設定してオートメーションを作成します
「ダッシュボードに天気カードを追加して」	新しいカードを追加して Lovelace ダッシュボードを更新します
「モーションセンサーのオートメーションが動かないので、デバッグして」	実行トレースを分析し、問題を特定して、修正方法を提案します
「朝のルーティンのオートメーションでコーヒーメーカーもつけるようにして」	既存のオートメーションを読み込み、新しいアクションを追加して更新します
「映画モードを設定するスクリプトを作成して：照明を暗くし、ブラインドを閉じて、テレビをつけて」	一連のアクションを含む再利用可能なスクリプトを作成します

設定にかける時間を減らして、スマートホームを楽しむ時間を増やしましょう。

---

✨ 機能

カテゴリ	機能
🔍 検索	あいまいなエンティティ検索、詳細な設定検索、システム概要
🏠 制御	任意のサービス、一括デバイス制御、リアルタイムの状態
🔧 管理	自動化、スクリプト、ヘルパー、ダッシュボード、エリア、ゾーン、グループ、カレンダー、ブループリント
📊 監視	履歴、統計、カメラのスナップショット、自動化のトレース、ZHA デバイス
💾 システム	バックアップ／復元、更新、アプリ、デバイスレジストリ
🔒 安全性	読み取り専用モードの切り替え、ツールごとの有効化／無効化、ツールのセキュリティポリシー（ユーザーの承認）、編集時の自動バックアップ

Template ヘルパーの編集バックアップは、HA-MCP カスタムコンポーネントを通じて永続化されたオプションを取得します。取得には、Server エントリまたは File & YAML Tools エントリを使用します。ヘルパーの編集、一般的な統合オプションの編集、削除では、安定した config-entry ID とエンティティ ID／名前の対応関係を取得します。シークレットのマスキングが不完全な場合、取得は拒否されます。既存のヘルパーを復元するには、新しい安全バックアップが必要です。また、スナップショットに存在しないオプション設定は削除され、永続化されたオプションが検証されます。

Template バックアップの一覧表示と一括削除では、取得時に entity_id として返される config-entry ID で絞り込んでください。取得ではエンティティの別名を指定できますが、履歴の絞り込みには安定した config-entry ID を使用します。再作成時には、新しい config-entry ID と保存されたエンティティの対応関係が別々に報告されます。

元のエントリが削除されている場合、復元によってヘルパーが再作成され、新しい config-entry ID が報告されます。保存されたエンティティ ID とカスタム名は、利用可能であれば復元されます。エンティティ ID がすでに使用されている場合、作成前に処理が拒否されます。エンティティのメタデータがない古いスナップショットでは、名前変更されたエンティティ ID を保持できません。作成後に競合または検証エラーが発生した場合、新しいヘルパーと元のバックアップは保持され、確認用に新しいエントリが結果に報告されます。その他のエンティティ／デバイスレジストリ設定は復元されません。同じサーバーを介したヘルパーと統合の編集は、復元が完了するまで待機します。それ以外の Home Assistant クライアントは、この調整の対象外です。復元に失敗した場合や結果が不確かな場合は、その結果と安全上の拒否理由が報告されます。再試行する前に、現在のヘルパーを確認してください。

ツール一覧（全87ツール）

| カテゴリー | ツール | |----------|-------| | **アプリ（アドオン）** | `ha_get_app`, `ha_manage_app` | | **エリアとフロア** | `ha_list_floors_areas`, `ha_remove_area_or_floor`, `ha_set_area_or_floor` | | **Assist** | `ha_manage_pipeline` | | **オートメーション** | `ha_config_get_automation`, `ha_config_remove_automation`, `ha_config_set_automation` | | **ブループリント** | `ha_manage_blueprints` | | **カレンダー** | `ha_config_get_calendar_events`, `ha_config_remove_calendar_event`, `ha_config_set_calendar_event` | | **カメラ** | `ha_get_camera_image` | | **ダッシュボード** | `ha_get_dashboard_screenshot` *(ベータ)* | | **ダッシュボード** | `ha_config_delete_dashboard_resource`, `ha_config_delete_dashboard`, `ha_config_get_dashboard`, `ha_config_list_dashboard_resources`, `ha_config_set_dashboard_resource`, `ha_config_set_dashboard` | | **開発者** | `ha_dev_manage_server`, `ha_dev_manage_settings` | | **デバイスレジストリ** | `ha_get_device`, `ha_remove_device`, `ha_set_device` | | **エネルギー** | `ha_manage_energy_prefs` | | **エンティティレジストリ** | `ha_get_entity_exposure`, `ha_get_entity`, `ha_remove_entity`, `ha_set_entity` | | **ファイル** | `ha_delete_file` *(ベータ)*, `ha_list_files` *(ベータ)*, `ha_read_file` *(ベータ)*, `ha_write_file` *(ベータ)* | | **グループ** | `ha_config_list_groups`, `ha_config_remove_group`, `ha_config_set_group` | | **HACS** | `ha_get_hacs_info`, `ha_manage_hacs` | | **ヘルパーエンティティ** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_remove_helpers_integrations` | | **履歴と統計** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs` | | **インテグレーション** | `ha_get_integration`, `ha_get_system_health`, `ha_set_integration` | | **ラベルとカテゴリー** | `ha_config_get_category`, `ha_config_get_label`, `ha_config_remove_category`, `ha_config_remove_label`, `ha_config_set_category`, `ha_config_set_label` | | **Matter** | `ha_manage_radio` | | **シーン** | `ha_config_get_scene`, `ha_config_remove_scene`, `ha_config_set_scene` | | **スクリプト** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` | | **検索と検出** | `ha_get_overview`, `ha_get_state`, `ha_search` | | **サービスとデバイスの制御** | `ha_bulk_control`, `ha_call_event`, `ha_call_service`, `ha_get_operation_status`, `ha_list_services` | | **システム** | `ha_config_get_yaml` *(ベータ)*, `ha_config_set_yaml` *(ベータ)*, `ha_manage_backup`, `ha_manage_custom_tool` *(ベータ)*, `ha_manage_security_policy`, `ha_manage_theme`, `ha_manage_updates`, `ha_reload_core`, `ha_restart` | | **ToDo リスト** | `ha_get_todo`, `ha_remove_todo_item`, `ha_set_todo_item` | | **ユーティリティ** | `ha_eval_template`, `ha_report_issue` | | **ゾーン** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |

Z-Wave の設定値は、設定エンティティが無効または存在しない場合でも、ha_manage_radio に action="get_config_params" または action="get_config_param" を指定して読み取れます。読み取りにはデフォルトで Z-Wave JS キャッシュが使用されます。単一のフルルートパラメーターについては、デバイスからの読み取りを明示的に要求できます。パラメーターの読み取り、鮮度、例を参照してください。

---

🆚 ha-mcp と Home Assistant 組み込みの MCP サーバーの比較

Home Assistant には、独自の MCP サーバー統合が用意されています。これは Assist パイプラインを基盤としているため、接続した MCP クライアントは、Assist に公開したエンティティの読み取りや制御、Assist が理解するインテントの実行ができます。すでに公開済みのデバイスを音声操作する用途に便利です。

ha-mcp は、スマートホームを制御するだけでなく、設定、構築、デバッグするために作られたスタンドアロンサーバーです。デバイス制御に加えて、組み込み統合にはない次の機能を備えています。

機能	組み込み MCP サーバー	ha-mcp
公開済みデバイスの制御、状態の照会	対応	対応
エンティティの範囲	Assist に公開されたエンティティのみ	Home Assistant 内のすべて
オートメーション、スクリプト、シーンの作成・編集	非対応	対応
ダッシュボードの構築・編集	非対応	対応
トレースからのオートメーションのデバッグ、履歴・ログの読み取り	非対応	対応
ヘルパー、エリア、ゾーン、ラベル、グループの管理	非対応	対応
バックアップ、アプリ、HACS、デバイス・エンティティレジストリの管理	非対応	対応

使い分けの目安： すでに公開したデバイスの音声操作には組み込み統合を使用し、Home Assistant の設定の構築やメンテナンスもできる AI アシスタントが必要な場合は、ha-mcp を使用してください。

---

🔌 カスタムコンポーネント（ha_mcp_tools）— ファイルおよび YAML サービス

HA-MCP カスタムコンポーネントは、標準の Home Assistant API では提供できない、ファイルシステムへのアクセスや YAML 設定の編集といった権限が必要なツールも実行します。（同じコンポーネントでサーバー全体をプロセス内で実行できます。ページ上部の Get Started セクションで推奨しているインストール方法です。）このコンポーネントの File & YAML services エントリ（HA-MCP File & YAML Tools）を追加すると、以下のツールが利用できます。

コンポーネントが必要なツール：

ツール	説明
ha_config_set_yaml (beta)	configuration.yaml およびパッケージファイルのトップレベル YAML キーを安全に追加、置換、削除します（自動バックアップ、検証、設定チェックを実行）
ha_list_files (beta)	許可されたディレクトリ内のファイルを一覧表示します
ha_read_file (beta)	許可されたパスにあるファイル（設定 YAML、ログ、許可されたディレクトリ内のファイル）を読み取ります
ha_write_file (beta)	許可されたディレクトリにファイルを書き込みます
ha_delete_file (beta)	許可されたディレクトリ内のファイルを削除します

テンプレートヘルパーの編集内容のバックアップと復元にも、サーバーエントリまたは File & YAML Tools エントリのいずれかを使って、このコンポーネントが必要です。この 5 つのツールは、コンポーネントがインストールされていない場合、インストール手順を含むエラーを返します。

これらのツールの利用にはベータ機能フラグも必要です。有効化方法は Beta Features を参照してください。ファイルシステム／YAML の各サブフラグを有効にするには、マスターフラグ ENABLE_BETA_FEATURES を先にオンにする必要があります。

インストール

同じ HA-MCP カスタムコンポーネントから HA-MCP File & YAML Tools エントリをインストールします。

手動で追加する場合：HACS > Integrations > 三点メニュー > Custom repositories を開き、https://github.com/homeassistant-ai/ha-mcp を追加します（カテゴリ：Integration）。その後、Download を選択します。または、このリポジトリの custom_components/ha_mcp_tools/ を HA の config/custom_components/ ディレクトリにコピーします。

インストール後、Home Assistant を再起動します。次に、Settings > Devices & Services > Add Integration を開き、HA-MCP Custom Component を検索して、HA-MCP File & YAML Tools エントリを追加します。

この同じコンポーネントを通じて、プロセス内で ha-mcp サーバー全体を実行する方法については、ページ上部の Get Started セクションとプロセス内サーバーの全ドキュメント →を参照してください。

---

🧠 エージェントスキルでより良い結果を

このサーバーは、Home Assistant を操作するツールを AI エージェントに提供します。設定の質を高めるには、Home Assistant Agent Skills を組み合わせてください。これらのスキルは、エージェントに Home Assistant のベストプラクティスを教えるドメイン知識です。

MCP サーバーではオートメーション、ヘルパー、ダッシュボードを作成できますが、それらをどのように構成するかについての指針はありません。ドメイン知識がないと、エージェントはテンプレートに頼りすぎたり、誤った種類のヘルパーを選んだり、保守が難しいオートメーションを作成したりする傾向があります。スキルは、そのギャップを埋めます。Jinja2 による回避策ではなくネイティブな構成要素を使うこと、適切なヘルパーを選択すること、安全なリファクタリングのワークフロー、オートメーションモードの適切な使用方法を提供します。

同梱スキル（組み込み）

homeassistant-ai/skills のスキルは同梱されており、skill:// URI を介して MCP リソース として提供されます。リソースに対応している MCP クライアントであれば、自動的に検出できます。手動でインストールする必要はありません。ツールのみのクライアント（claude.ai など）では、ベストプラクティスのスキルを ha_get_skill_guide ツールから利用できます。引数なしで呼び出すと SKILL.md を読み込み、file に SKILL.md が参照しているパスを指定すると、その参照ファイルを読み込みます。リソースはコンテキストに自動で挿入されないため、クライアントが明示的に要求する必要があります。そのため、アイドル時のコンテキストコストはメタデータの一覧分だけです。

ha_get_skill_guide は必須のツールです。カタログには常に表示され（無効化できません）、そのためツールのみのクライアントでスキルの提供が気付かないうちに欠落することはありません。

ローカルのスキルファイルを使いたいクライアントでは、スキルを手動でインストールすることもできます。手順は スキルのリポジトリ を参照してください。

---

🔍 AI エージェント向けのツール検出

デフォルトでは、完全なツールカタログ（約87個のツール）が、標準の MCP tools/list 応答を通じてクライアントに一覧表示されます。ツールの遅延読み込み／オンデマンド読み込みに対応したクライアント（claude.ai、Claude Desktop、Claude Code）では問題なく処理できます。必要なときだけツールがコンテキストに読み込まれるため、アイドル時のコンテキストコストはほぼゼロです。

遅延読み込みに対応していない環境では、ツールカタログ全体を最初に一覧表示すると、アイドル時のコンテキストを大きく消費し、小規模なモデルを圧倒することがあります。該当するのは、Claude Haiku、Gemini、OpenAI 互換のローカルモデル、小規模なオープンウェイトモデルなどのモデルや、モデルに関係なくすべてのツールスキーマをインライン表示するクライアント（GitHub Copilot CLI など）です。この問題に対応するため、サーバーには FastMCP の BM25 検索変換を基盤とする検索ベースの検出モードが用意されています。

小規模またはローカルの LLM（Ollama など）

モデルからツールや Home Assistant が見えない場合、ツールカタログ全体が一度に渡されていて、処理に苦労している可能性があります。改善するか確認するには、次の方法をお試しください。

• ツール検索を有効にします（ENABLE_TOOL_SEARCH=true、または以下のアプリオプションを設定）。すべてのツールを最初に一覧表示する代わりに、サーバーは検索インターフェースの背後にカタログを置き、モデルが必要なときに必要なツールだけを読み込めるようにします。
• モデルのコンテキストウィンドウをデフォルトより大きくします。 ローカルランタイムには小さなデフォルト値が設定されている場合があります（Ollama の num_ctx など）。その設定では大量のツールと会話を保持できないため、デフォルトより大幅に大きな値にしてください。

検索ベースの探索を有効にする

ENABLE_TOOL_SEARCH=true に設定するか、HA アプリでオプションを切り替えます。ツール一覧では、完全なカタログが4つのエントリーポイントと、常に表示される少数の「ピン留め」ツール（ha_search、ha_get_overview、ha_report_issue など）に置き換わります。見つけたツールはすべて、名前を指定して直接呼び出せます。

ツール	用途
ha_search_tools	すべてのツール（ピン留めされたものを含む）を、BM25 による英語キーワード検索で検索します。非表示のツールは、名前、1行の説明（docstring の最初の段落）、1行の params リスト（型、列挙値、必須かどうか）、および実行するプロキシを含む簡潔な形式で返されます。ha_search_tools(tools=[...]) を使うと、指定したツールの完全な定義（説明、入力スキーマ、アノテーション）が返されます。これは呼び出し前の2段階目のリクエストです。ピン留めされたツールは、ツール一覧を参照する pinned: true の名前のみのスタブを返し、検索結果枠を消費しません。
ha_call_read_tool	名前を指定して readOnlyHint ツールを実行します。安全なため、クライアントは自動承認できます。
ha_call_write_tool	データを作成または更新する書き込みツールを実行します。
ha_call_delete_tool	データを削除するツールを実行します。

プロキシを分けることで、MCP クライアントはツールの docstring を解析せずに、カテゴリごとに異なる権限ポリシーを適用できます（例：読み取りは自動承認、書き込みはプロンプトで確認、削除は確認を要求）。

ha_manage_* ツールは複数の操作をまとめるため、複数のプロキシから利用できます。ha_call_write_tool と ha_call_delete_tool はツール全体を実行し、ha_call_read_tool は Read Only Mode が承認する読み取り操作のみを実行します（呼び出しごとの判定は同じです）。そのため、承認された読み取り操作がない管理ツールは、ここからは利用できません。検索結果には、ツールを利用できる各プロキシが表示されます。Read Only Mode では ha_call_read_tool のみが一覧に表示されます。残り2つは、それらをキャッシュ済みのツール一覧に保持しているクライアントからの呼び出しには引き続き応答し、含まれる書き込み操作には Unknown tool ではなく Read Only Mode エラーを返します。

設定	デフォルト	説明
ENABLE_TOOL_SEARCH	false	完全なツールカタログを検索ベースの探索に置き換えます（ツールはオンデマンド検索で見つかるまで表示されません）。
TOOL_SEARCH_MAX_RESULTS	5	ha_search_tools の呼び出しごとに返される非表示ツールの最大数（範囲：2～10）。この上限内の順位に入ったピン留めツールは、その件数に加えて名前のみのスタブとして追加されます。
PINNED_TOOLS	空	常に表示するツール名をカンマ区切りで指定します。管理にはウェブ設定 UI を使用するのが基本です。

有効にする場面

• Claude Haiku、OpenAI 互換のローカルモデル、Gemini、またはネイティブの遅延ツールサポートがないモデル — アイドルコンテキストの大幅な節約になります。モデルに関係なくすべてのツールスキーマをインライン展開するクライアント (例: GitHub Copilot CLI、Claude Sonnet/Opus を実行している場合でも) にも同じことが当てはまります。
• ツールの総数を上限設定する MCP クライアント (100 に制限するものもあります) — 87 個ではなく最小限のセット (約 10 個のツール) を公開します。
• コストに敏感なデプロイ — ターンごとのアイドルトークンが少なくなります。

遅延ツール読み込みを備えたクライアント (claude.ai、Claude Desktop、Claude Code) では無効のままにしてください。そこでは完全なカタログにアイドルコストはかからず、直接呼び出しは検索ステップをスキップし、クライアント内蔵のツール検索のほうが適しています — その上に ha-mcp のものを実行する利点はありません。ツールが遅延されるかどうかはクライアントとモデルの組み合わせに依存します。同じモデルでもクライアントごとに動作が異なることがあります — GitHub Copilot CLI は Claude Sonnet/Opus を実行していると完全なカタログをインライン展開するため、ここでのツール検索の恩恵を受けられます。一部の Codex モデルや ChatGPT も遅延ツールを含んでいます — 不必要にこれを有効にしたままにしないよう、お使いのクライアント/モデルを直接確認してその機能を確かめてください。

🔄 この設定 (またはその他の設定) を変更した後は、クライアントのツールリストを更新してください。 ENABLE_TOOL_SEARCH を切り替える (または固定/無効化されたツール、読み取り専用モードなどを変更する) と、サーバーが公開するツールが変わりますが、AI クライアントは再取得するまで キャッシュされた ツールリストを提供し続けます。アプリや Home Assistant を再起動してもクライアントは 更新されません — クライアントで MCP サーバーに再接続または更新を行ってください (例: ChatGPT でコネクタを再追加/更新する、または Claude Desktop を閉じて再度開く)。これを怠ると、新しく有効化されたツールはクライアントにまったく表示されず、サーバーが公開しなくなったツールは利用可能として表示され続けますが、呼び出すと失敗します (Unknown tool、または読み取り専用モードが隠す書き込みツールに対する読み取り専用モードのエラー)。ChatGPT は、コネクタを削除して同じ名前で再追加した後でも、古いリストを提供し続けることがあります — 再追加してもツールがまだ表示されない場合は、コネクタを削除し、異なる名前 で新しいものを作成してください。

HA アプリの場合、同じオプションが homeassistant-addon/DOCS.md に、きめ細かなツールの有効化/無効化/固定のためのアプリ内設定 UI とともに記載されています。

---

読み取り専用 HTTP 接続

サーバーの HTTP MCP エンドポイントに /readonly を追加すると、その接続を既存の読み取り専用モードに制限しつつ、他のクライアントは通常のアクセスを維持できます:

Normal:     https://example.com/private_your_secret
Read-only:  https://example.com/private_your_secret/readonly

OAuth および OIDC 接続は同じログイン/プロバイダーを使用します。たとえば、https://example.com/mcp/readonly のようになります。追加のシークレットやサーバーは必要ありません。読み取り専用接続は書き込みツールを隠し、キャッシュされたツールや検索プロキシ経由の呼び出しを含め、書き込み呼び出しをブロックします。グローバルの読み取り専用モード設定が有効な場合、両方のエンドポイントが引き続き制限されます。URL を変更した後は、ツールリストを更新するためにクライアントを再接続してください。

これは自動化エージェント向けの接続モードであり、認証情報に対する別個の権限ではありません。同じ認証情報は通常のエンドポイントでも引き続き機能します。Home Assistant の Webhook URL もこのサフィックスを受け付けます: https://your-ha.example/api/webhook/<webhook-id>/readonly。これには、更新された組み込み統合または Webhook Proxy 開発アプリ (アドオン) と、更新された MCP サーバーが必要です。

🧪 開発チャンネル

新機能や修正にいち早くアクセスしたいですか? 開発リリース (.devN) は master へのプッシュごとに公開されます。

開発チャンネルのドキュメント — pip/uvx、Docker、Home Assistant アプリ向けの手順です。

---

🤝 コントリビューション

開発環境のセットアップ、テスト手順、コントリビューションのガイドラインについては、CONTRIBUTING.md を参照してください。

包括的なテストドキュメントについては、tests/README.md を参照してください。

---

🔒 プライバシー

Ha-mcp はお使いのマシン上でローカルに動作します。スマートホームのデータはネットワーク内に留まります。

• 現在、テレメトリーはありません — 匿名の使用状況統計は将来の機能として計画されています（2026 年 6 月時点）。導入時には、Home Assistant の分析／テレメトリー設定（変更可能）に従い、リリースノートとウェブ版の設定 UI で少なくとも 1 か月前に目立つ形で告知します
• 個人データは収集しません — エンティティ名、設定、デバイスデータを収集することはありません
• ユーザーが管理するバグ報告 — 明示的な承認があった場合にのみ送信されます

詳細については、プライバシーポリシーをご覧ください。

---

📄 ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細はLICENSEファイルをご覧ください。

---

🙏 謝辞

• Home Assistant：素晴らしいスマートホームプラットフォームです（！）
• FastMCP：優れた MCP サーバーフレームワークです
• Model Context Protocol：AI アプリケーション間の通信を標準化します
• Claude Code：AI を活用したコーディングアシスタントです
• PolicyLayer：引数パス述語 DSL の形式（args.domain in [...] と eq／in／regex／contains／exists／…）に着想を得て、ツールごとの承認ルールスキーマを設計しました（#966）。

👥 貢献者

メンテナー

• @julienld — プロジェクトの作成者です。
• @sergeykad — コアメンテナーです。
• @kingpanther13 — コアメンテナーです。
• @Patch76 — コアメンテナーです。

貢献者

• @bigeric08 — プロトコルバージョン 2025-11-25 をサポートするため、mcp 依存関係を明示的に追加。
• @airlabno — スケジュールの時間ブロックで data フィールドをサポート。
• @ryphez — Codex Desktop UI MCP のクイックセットアップガイド。
• @Danm72 — エンティティのプロパティを管理するエンティティレジストリツール（ha_set_entity、ha_get_entity）。
• @Raygooo — SOCKS プロキシをサポート。
• @cj-elevate — インテグレーションとエンティティの管理ツール（有効化／無効化／削除）、および人物／ゾーン／タグの設定ストアルーティング。
• @maxperron — ベータテスト。
• @kingbear2 — Windows UV セットアップガイド。
• @konradwalsh — GitHub Sponsors を通じた金銭的支援。ありがとうございます！☕
• @knowald — 親デバイス経由で割り当てられたエンティティについて、ha_get_system_overview でデバイスレジストリを使ったエリア解決を実装。GitHub Sponsors を通じた金銭的支援。ありがとうございます！☕
• @zorrobyte — OAuth モードでクライアントごとの WebSocket 認証情報に対応し、WebSocket ツールの失敗を修正。
• @deanbenson — オートメーションが多数ある大規模な Home Assistant インスタンスで発生する ha_deep_search のタイムアウトを修正。
• @saphid — 設定エントリーのオプションフローツール（初期設計、#590）。
• @adraguidev — グループヘルパーのメニューベースの設定エントリーフローを修正（#647）。
• @transportrefer — インテグレーションのオプション検査（ha_get_integration のスキーマサポート、#689）。
• @teh-hippo — ブループリントのインポートで保存ステップが欠落する問題を修正。
• @smenzer — ドキュメントの修正。
• @The-Greg-O — 設定エントリー削除用 REST API。
• @restriction — 責任ある脆弱性開示：python_transform サンドボックスで呼び出し先の検証が欠落している問題。
• @lcrostarosa — 診断とヘルスモニタリングツールの構想（#675）。システム／エラーログ、修復、ZHA 無線メトリクスの統合に着想を与えました。
• @roysha1 — インストールウィザードで Copilot CLI をサポート。ドキュメントサイトのプレースホルダーロゴ SVG を正式なブランドアイコンに置き換え。
• @teancom — アドオンの統計情報エンドポイント（/addons/{slug}/stats）を修正。
• @TomasDJo — オートメーション、スクリプト、シーンのカテゴリをサポート。
• @bzelch — オートメーションとスクリプトで python_transform をサポート。
• @gcormier — Windows インストーラーを改善。未使用の変数を削除し、インストール後にターミナルが閉じる問題を修正。
• @ekobres — アプリ設定で HAMCP_ENABLE_FILESYSTEM_TOOLS と（後に削除された）HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION の機能フラグを追加し、ソースとドキュメントでベータタグを付与。
• @w3z315 — GitHub Sponsors を通じた金銭的支援。ありがとうございます！☕
• @griffinmartin — Anomaly による OpenCode をセットアップウィザードで選択可能な AI クライアントとして追加。stdio とストリーミング可能な HTTP の両方をサポート。
• @hhopke — アプリ（アドオン）API 呼び出しがコンテナへの直接接続ではなく HA Core のイングレスプロキシ経由になるよう修正し、アプリのインストール環境における ha_manage_addon（現在は ha_manage_app）のプロキシモードの問題を解決。
• @tomwilkie — JMESPath ミドルウェアの検討（#1147）。レビュー時のトークン測定データが #1199 と #1225 の設計に役立ちました。
• @SealKan — 読み取り負荷の高い 6 つのツールに fields=／attribute_keys= 投影を追加（#1225）、ha_call_event ツールを追加（#1239）、ダッシュボード一覧ヘルパーをリファクタリング（#1207）、ベストプラクティスチェッカーに for: フィールドの期間計算検出機能を追加（#1264）、再起動後も保持される DCR OAuth クライアント登録（#1265）、課題トリアージ用プロンプトのトークン予算管理（#1522）。
• @KarelTestSpecial — 大量編集時の CPU スパイクを防ぐため、YAML インスタンスをキャッシュ（#1371）。
• @corgan2222 — カスタムインテグレーション用の HA ブランドアセット（#1317）。
• @drseanwing — FastMCP Context を使った長時間実行ツールの進捗通知（#1124）、ツールの検出／カテゴリ別検索に関するドキュメント（#1123）。
• @fnordpig — 設定サブエントリーをサポート（#1393）、Assist パイプライン管理ツールを追加（#1392）。
• @paul43210 — アトミックな GET・変更・POST を可能にする ha_manage_app の array_patch モード（#1063）。
• @L1AD — ツールのセキュリティポリシーを提案する #966 を提出。述語 DSL の形式に着想を与えた先行事例として、PolicyLayer の MCP セキュリティに関する取り組みを紹介。
• @nightcityblade — HA 2026.6 で従来は詳細設定だったオプションがデフォルトで利用可能になったことを受け、古くなった Home Assistant の詳細設定に関する記述を更新（#1533）。
• @emmelutzer — GitHub Sponsors を通じた金銭的支援。ありがとうございます！☕
• @pkkr — アップロードされた ETS プロジェクトファイルから KNX グループアドレスを取得する ha_knx_get_project ツール。
• @cbowns — setup.astro の Codex CLI ドキュメントにある不統一なハイフンを修正。
• @Shaan-alpha — リバースプロキシからの 502／503 応答に対応するため、ha_restart の既知の正常エラーパターンを拡張。
• @rebelancap — add_timezone_metadata で UTC からローカルタイムゾーンへの変換を修正。
• @saevras — ブループリントインポートの E2E テストで、ホストとコンテナ間のネットワークではなくローカル URL を使うよう修正。
• @jasonjhofmann — ha_config_set_calendar_event で rrule をサポートし、カレンダーの定期イベントに対応。
• @vpciii — ツールの dict／list パラメーターで、JSON エンコードされた文字列を適切な型に変換。
• @pburtchaell — GitHub Sponsors を通じた金銭的支援。ありがとうございます！☕
• @norpol — OpenAI Tunnel for HA-MCP コンパニオンインテグレーションを開発。ファイアウォールで保護された Home Assistant MCP サーバーに ChatGPT を接続します（#1811）。

---

💬 コミュニティ

• GitHub Discussions — 質問したり、アイデアを共有したりできます
• Issue Tracker — バグの報告、機能のリクエスト、ツールの動作改善の提案ができます。バグ報告には、ha_report_issue ツールが生成するレポート、またはレポートがない理由が必要です。どちらもない場合、24 時間後にクローズされます。

---

スターの履歴