Ambient Home Assistant MCP
OfficialAmbient 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 |
| Meldet Erreichbarkeit und Authentifizierungsstatus, ohne Anmeldeinformationen preiszugeben. |
| Gibt nur Version, Zeitzone und Einheitensystem-Metadaten zurück. |
| Ruft eine aktuelle Entität anhand der exakten Entitäts-ID mit aufgelöstem Standort und sicheren Attributen ab. |
| Durchsucht aktuelle Entitäten nach Name/ID und kombinierbaren Domänen-, Bereichs-, Etagen-, Zustands- und Verfügbarkeitsfiltern. |
| Listet kompakte Bereiche auf oder ruft einen Bereich mit Domänenzählungen und einer optionalen begrenzten Entitätsliste ab. |
| Listet Etagen auf oder ruft eine Etage mit Bereichs- und Domänenaggregaten ab. |
| Fasst beobachtete Zustände und Verfügbarkeit für jede Entitätsdomäne zusammen. |
| 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-mcpDer 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@latestVerbinden 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 --buildRegenerieren Sie die Abhängigkeitssperre nach einer beabsichtigten Änderung der Abhängigkeiten:
uv lockDocker 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…
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