Ambient Home Assistant MCP
OfficialAmbient Home Assistant MCP
Ambient Home Assistant MCPは、ChatGPTやその他のMCPクライアントに、Home Assistantへの専用アクセスを提供する、安全でセマンティックなブリッジです。これは、将来のユーザー向けAmbient Home Assistantアプリケーションのサーバー基盤です。
フェーズ2のステータス: ローカル/プライベートかつ読み取り専用です。このリリースでは、セマンティックなエンティティ検出、現在の状態、エリア、フロア、ドメインのサマリーが追加されています。デバイスの制御やHome Assistantの変更はできません。
何であるか—そして何でないか
このブリッジは抽象化およびセキュリティレイヤーです。将来的には、Home Assistant REST、WebSocket、ネイティブMCP/Assistインターフェースの中から選択しつつ、モデルに小さなセマンティックなツールを提示できます。
これはではありません:
Home Assistantの代替品;
無制限のHome Assistant管理者API;
LLMに公開される汎用APIラッパー; または
Home Assistantの
/api/mcpエンドポイントのリバースプロキシ。
Related MCP server: homeassistant-gateway
アーキテクチャ
flowchart TD
C[ChatGPT or MCP client] -->|MCP| A[Ambient Home Assistant MCP]
A --> T[Semantic tools]
A --> P[Policy and security]
A --> N[Normalized data and diagnostics]
T --> H[Home Assistant client facade]
P --> H
N --> H
H --> R[REST state API]
H --> W[WebSocket registries]
H -. selective future use .-> M[HA MCP or Assist API]MCPツールは生のHTTPリクエストを行いません。インターフェースの選択を担い、アップストリームのレスポンスを即座に正規化するHomeAssistantClientに依存しています。アーキテクチャ決定記録を参照してください。
機能
サーフェス | 目的 |
| 資格情報を公開せずに到達可能性と認証状態を報告します。 |
| バージョン、タイムゾーン、単位系のメタデータのみを返します。 |
| 解決された場所と安全な属性を含む、正確なエンティティIDによる現在のエンティティを1つ取得します。 |
| 名前/IDと、合成可能なドメイン、エリア、フロア、状態、可用性フィルターで現在のエンティティを検索します。 |
| コンパクトなエリアの一覧を取得するか、ドメイン数とオプションの制限付きエンティティリストを含む1つのエリアを取得します。 |
| フロアの一覧を取得するか、エリアとドメインの集計を含む1つのフロアを取得します。 |
| 任意のエンティティドメインについて、観測された状態と可用性を要約します。 |
| アプリケーションの生存性と、別個のHome Assistantの準備状態を報告します。 |
サービスコール、状態変更、管理エンドポイントは実装されていません。
セキュリティモデル
Home Assistantトークンはランタイム設定からのみ取得され、Pydanticのシークレット型を使用します。
ログは構造化されており、ベアラートークンと一般的な資格情報フィールドを編集(redact)します。
生の
/api/configデータは、ツールの結果に到達する前に許可リスト化されたモデルに縮小されます。詳細なエンティティ属性は明示的な許可リストを使用し、URL、カメラソース、トークン、資格情報、座標、位置情報を含むメタデータを除外します。
現在の状態は決してキャッシュされません。レジストリメタデータは、繰り返しのWebSocket認証とレジストリ読み取りを避けるために、制限付きの60秒TTLキャッシュを1つ使用します。
MCPトランスポートのHostおよびOrigin許可リストは、DNSリバインディングから保護します。
ポリシーエンジンは読み取りを許可し、すべての制御クラスに対してフェイルクローズします。
コンテナはCompose内で読み取り専用ファイルシステムを持つ非rootユーザーとして実行されます。
.env、Home Assistantトークン、資格情報、プライベートURL、証明書をコミットしないでください。デプロイ作業の前にセキュリティを参照してください。
クイックスタート
要件: Python 3.12+ と uv。
cp .env.example .env
# Edit .env and provide HOME_ASSISTANT_URL and HOME_ASSISTANT_TOKEN.
uv sync --all-extras
uv run ambient-ha-mcpStreamable HTTP MCPエンドポイントはhttp://127.0.0.1:8000/mcpです。ヘルスチェックはhttp://127.0.0.1:8000/healthにあります。
ツールをローカルで検査:
npx @modelcontextprotocol/inspector@latest次に、Inspectorをhttp://127.0.0.1:8000/mcpに接続します。
開発コマンド
uv sync --all-extras # install
uv run ambient-ha-mcp # run locally
uv run pytest # unit tests; real HA tests skip by default
uv run ruff check . # lint
uv run ruff format --check . # formatting check
uv run mypy # type check
docker build -t ambient-ha-mcp .
docker compose up --build意図的な依存関係の変更後、依存関係ロックを再生成します:
uv lockDocker Compose
.env.exampleを.envにコピーし、必要な2つのHome Assistant設定を入力して、docker compose up --buildを実行します。Composeはホストのループバックにのみ公開します。
Dockerのヘルスプローブはアプリケーションの生存性をテストします。一時的なHome Assistantの停止により/healthはstatus: degradedに変わりますが、HTTPステータスは200のままなので、オーケストレーターが正常なブリッジをループで再起動することはありません。
ドキュメント
ライセンス
MIT。LICENSEを参照してください。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
The HubSpot MCP Server acts as a bridge that enables AI assistants and Large Language Models to securely interact with HubSpot CRM data through natural conversation, without requiring users to understand complex API structures. It provides read-only access to standard CRM objects (contacts, companies, deals, tickets, products, invoices, and more) and their associations, secured via OAuth 2.0, allowing AI agents to perform tasks like summarizing deals, fetching company updates, and looking up record changes.
Read-only MCP server exposing a user ORANO library to their own AI agent.
Read-only Google Analytics 4 MCP server for AI assistants.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA self-learning discovery tool + MCP server that turns your Home Assistant into knowledge an AI assistant can actually use.MIT
- AlicenseNot gradedqualityBmaintenanceEnables secure, auditable access to Home Assistant through MCP, with a read-only observer profile and an operator profile for controlled mutations.2MIT
- AlicenseNot gradedqualityCmaintenanceExposes a curated allowlist of Home Assistant entities to external clients over MCP with read-only list and get_state tools, using an isolated guest credential that cannot access other Home Assistant APIs.1Apache 2.0
- AlicenseAqualityDmaintenanceRead-only MCP server for Home Assistant that computes statistical summaries, trends, and session detection from recorded sensor history, returning compact tables instead of raw data so small local models can answer questions about energy usage, climate, and appliance activity without token-heavy arithmetic.107 npmApache 2.0