Ambient 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: ha-ai-learner

アーキテクチャ

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に依存しています。アーキテクチャ決定記録を参照してください。

機能

サービスコール、状態変更、管理エンドポイントは実装されていません。

セキュリティモデル

• 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-mcp

Streamable 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 lock

Docker Compose

.env.exampleを.envにコピーし、必要な2つのHome Assistant設定を入力して、docker compose up --buildを実行します。Composeはホストのループバックにのみ公開します。

Dockerのヘルスプローブはアプリケーションの生存性をテストします。一時的なHome Assistantの停止により/healthはstatus: degradedに変わりますが、HTTPステータスは200のままなので、オーケストレーターが正常なブリッジをループで再起動することはありません。

ドキュメント

• アーキテクチャ

• セキュリティ

• ツール契約

• 開発

• ChatGPTのセットアップと現在の制限

ライセンス

MIT。LICENSEを参照してください。