Skip to main content
Glama
Ambient Home Assistant MCP

Ambient Home Assistant MCP

Official

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: homeassistant-gateway

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

Schnittstelle

Zweck

ha_connection_status

Meldet Erreichbarkeit und Authentifizierungsstatus, ohne Anmeldeinformationen preiszugeben.

ha_server_info

Gibt nur Version, Zeitzone und Einheitensystem-Metadaten zurück.

ha_get_entity

Ruft eine aktuelle Entität anhand der exakten Entitäts-ID mit aufgelöstem Standort und sicheren Attributen ab.

ha_search_entities

Durchsucht aktuelle Entitäten nach Name/ID und kombinierbaren Domänen-, Bereichs-, Etagen-, Zustands- und Verfügbarkeitsfiltern.

ha_list_areas / ha_get_area

Listet kompakte Bereiche auf oder ruft einen Bereich mit Domänenzählungen und einer optionalen begrenzten Entitätsliste ab.

ha_list_floors / ha_get_floor

Listet Etagen auf oder ruft eine Etage mit Bereichs- und Domänenaggregaten ab.

ha_domain_summary

Fasst beobachtete Zustände und Verfügbarkeit für jede Entitätsdomäne zusammen.

GET /health

Meldet die Lebendigkeit der Anwendung und die separate Bereitschaft von Home Assistant.

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

Lizenz

MIT. Siehe LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A self-learning discovery tool + MCP server that turns your Home Assistant into knowledge an AI assistant can actually use.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables secure, auditable access to Home Assistant through MCP, with a read-only observer profile and an operator profile for controlled mutations.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes 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.
      1
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Read-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.
      10
      7 npm
      Apache 2.0