Ambient Home Assistant MCP

Ambient Home Assistant MCP ist eine sichere, semantische Brücke, die ChatGPT und anderen MCP-Clients einen speziell entwickelten Zugriff auf Home Assistant bietet. Es ist die Server-Grundlage für die zukünftige benutzerorientierte Anwendung Ambient Home Assistant.

Phase-2-Status: lokal/privat und schreibgeschützt. Diese Version fügt semantische Entitätserkennung, aktuellen Zustand, Bereiche, Etagen und Domänenübersichten hinzu. Sie kann keine Geräte steuern oder Home Assistant ändern.

Was es ist – und was es nicht ist

Die Brücke ist eine Abstraktions- und Sicherheitsschicht. Im Laufe der Zeit kann sie zwischen Home-Assistant-REST-, WebSocket- und nativen MCP/Assist-Schnittstellen wählen und dem Modell dabei kleine, semantische Werkzeuge präsentieren.

Sie ist nicht:

• ein Ersatz für Home Assistant;

• eine uneingeschränkte Home-Assistant-Administrator-API;

• ein generischer API-Wrapper, der einem LLM ausgesetzt ist; oder

• ein Reverse-Proxy für den /api/mcp-Endpunkt von Home Assistant.

Related MCP server: ha-ai-learner

Architektur

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-Tools senden niemals rohe HTTP-Anfragen. Sie sind von HomeAssistantClient abhängig, der die Schnittstellenauswahl übernimmt und Upstream-Antworten sofort normalisiert. Siehe das Architektur-Entscheidungsprotokoll.

Funktionen

Es sind keine Serviceaufrufe, Zustandsänderungen oder administrativen Endpunkte implementiert.

Sicherheitsmodell

• Home-Assistant-Tokens stammen nur aus der Laufzeitkonfiguration und verwenden Pydantic-Geheimnistypen.

• Protokolle sind strukturiert und schwärzen Bearer-Tokens und häufige Anmeldefelder.

• Rohe /api/config-Daten werden auf ein zugelassenes Modell reduziert, bevor sie ein Tool-Ergebnis erreichen können.

• Detaillierte Entitätsattribute verwenden eine explizite Zulassungsliste und schließen URLs, Kameraquellen, Tokens, Anmeldeinformationen, Koordinaten und standortbezogene Metadaten aus.

• Aktuelle Zustände werden nie zwischengespeichert. Registrierungsmetadaten verwenden einen begrenzten 60-Sekunden-TTL-Cache, um wiederholte WebSocket-Authentifizierung und Registrierungslesevorgänge zu vermeiden.

• MCP-Transport-Host- und Origin-Zulassungslisten schützen vor DNS-Rebinding.

• Die Richtlinien-Engine erlaubt Lesevorgänge und schlägt für jede Steuerklasse fehl (fail closed).

• Der Container läuft als Nicht-Root-Benutzer mit einem schreibgeschützten Dateisystem in Compose.

Committen Sie niemals .env, Home-Assistant-Tokens, Anmeldeinformationen, private URLs oder Zertifikate. Siehe Sicherheit vor jeglichen Bereitstellungsarbeiten.

Schnellstart

Voraussetzungen: Python 3.12+ und 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

Der Streamable-HTTP-MCP-Endpunkt ist http://127.0.0.1:8000/mcp; der Health-Endpunkt ist unter http://127.0.0.1:8000/health erreichbar.

Untersuchen Sie die Tools lokal:

npx @modelcontextprotocol/inspector@latest

Verbinden Sie dann den Inspector mit http://127.0.0.1:8000/mcp.

Entwicklungsbefehle

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

Regenerieren Sie die Abhängigkeitssperre nach einer beabsichtigten Änderung der Abhängigkeiten:

uv lock

Docker Compose

Kopieren Sie .env.example in .env, geben Sie die beiden erforderlichen Home-Assistant-Einstellungen an und führen Sie docker compose up --build aus. Compose veröffentlicht nur auf dem Host-Loopback.

Die Docker-Health-Prüfung testet die Lebendigkeit der Anwendung. Ein vorübergehender Home-Assistant-Ausfall ändert /health auf status: degraded, lässt aber den HTTP-Status 200, sodass der Orchestrator eine gesunde Brücke nicht in einer Schleife neu startet.

Dokumentation

• Architektur

• Sicherheit

• Tool-Verträge

• Entwicklung

• ChatGPT-Einrichtung und aktuelle Einschränkungen

Lizenz

MIT. Siehe LICENSE.