Home Assistant Admin MCP

安全性を重視したModel Context Protocol（MCP）サーバーで、Home Assistantインスタンスの検査、制御、診断、および選択的な管理を行うためのものです。Home AssistantのREST APIとWebSocket APIを、オプションで制約付きのHome Assistant設定マウントと組み合わせて使用します。

このサーバーにはLLMは含まれていません。MCPクライアントがツールを選択します。このサーバーは入力を検証し、デプロイメントポリシーを適用し、Home Assistantと通信して、構造化された結果を返します。

[!NOTE] このプロジェクトはAI支援開発ツールを使用して構築されています。

[!WARNING] adminモードでは、デバイス、レジストリ、ヘルパー、オートメーション、スクリプト、シーン、統合、YAML設定を変更したり、Home Assistantを再起動したりできます。read_onlyで開始し、専用のHome Assistantアカウントを使用し、ドライランを確認し、HTTPエンドポイントは信頼できるクライアントにのみ公開してください。

範囲と境界

実装済みの機能は以下のとおりです：

• ランタイム状態、サービス/アクション、イベント、履歴、ログブック、統計、現在のセッションログの検査（凝縮されたsystem_logフォールバック付き）。

• エリア、デバイス、エンティティ、設定エントリが相互リンクされたレジストリおよび統合の検出。

• 明示的なターゲットとライブのHome Assistantサービス定義を使用した、検証済みのサービス呼び出し。

• エディタで管理されるオートメーション、スクリプト、シーンの読み取りと変更。

• Home Assistant内部APIを通じた、ストレージバックアップのヘルパーおよび選択されたレジストリ/設定エントリの変更。

• 診断、依存関係分析、レジストリ/エディタリソース/許可リストされたYAMLにわたる検索、トレース、設定差分、チェックポイント、および制限付きGit履歴。

• 明示的なファイルシステム許可リストの下での構造化YAMLパッチ。

明示的な非目標と制限事項：

• Home Assistant Supervisor API、アドオン管理、ホスト管理、またはHome AssistantバックアップAPIはありません。

• Docker API、Dockerソケット、コンテナライフサイクル、イメージ管理、またはコンテナログへのアクセスはありません。デプロイメントは/var/run/docker.sockをマウントしません。

• 任意のシェル実行や任意のファイルシステムアクセスはありません。

• 汎用のconfig-flow/options-flow実装はなく、任意の統合認証情報を送信するメカニズムもありません。統合ツールは設定エントリの読み取り、実装済みの設定変更、有効化/無効化、または再読み込みの要求のみを行います。

• すべてのHome Assistantユーザーがすべてのエンドポイントを呼び出せるという前提はありません。長期トークンは、そのHome Assistantユーザーの権限と管理者ステータスを継承します。

Related MCP server: hass-mcp-server

アーキテクチャ

flowchart LR
    Client["MCP client"] -->|"Streamable HTTP + MCP bearer token"| HTTP["HTTP transport /mcp"]
    Client -->|"stdio"| Stdio["stdio transport"]
    HTTP --> Policy["MCP tools, schemas, mode, risk and confirmation policy"]
    Stdio --> Policy
    Policy --> REST["Home Assistant REST client"]
    Policy --> WS["Home Assistant WebSocket client"]
    REST --> HA["Home Assistant Core"]
    WS --> HA
    Policy --> TX["Filesystem transaction layer"]
    TX --> Mount["/ha-config allowlisted read-write mount"]
    TX --> Checkpoints[".ha-mcp/backups"]
    TX --> Git["Optional local Git commits"]
    TX -->|"check config, reload, health"| REST
    NoDocker["No Supervisor or Docker socket access"]

HTTPトランスポートはMCPハンドラーレイヤーではステートレスです。アプリケーションプロセスは引き続きHome Assistant接続/キャッシュを共有し、ファイルシステムトランザクションを直列化します。

Home Assistant APIマトリックス

2026-08-20に現在のHome Assistantドキュメントとhome-assistant/coreのdevソースに対してレビュー済み。ソースリンクは内部コマンドが現在存在することを示していますが、安定性を保証するものではありません。

Home Assistant APIにはAuthorization: Bearer <HA token>が必要です。公式の認証APIを参照してください。MCP HTTPエンドポイントには別のベアラートークンがあります。

内部API互換性

• 内部エンドポイントは、公開APIの非推奨期間なしに名前変更、制限、スキーマ変更が行われる場合があります。本番環境でadminを有効にする前に、正確なHome Assistantリリースに対してテストしてください。

• レジストリ、ヘルパー、トレース、システムヘルス、ログブックWebSocket、レコーダーメタデータ、設定エントリ、およびエディタ操作は、互換性のないリリースではHA_WS_UNSUPPORTED、HA_INTERNAL_API_UNAVAILABLE、HELPER_STORAGE_API_UNAVAILABLE、権限エラー、または応答検証エラーを返す場合があります。

• 現在のHome Assistantコアは、多くのレジストリ変更とトレース読み取りを管理者専用としてマークしています。それらのツールが必要な場合は、管理者に属するトークンを使用してください。非管理者トークンは、そのHome Assistantの権限で十分な場合、読み取り/制御専用のデプロイメントには適切な場合があります。

• エディタの変更は、エディタ管理のautomations.yaml、scripts.yaml、scenes.yamlリソースに限定されます。使用可能なエディタIDがない実行中のYAMLリソースは、編集不可として報告されます。

• サポートされているヘルパーは、input_boolean、input_button、input_text、input_number、input_datetime、input_select、counter、timer、scheduleです。それらの受け入れフィールドは、インストールされているHome Assistantのバージョンによって決まります。

• 設定エントリ操作は、設定フロー、オプションフロー、再認証、修復、OAuth、または資格情報の入力を開始しません。これらの操作にはHome Assistant UIを使用してください。

• ヘルパー、レジストリ、エリア、デバイス、エンティティ、および設定エントリのドライラン・プレビューは、Home Assistantの変更バリデータを呼び出しません。その結果には、その事実を説明する制限が含まれます。

本番デプロイメント

前提条件

• Compose v2とBuildKitを備えたDocker Engine。

• APIが有効な、到達可能なHome Assistant Coreインスタンス。Home Assistantのフロントエンドが通常これを提供します。APIのみのインストールには、api統合が必要です。

• Home Assistantの長期アクセストークン。

• ファイルシステム、チェックポイント、エディタ変更の安全性、またはGit機能が必要な場合は、Home Assistant設定を含むホストパス。

• 設定された非root UID/GIDがそのパスを読み書きできるホストの所有権/権限。

GitHubリリースは、docker.io/lemanjo/hac-mcpにマルチアーキテクチャイメージを公開しています。再現可能なデプロイメントには、latestではなく正確なリリースタグを使用してください。ローカルビルドも引き続きサポートされています。

Home Assistantトークンの作成

1. このサービスが動作するユーザーとしてHome Assistantにサインインします。

2. ユーザープロフィールを開き、セキュリティタブを開きます。

3. 長期アクセストークンで、トークンを作成を選択し、このデプロイメント用に名前を付けます。

4. 表示されたトークンを記録します。Home Assistantは後で表示するためにトークン文字列を保持しません。

5. 内部管理ツールが必要な場合のみ、管理者アカウントを使用します。

Home Assistantは、プロフィール管理をここで、長期トークンをここで文書化しています。長期トークンは高価値の資格情報であり、コミットしたり、config.example.yamlに配置したり、MCPクライアントに公開したりしないでください。

Composeセットアップ

cp .env.example .env
cp config.example.yaml config.yaml
install -d -m 700 secrets
openssl rand -hex 32 > secrets/mcp_auth_token
read -rsp "Home Assistant token: " HA_TOKEN
printf '%s' "$HA_TOKEN" > secrets/home_assistant_token
unset HA_TOKEN
chmod 600 secrets/home_assistant_token secrets/mcp_auth_token

.envにこれらの値を設定します：

• HOME_ASSISTANT_URL：コンテナから到達可能。http://host.docker.internal:8123は、Composeがhost-gatewayエントリをインストールするため、Linux Dockerホストが公開するHome Assistantポートに到達します。Home AssistantのLAN URLも機能します。

• HA_CONFIG_PATH：既存のホストHome Assistant設定ディレクトリ。読み書き可能で/ha-configにマウントされます。Composeは存在しないソースパスの作成を拒否します。

• MCP_SETTINGS_FILE：デプロイメント固有の変更を行った後、./config.yamlを使用します。

• PUIDとPGID：HA_CONFIG_PATHへのアクセス権を持つ非root ID。

• MCP_ALLOWED_HOSTS：クライアントがHTTP Hostヘッダーに入れるすべてのDNS名またはIP。

• MCP_BIND_IP：ローカルリバースプロキシ/クライアントには127.0.0.1を維持します。意図的なLAN公開の場合のみ0.0.0.0を使用します。

検証、ビルド、起動：

docker compose config
docker compose build --pull
docker compose up -d
docker compose ps
docker compose logs -f hac-mcp

ローカルビルドの代わりに公開リリースを使用するには、正確なイメージタグを設定し、ビルドを無効にします：

MCP_IMAGE=docker.io/lemanjo/hac-mcp:0.1.0 docker compose pull hac-mcp
MCP_IMAGE=docker.io/lemanjo/hac-mcp:0.1.0 docker compose up -d --no-build hac-mcp

ヘルスエンドポイント：

curl --fail http://127.0.0.1:3000/livez
curl --fail http://127.0.0.1:3000/readyz

/livezはHTTPプロセスがサービスを提供していることを報告します。/readyzは認証済みのHome Assistant /api/リクエストを実行し、Home Assistantが利用できない場合は503を返します。どちらのエンドポイントもMCPベアラートークンを必要としません。イメージとComposeヘルスチェックは/livezを使用するため、一時的なHome Assistantの停止で再起動ループが発生しません。

ランタイムファイルシステムは、/tmp、Dockerシークレットマウント、/ha-configを除いて読み取り専用です。イメージは非rootユーザーとして実行され、PID 1としてtiniを使用します。SIGTERM/SIGINTはNodeに到達し、HTTPハンドラーとHome Assistant WebSocket接続を閉じます。GitとCA証明書がインストールされていますが、シェル実行MCPツールは実装されていません。

ネットワーク配置

提供されているComposeネットワークは、公開されたMCPポートが1つの分離されたブリッジです。ホストネットワーキングを使用したり、Dockerソケットをマウントしたりすることはありません。

Home Assistant接続の場合：

• 公開ポートを持つDockerホスト上のHome Assistant：http://host.docker.internal:8123を使用します。

• LANまたはmacvlan/ipvlanネットワーク上のHome Assistant：そのLAN DNS名またはIPを使用します。

• 別のユーザー定義ブリッジ上のHome Assistant：hac-mcpをその外部ネットワークに接続し、Home AssistantのコンテナDNS名を使用します。下部のネットワーク宣言をexternal: trueネットワークに置き換えるか、サービスに2番目の外部ネットワークを追加します。

MCPクライアント接続の場合：

• 同じホストのクライアントまたは同じホストのリバースプロキシには、MCP_BIND_IP=127.0.0.1を維持します。

• 信頼できるLANクライアントにはMCP_BIND_IP=0.0.0.0を設定し、サーバーのLAN IP/DNS名をMCP_ALLOWED_HOSTSに追加し、ホストファイアウォールルールでポートを制限します。

• このサーバーはTLSを終端しません。信頼できないネットワークを通過するトラフィックには信頼できるリバースプロキシを使用し、Authorizationヘッダーを保持し、ブラウザクライアントがOriginを送信する場合は許可されたオリジンホスト名を設定します。

許可されたホストとオリジンホスト名は、DNSリバインディング/クロスオリジンアクセスを軽減します。これらはベアラー認証やネットワーク制御を置き換えるものではありません。MCPのStreamable HTTPセキュリティガイダンスは、トランスポート仕様にあります。

Unraid

Unraidはユーザー共有を/mnt/userの下に公開します。公式の共有ドキュメントを参照してください。一般的なレイアウトは、このチェックアウト/シークレット用に/mnt/user/appdata/hac-mcp、HA_CONFIG_PATH用に実際のHome Assistant appdataディレクトリです。

1. プロジェクトとシークレットファイルをプライベートなappdataの場所に置きます。可能な場合は、シークレットファイルをモード0600、ディレクトリをモード0700に保ちます。

2. HA_CONFIG_PATHを正確なHome Assistant設定ディレクトリに設定します。例：/mnt/user/appdata/home-assistant。/mnt/user全体をマウントしないでください。

3. Home AssistantファイルがUnraidの通常のnobody:usersアカウント用に所有されている場合のみ、PUID=99とPGID=100を設定します。それ以外の場合は、実際の非root所有者を使用します。このIDが/ha-config/.ha-mcp/backupsを作成し、許可されたYAMLファイルを原子的に置き換えられることを確認します。

4. Docker Compose ManagerコミュニティプラグインまたはCompose v2 CLIがインストールされている場合は、プロジェクトディレクトリから上記のComposeセットアップを実行します。Composeシークレットは/run/secretsの下のファイルとして表示されます。Dockerはその動作をここで文書化しています。

5. Composeがない場合は、home-assistant-admin-mcp:localをビルドし、UnraidのDocker UIで詳細ビューを使用してコンテナを作成します。docker-compose.ymlから環境、ポート、パスの設定をミラーリングします。2つのトークンファイルを読み取り専用で/run/secrets/home_assistant_tokenと/run/secrets/mcp_auth_tokenにバインドします。これらのUIバインドマウントは、アプリが期待するファイルインターフェースを提供しますが、Composeシークレットオブジェクトではありません。

6. デフォルトでブリッジネットワークを使用します。Home Assistantがホストネットワーキングを使用している場合は、HOME_ASSISTANT_URLをUnraid LAN IPとHome Assistantポートに向けるか、host.docker.internal:host-gatewayを追加します。Home Assistantに独自のbr0 LAN IPがある場合は、そのIPを使用します。両方のコンテナがカスタムDockerネットワークを共有している場合は、Home Assistantのネットワークエイリアスを使用します。

7. LAN MCPアクセスの場合は、コンテナポート3000を公開し、意図的にバインドし、Unraid IP/DNS名をMCP_ALLOWED_HOSTSに含めます。信頼できるLANでもベアラートークンとファイアウォール制限を維持します。

8. Dockerソケットパスを追加しないでください。スーパーバイザー/コンテナ管理は必要なく、サポートされていません。

UnraidのMoverまたは共有設定により、ユーザー共有ファイルの物理的な保存場所が/mnt/user/...を変更せずに変わる場合があります。安定したユーザー共有パスを1つ使用し、同等の/mnt/userと/mnt/diskXパスを混在させないでください。

MCPクライアント

Streamable HTTP

以下の例では、MCPクライアントがDockerと同じホストで実行され、Composeのデフォルトが変更されていないことを前提としています。クライアントを次の場所に向けます：

http://127.0.0.1:3000/mcp

/mcpへのすべてのリクエストは、別のMCPトークンを運ぶ必要があります：

Authorization: Bearer <contents of secrets/mcp_auth_token>

MCPトークンをクライアント設定ファイルに入れずに、クライアントプロセス環境にロードします。このトークンはMCPクライアントのみを認証します。ここでHome Assistantトークンを使用しないでください。

export HAC_MCP_TOKEN="$(tr -d '\r\n' < /absolute/path/to/secrets/mcp_auth_token)"

別のホストのクライアントの場合は、127.0.0.1をMCPホストのアドレスに置き換え、ネットワーク配置で説明されているようにMCP_BIND_IP、MCP_ALLOWED_HOSTS、ファイアウォールルール、TLSを設定します。別のコンテナからは、127.0.0.1はそのクライアントコンテナを意味します。共有ネットワークエイリアスまたはホストアドレスを使用してください。

Codex

ユーザーレベルの~/.codex/config.tomlまたは信頼できるプロジェクトの.codex/config.tomlにこれを追加します：

[mcp_servers.home-assistant-admin]
url = "http://127.0.0.1:3000/mcp"
bearer_token_env_var = "HAC_MCP_TOKEN"
enabled = true
default_tools_approval_mode = "writes"
tool_timeout_sec = 150

HAC_MCP_TOKENを設定した後、Codexを再起動し、codex mcp listまたはCodex TUIの/mcpで接続を確認します。writes承認モードは、読み取り専用としてマークされていないツールに対してクライアント側のプロンプトを追加します。サーバー側のモード、リスク、確認ポリシーは引き続き独立して適用されます。Codex MCPドキュメントを参照してください。

OpenCode

これをプロジェクトレベルのopencode.jsonまたはグローバルなOpenCode設定にマージします：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "home-assistant-admin": {
      "type": "remote",
      "url": "http://127.0.0.1:3000/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:HAC_MCP_TOKEN}"
      },
      "timeout": 150000
    }
  }
}

HAC_MCP_TOKENを設定した後、OpenCodeを再起動します。opencode mcp listでステータスを確認するか、opencode mcp debug home-assistant-adminで接続を診断します。プロンプトでは、必要に応じてサーバーを名前で参照します。例：Use home-assistant-admin to list unavailable entities. OpenCode MCPドキュメントを参照してください。

Claude Code

Claude Codeを実行するプロジェクトに、この.mcp.jsonを作成またはマージします：

{
  "mcpServers": {
    "home-assistant-admin": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${HAC_MCP_TOKEN}"
      },
      "timeout": 150000
    }
  }
}

環境変数参照は共有しても安全です。コミットされたファイル内のリテラルトークンに置き換えないでください。HAC_MCP_TOKENを設定した後、claude mcp listを実行し、claudeを起動し、プロンプトが表示されたらプロジェクトスコープのサーバーを承認し、/mcpでそのステータスを確認します。Claude Code MCPドキュメントを参照してください。

確認と使用

低レベルの初期化プローブは、クライアントとは独立してエンドポイント、プロキシ、認証の問題を診断するのに役立ちます：

curl --fail-with-body http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer ${HAC_MCP_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-probe","version":"1.0.0"}}}'

通常の操作には実際のMCPクライアントを使用してください。クライアントは初期化、プロトコルバージョン交渉、通知、ツール呼び出しを正しく実行します。サーバーはauto応答モードでJSONまたはSSE応答を受け入れ、ステートレスなHTTPハンドラーを使用します。役立つ最初のプロンプトは次のとおりです：

• Use home-assistant-admin to summarize the Home Assistant instance and list unavailable entities. Do not make changes.

• Use home-assistant-admin to diagnose why <entity> is unavailable. Read configuration and recent logs only.

• controlモード：Turn on <explicit entity_id>. Do not target an area or device.

• adminモード：Dry-run the requested configuration change, show the diff and validation result, and wait for confirmation before applying it.

クライアントはサーバーの設定済みモードを昇格できません。read_only で起動してください。権限とデプロイ時の露出を確認した後にのみ、.env の MCP_MODE を変更し、Compose サービスを再作成してください。

stdio

まず pnpm build でビルドし、その後ローカルの MCP クライアントを設定してサーバーを起動します。stdio では MCP クライアントがサブプロセスとパイプを所有するため、HTTP 認証は使用されません。

{
  "mcpServers": {
    "home-assistant-admin": {
      "command": "node",
      "args": ["/workspaces/hac-mcp/dist/index.js"],
      "env": {
        "MCP_CONFIG_FILE": "/workspaces/hac-mcp/config.example.yaml",
        "MCP_TRANSPORT": "stdio",
        "MCP_MODE": "read_only",
        "HOME_ASSISTANT_URL": "http://homeassistant.local:8123",
        "HOME_ASSISTANT_TOKEN_FILE": "/absolute/private/path/home_assistant_token",
        "HA_CONFIG_PATH": "/absolute/path/to/home-assistant/config"
      }
    }
  }
}

サーバーは stdio モードでは stderr にのみログを書き込みます。Docker のヘルスチェックは HTTP 固有のものであるため、イメージを意図的に stdio サブプロセスとして実行する場合は、デフォルトの Docker ヘルスチェックを使用しないでください。

認証と設定

2 つの独立した認証情報があります:

両方のトークンについて、*_FILE 変数は直接の環境変数より優先され、周囲の空白はトリミングされます:

• HOME_ASSISTANT_TOKEN_FILE は HOME_ASSISTANT_TOKEN より優先されます。

• MCP_AUTH_TOKEN_FILE は MCP_AUTH_TOKEN より優先されます。

MCP_AUTH_TOKEN またはそのファイルは HTTP では必須であり、stdio では不要です。Bearer 比較は SHA-256 ダイジェストとタイミングセーフな比較を使用します。Bearer トークンは再生可能であるため、ネットワークが信頼されていない場合は TLS が依然として必要です。

設定は MCP_CONFIG_FILE から読み込まれ、その後環境変数の値がファイルを上書きします。サポートされている環境変数の上書きは次のとおりです:

カンマ区切りの変数はトリミングされます。存在する環境変数のみが YAML の値を上書きします。制限、権限、キャッシュ TTL、シークレットメタデータポリシー、バックアップディレクトリ、Git 作成者 ID は、それ以外は YAML のデフォルトまたは設定ファイルから取得されます。

モード、リスク、および確認

すべてのツールはリスクレベルとともに登録され、クライアントに表示されたままになります。ポリシーは呼び出し時に再度適用されます。

call_service は CONTROL ベースラインを持ちますが、認可前に既知の管理引数を昇格させます: 再起動/停止、バックアップ、レコーダーパージ操作は HIGH_IMPACT になります。リロード、ロガー、設定操作は CONFIG になります。実効リスクは各結果で返され、カスタム MCP メタデータはツールが動的に分類されることを示します。

permissions.requireConfirmationFor はデフォルトで HIGH_IMPACT です。一致するツールは confirm: true を受け取る必要があります。そうでない場合は、再試行メタデータとともに CONFIRMATION_REQUIRED を返します。より広範囲に確認を要求するには、CONTROL や CONFIG を追加します。

機密ドメインポリシーはモードとは独立しています:

• allow: 通常のモード/リスクポリシーが適用されます。

• confirm: 明示的な confirm: true が必要です。

• deny: admin モードでも操作は拒否されます。

デフォルトでは、lock、alarm_control_panel、siren に確認が必要です。garage または gate を含む明示的なカバーエンティティ ID も確認が必要です。ポリシーは、マルチエンティティターゲット内のすべての明示的なエンティティを評価します。エリア/デバイスターゲットは認可時に安全に展開できないため、その区別が重要な場合は、サービスドメイン全体に対して拒否または確認を要求します。

ドライラン

dry_run: true は、永続リソース、ヘルパー、レジストリ、エリア、デバイス、エンティティ、設定エントリ、YAML パッチ、管理ライフサイクル、ロールバック、および汎用サービス呼び出しツールに実装されています。便利な物理制御ツールはアクションをシミュレートしません。

• YAML パッチは、結果の YAML を解析して検証し、書き込み、チェックポイント作成、リロード、Home Assistant の完全な設定チェック、コミットを行わずに、編集された構造化差分を返します。

• ローカル YAML 解析は、構文エラー、重複するマッピングキー、未解決のエイリアス、過剰なエイリアス展開を拒否します。非ドライの適用では、その後 Home Assistant の完全な設定チェックが実行され、拒否された場合はロールバックが試行されます。ローカル検証は Home Assistant のドメイン検証の代わりにはなりません。

• オートメーション/スクリプト/シーンのドライランは、現在のエディタリソースを読み取り、JSON 差分を作成し、利用可能な場合は実装されたフラグメント検証を呼び出しますが、書き込みやチェックポイントの作成は行いません。

• ヘルパー、レジストリ、エリア、デバイス、エンティティ、設定エントリのドライランは、現在のデータを読み取り、プレビューを構築します。内部の変更エンドポイントを呼び出さず、Home Assistant のサーバー側変更検証も実行しません。

• 設定エントリのリロードドライランは、提案されたリロードを報告しますが、実行時の影響を予測することはできません。

• リロード、再起動、チェックポイントロールバック、サービス所有の Git ロールバックのドライランは、利用可能な識別子/現在のメタデータを検証し、適用せずに提案された高影響アクションを説明します。

• 汎用の call_service は、ライブのサービス定義に対するドライラン検証をサポートします。サービスは呼び出されません。便利な物理制御ツールは意図的にアクションをシミュレートしません。

• 成功したドライランは、その結果に記述された検証のみを証明します。適用時に状態、権限、内部 API、ファイル、または統合の動作が変更されないことを保証するものではありません。

ファイルシステムの安全性

ファイルシステムアクセスは、HA_FILESYSTEM_ENABLED=false でユニットとして無効になります。有効な場合、リクエストは filesystem.root の下で正規化され、すべてのパスセグメントがチェックされ、シンボリックリンクは拒否されます。

許可されるパス:

• 設定ルート直下の任意の .yaml または .yml ファイル。

• 設定された allowedDirectories の下の YAML(デフォルトは packages と themes、スキャン深度 32 まで再帰的)。

• カスタムコンポーネントポリシーが有効な場合のみ、custom_components/<integration>/... の下の選択された .json、.py、.pyi、.yaml、.yml。専用ツールが制限付きソース読み取りを提供します。ソース書き込みツールや Python 実行/検証パスは公開されません。

常に保護または拒否されるもの:

• .storage、.git、Home Assistant データベース形式、秘密鍵の形式/名前、および実装された認証、資格情報、トークン、バックアップキーのパターンに一致するパス名。

• ルート外のパス、無効なパスセグメント、存在しない書き込み親ディレクトリ、通常ファイル以外のファイル、およびすべてのシンボリックリンク。

• デフォルトでは secrets.yaml と secrets.yml の値。allowSecretsMetadata: true の場合、ツールは値なしでソートされたトップレベルのシークレットキー名、バイト数、タイムスタンプを返すことができます。

allowSecretValues: false の場合、password、clientSecret、token、apiKey、private-key、credential、authorization、cookie などの機密性の高い snake_case、camelCase、ハイフン付きキーは、正規化され再帰的に編集されます。!secret/!env_var の値と一致する差分行も編集されます。

これらのチェックはパターンベースであり、コンテンツスキャナーではないため、一般的でないシークレット名がすべてのガードに一致するとは限りません。実際の値は保護されたルートの secrets.yaml に保持し、他の許可リストに登録された YAML に資格情報を保存せず、信頼できないモデルに渡す前に編集された出力を検査してください。HA_ALLOW_SECRET_VALUES=true を設定すると、ルートの secrets.yaml を含むシークレットを含む YAML の読み取りとパッチ適用が明示的に許可されます。この例外的な回復オプションは、完全に信頼できるクライアントでのみ使用してください。

書き込みは、一時ファイル、O_NOFOLLOW、fsync、アトミックな名前変更、モードの保持、SHA-256 楽観的並行性チェック、およびサポートされている場合の親ディレクトリの同期を使用します。

チェックポイント、トランザクション、およびロールバック

patch_yaml_file の非ドライランのワークフロー:

1. 許可リストに登録されたパスを解決し、現在のハッシュを読み取り、構造的な YAML 操作を適用し、構文を検証します。

2. デフォルトで /ha-config/.ha-mcp/backups の下にモードを保持するチェックポイントを作成します。

3. ハッシュを再確認し、各ファイルをアトミックに書き込みます。サーバープロセスごとに実行される設定トランザクションは 1 つだけです。

4. Home Assistant に完全な設定のチェックを依頼します。

5. 影響を受けるオートメーション/スクリプト/シーンのドメインをリロードするか、reload: false でない限り、他の/複数のパスには homeassistant.reload_all を呼び出します。

6. ヘルスチェックとして Home Assistant の設定を読み取ります。

7. 書き込み開始後に失敗した場合、ハッシュがトランザクション出力とまだ一致する場合にのみ適用されたファイルを復元し、その後リロードとヘルスチェックを試みます。

8. オプションで、変更されたパスのみを Git にコミットします。Git の失敗は、Home Assistant の変更が成功した後の警告になります。変更をロールバックしません。

エディタ管理のオートメーション/スクリプト/シーンの変更は、内部エディタエンドポイントを呼び出す前にファイルシステムチェックポイントを作成し、非ドライランの変更には設定マウントを必要とし、制限付き再試行でエディタ設定とランタイムの存在/不在を検証し、Home Assistant の設定検証を実行し、適用または検証が失敗した場合はエディタレベルのロールバックを試みます。

rollback_change は、最初に現在のファイルの安全チェックポイントを作成し、現在のハッシュの競合チェックで選択したチェックポイントを復元し、Home Assistant の設定を検証し、リロードします。検証/リロードが失敗した場合、安全チェックポイントの復元を試み、回復の失敗を報告します。チェックポイントはローカルファイルのスナップショットであり、Home Assistant Supervisor のバックアップではなく、保持クリーンアップは自動ではありません。

Git の動作と制限

Git はオプションであり、/ha-config が検出されたリポジトリ内にある場合にのみ動作します。イメージには Git CLI が含まれています。

• ステータス、履歴、差分は、設定のパス・ポリシーで許可されたパスのみに制限されます。

• コミットは、選択された許可パスのみをステージしてコミットします。フックは無効化され、署名は無効化され、作成者/コミッターの身元は設定から取得されます。

• サーバーは、初期化、クローン、フェッチ、プル、プッシュ、マージ、リベース、リモート・認証情報・ブランチ・タグ・サブモジュールの管理を行いません。

• ターゲット・パスは変更前にチェックされます。影響を受けるファイルに既にステージ済みまたは作業ツリーの変更がある場合、Home Assistant の操作はチェックポイント付きで続行できますが、自動 Git コミットはスキップされ、既存の人間による編集が MCP コミットに巻き込まれることはありません。無関係なパスは変更されません。

• rollback_to_commit は、現在の HEAD のみ、設定されたサービス・メールアドレスと一致する作成者メールを持つコミットのみ、初期コミットではないもののみ、そして影響を受けるパスに未コミットの変更がない場合のみ受け入れます。

• Git ロールバックは履歴をリセットするのではなく、新しい補償コミットを書き込みます。Home Assistant の検証が失敗した場合、以前の状態を復元するために、別のサービス所有のロールバックが試行されます。

• Git コマンドは30秒でタイムアウトします。通常の出力は4 MiBに制限され、差分は maxReadBytes の4倍、最大16 MiBに制限されます。

ツール

以下の名前は src/mcp/tools から派生しています。クライアントから見えるスキーマ、説明、注釈、リスク、ソース、安定性のメタデータは MCP ディスカバリによって返されます。

ディスカバリ

• インスタンス: get_home_assistant_info、get_system_health、get_config。

• 統合: list_integrations、get_integration。

• エリア: list_areas、get_area。

• デバイス: list_devices、get_device、search_devices。

• エンティティ: list_entities、get_entity、search_entities。

• クロスレジストリ検索: search_home_assistant_registry。

ランタイムと履歴

• サービス/イベント: list_services、list_event_types、get_events、subscribe_events。

• 状態: get_state、get_states、get_states_by_area、get_states_by_device。

• レコーダーデータ: get_history、get_logbook、get_statistics、get_recorder_statistics。

制御

• 汎用/標準制御: call_service、turn_on、turn_off、toggle、set_value、set_temperature。

• 実行: activate_scene、run_script。

オートメーション、スクリプト、シーン、トレース

• オートメーション: list_automations、get_automation、create_automation、update_automation、delete_automation、enable_automation、disable_automation、trigger_automation、reload_automations、validate_automation。

• スクリプト: list_scripts、get_script、create_script、update_script、delete_script、run_script_by_id、reload_scripts、validate_script。

• シーン: list_scenes、get_scene、create_scene、update_scene、delete_scene、activate_scene_resource、reload_scenes。

• オートメーショントレース: get_automation_traces、get_automation_trace、explain_automation_failure、get_last_automation_run。

• 汎用トレース: get_trace、list_traces、explain_trace、get_last_trace。

ヘルパーとレジストリ

• ヘルパー: list_helpers、get_helper、create_helper、update_helper、delete_helper。

• エンティティレジストリ: update_entity_registry、disable_entity、enable_entity、rename_entity、move_entity_to_area。

• デバイスレジストリ: update_device、rename_device、move_device_to_area、disable_device、enable_device。

• エリアレジストリ: create_area、update_area、delete_area、assign_device_to_area、assign_entity_to_area。

• 設定エントリ: get_config_entries、get_config_entry、reload_config_entry、update_integration、enable_integration、disable_integration。

設定とリカバリ

• 読み取り/一覧: read_configuration、list_configuration_files、read_yaml_file、list_custom_component_files、read_custom_component_source。

• パッチ/検証: patch_yaml_file、validate_configuration、validate_home_assistant_configuration。

• リロード/再起動: reload_configuration、reload_yaml_configuration、restart_home_assistant。

• 履歴/差分: get_config_history、get_config_diff、get_recent_changes。

• ロールバック: rollback_change、rollback_to_commit。

ログ、診断、依存関係、検索

• ログ: get_home_assistant_logs、search_logs、get_errors、get_warnings、get_recent_errors、get_integration_errors。

• エンティティ/デバイス検出: find_unavailable_entities、find_disabled_entities、find_orphaned_entities、find_orphaned_devices、find_duplicate_entities、find_entities_without_area、find_devices_without_area、find_stale_sensors。

• オートメーション/ヘルパー検出: find_unused_helpers、find_broken_automations、find_automation_errors、find_automations_referencing_missing_entities。

• 依存関係/検索: get_entity_dependencies、get_automation_dependencies、search_home_assistant。

ユーザーリクエストの例

• 「キッチンの利用不可エンティティを一覧表示し、そのデバイスと統合の関係を含めてください。」

• 「過去1時間の zha 統合の ERROR および CRITICAL ログエントリを表示してください。」

• 「オートメーション ID garage_arrival の最新の失敗した実行を説明してください。」

• 「欠落エンティティを参照するオートメーションを検索し、各オートメーションの依存関係を表示してください。」

• 「packages/lighting.yaml を変更する構造的な YAML パッチをドライランし、編集済みの差分のみを表示してください。」

• 「light.office をオフにしますが、他のエンティティをターゲットにしないでください。」

• 「ゲストモード用の input_boolean ヘルパーをドライランとして作成し、検証の制限を報告してください。」

• 「シーン ID old_evening を明示的な確認付きで削除し、チェックポイント、設定検証、検証、ロールバック、Git の結果を報告してください。」

モデル/クライアントは、リクエストを正確なツールスキーマに変換する必要があります。自然言語のリクエストは、モード、リスク、確認、パス、または Home Assistant の認可チェックを迂回しません。

パフォーマンスと制限

デフォルトとハードバウンドは、MCP 呼び出しが無制限の Home Assistant またはファイルシステムクエリにならないように設計されています。

長い履歴/ログブックウィンドウと完全な診断は、Home Assistant のレコーダー内で依然として高コストになる可能性があります。可能な場合は常に、エンティティ、デバイス、統合、時間範囲、ページでフィルタリングしてください。

開発

Node.js 22.23.1 と pnpm 11.21.0 が必要です。

corepack enable
pnpm --version
pnpm install --frozen-lockfile
pnpm build

依存関係のサプライチェーン

• 直接依存関係は正確なバージョンを使用します。ロックファイルは、レジストリの整合性ハッシュを含む完全なグラフを固定します。

• pnpm は、10,080 分（7日）未満のリリース、公開時刻のないパッケージ、パブリッシャーの信頼のダウングレード、異例の推移的ソース、承認されていない依存関係のビルドスクリプトを拒否します。また、インストールのたびに、固定された npm レジストリに対してロックファイルの解決データを再検証します。

• インストールはデフォルトでフリーズされたロックファイルを使用します。依存関係の変更には、明示的でレビューされた pnpm install --no-frozen-lockfile と、それに続く pnpm supply-chain:check、通常の検証スイート、およびコミットされたロックファイルの差分が必要です。

• 推移的オーバーライドは、新しいバージョンが検疫ウィンドウ内にある間、対象となる content-type と hono のリリースを固定し、undici-types をパブリッシャーの信頼をダウングレードしない証明済みリリースに固定します。レビューされた依存関係の更新中に、これらのオーバーライドを再評価しますが、自動的に削除しないでください。

• CI アクションとコンテナベースイメージは、不変のコミットまたはコンテンツダイジェストを使用します。ランタイムの Debian パッケージは日付付きスナップショットから取得されるため、再ビルドしても静かにアップグレードされることはありません。

• minimumReleaseAgeExclude 例外を追加しないでください。緊急のセキュリティリリースの場合、7日間経過するまで待つか、レビューされた変更でこのポリシーを変更する明示的な承認を得てください。

リリースの公開

v0.1.0 などの SemVer タグを持つ GitHub リリースを公開すると、.github/workflows/release-docker.yml が実行されます。linux/amd64 と linux/arm64 イメージをビルドし、バージョンタグを docker.io/lemanjo/hac-mcp にプッシュし、SBOM と来歴の証明を添付します。安定版リリースは latest も更新します。プレリリースは更新しません。

リポジトリには、以下の GitHub Actions シークレットが必要です:

• DOCKERHUB_USERNAME: Docker Hub アカウント名。現在は lemanjo。

• DOCKERHUB_TOKEN: lemanjo/hac-mcp の読み取り/書き込み権限を持つ Docker Hub パーソナルアクセストークン。アカウントのパスワードは使用しないでください。

これらは、GitHub リポジトリ > Settings > Secrets and variables > Actions > New repository secret で追加するか、GitHub CLI で追加します:

gh secret set DOCKERHUB_USERNAME --repo lemanjo/hac-mcp --body lemanjo
gh secret set DOCKERHUB_TOKEN --repo lemanjo/hac-mcp

2番目のコマンドは、トークン値を安全にプロンプトで要求します。トークンを .env、ワークフロー YAML、シェル履歴、またはリポジトリに保存しないでください。

main へのすべてのプッシュ（マージされたプルリクエストを含む）は、.github/workflows/nightly-docker.yml を実行します。これは、別の DOCKERHUB_NIGHTLY_TOKEN シークレットを使用して、nightly タグと不変の nightly-<full-commit-sha> タグを公開します。このワークフローは、GitHub Actions から手動で開始することもできます。再現性が重要な場合は、完全な SHA タグを使用してください。

gh secret set DOCKERHUB_NIGHTLY_TOKEN --repo lemanjo/hac-mcp

HTTP 開発:

HOME_ASSISTANT_URL=http://homeassistant.local:8123 \
HOME_ASSISTANT_TOKEN_FILE=/absolute/private/path/home_assistant_token \
MCP_AUTH_TOKEN_FILE=/absolute/private/path/mcp_auth_token \
MCP_CONFIG_FILE=./config.example.yaml \
MCP_TRANSPORT=http \
MCP_HOST=127.0.0.1 \
MCP_ALLOWED_HOSTS=localhost,127.0.0.1 \
HA_CONFIG_PATH=/absolute/path/to/home-assistant/config \
pnpm dev

API のみの開発の場合、HA_FILESYSTEM_ENABLED=false と HA_GIT_ENABLED=false を設定します。チェックポイントを必要とするエディタのミューテーションは、設計上利用できなくなります。

テストと検証

リポジトリのチェックを実行します:

pnpm supply-chain:check
pnpm audit --prod --audit-level high
pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm build

Docker が利用可能な環境でデプロイメントファイルを検証します:

docker compose config
docker build --check -t home-assistant-admin-mcp:check .
docker build -t home-assistant-admin-mcp:local .

次に、非本番の Home Assistant インスタンスに対して /livez、/readyz、MCP 初期化リクエスト、および代表的な読み取り専用ツールをテストします。admin を有効にする前に、内部 API の読み取り、ドライラン、使い捨てミューテーション、チェックポイントのロールバック、および Git の動作を、本番で使用するのと同じ Home Assistant バージョンとファイルシステムに対してテストします。

トラブルシューティング

サーバーが起動しない

• INVALID_CONFIGURATION: config.yaml を解析し、正確な camelCase キー、数値範囲、URL、メール形式を確認し、stderr のフラット化された検証詳細を調べます。

• MCP_AUTH_REQUIRED: HTTP には MCP_AUTH_TOKEN または MCP_AUTH_TOKEN_FILE が必要です。トリミング後、少なくとも 16 文字必要です。

• シークレットの ENOENT: Compose のシークレットソースパスは、Compose プロジェクトに対するホスト相対パスです。.env とファイルの権限を確認してください。

• stdio モードで Docker ヘルスチェックが失敗する: /livez は HTTP モードでのみ存在します。意図的な stdio コンテナの場合は、ヘルスチェックを削除するかオーバーライドしてください。

MCP 401、403、または 413

• 401: MCP ベアラートークンが存在しない、間違っている、または不正な形式です。認証スキームは大文字小文字を区別せず、Bearer でなければなりません。

• 403 ツール呼び出し前: リクエストの実際のホスト名を MCP_ALLOWED_HOSTS に追加し、ブラウザクライアントの場合は、スキームとポートを除いたオリジンホスト名を MCP_ALLOWED_ORIGINS に追加します。任意のワイルドカードを追加しないでください。

• 413 または JSON 解析拒否: リクエストを減らすか、mcp.maxRequestBytes を 10 MiB の制限内で増やします。

• リバースプロキシの失敗: Authorization、Host、Origin、Accept、Content-Type、MCP-Protocol-Version の各ヘッダー、HTTP ストリーミング、および SSE の動作を保持してください。

/readyz が 503 を返す、または Home Assistant の呼び出しが失敗する

• ブリッジコンテナ内からは、localhost は MCP コンテナであり、Home Assistant ではありません。host.docker.internal、LAN アドレス、または共有ネットワークエイリアスを使用してください。

• HA_AUTH_FAILED/HA_WS_AUTH_FAILED: Home Assistant の長期アクセストークンを置き換えるか再作成します。

• HA_PERMISSION_DENIED: トークンのユーザーに、要求されたエンティティ、サービス、または設定エントリに対する権限または管理者ステータスがありません。

• HA_TLS_ERROR/HA_WS_TLS_ERROR: 信頼できる証明書チェーンをインストールするか、管理されたプライベートネットワーク上でのみ HA_VERIFY_TLS=false を設定します。サーバー ID は検証されなくなることに注意してください。

• 履歴、ログブック、または統計のエラー: recorder/logbook 統合がロードされていること、および要求された ID と時間範囲が存在することを確認します。

ファイルシステムまたは Git が失敗する

• CONFIG_ROOT_UNAVAILABLE/権限拒否: HA_CONFIG_PATH が正しく、PUID/PGID によって書き込み可能であることを確認します。コンテナは意図的に root では実行されません。

• CONFIG_PATH_NOT_ALLOWED: ルート YAML または許可されたディレクトリを使用します。保護されたパス、シンボリックリンク、任意の拡張子、存在しない親ディレクトリは拒否されます。

• CONFIG_CONCURRENT_MODIFICATION/ROLLBACK_CONFLICT: 別のプロセスがファイルを変更しました。上書きを強制するのではなく、再読み取り、再確認、再試行してください。

• Git is enabled but no repository was detected: MCP の外部でリポジトリを初期化/管理するか、HA_GIT_ENABLED=false を設定します。

• Git が「dubious ownership」を報告: コンテナの UID/GID をリポジトリの所有者に合わせるか、その逆を行います。root で実行して解決しないでください。

• チェックポイントがスペースを消費: オペレーター定義の保持ポリシーを .ha-mcp/backups に適用します。自動削除ツールはありません。

内部ツールが Home Assistant のアップグレード後に失敗する

• コマンドが、リンクされた現在のコアソースにまだ存在することを確認し、リクエスト/レスポンスのフィールドを比較します。

• 最初に読み取り専用操作を再試行します。検証またはロールバックのステータスが不明な場合は、ミューテーションを繰り返し再試行しないでください。

• 互換性がテストされ、レビューされるまで、Home Assistant の UI を使用してヘルパー、統合、またはリソースを変更します。

• 互換性がテストされ、レビューされるまで MCP_MODE=read_only を維持します。

ライセンス

MIT