Home Assistant MCP

Ein OAuth-geschützter Model Context Protocol (MCP)-Server für die sichere Verbindung von ChatGPT, Codex und anderen MCP-Clients mit Home Assistant.

Das Projekt stellt 99 typisierte Tools für Erkennung, Dashboards, Zeitpläne, Klima, Energie, Medien, Reinigung, Bewässerung, Automatisierungen, Diagnose und sorgfältig begrenzte Gerätesteuerung bereit. Es hält die API von Home Assistant privat und vermeidet bewusst, eine generische Shell, ein Log-Leser, ein Netzwerkscanner oder ein uneingeschränkter Service-Proxy zu werden.

[!WICHTIG] Dies ist eine sicherheitsrelevante Referenzimplementierung für eine selbst gehostete Home-Assistant-Installation. Lesen Sie das Sicherheitsmodell, ersetzen Sie jeden Beispielwert und prüfen Sie die Whitelists, bevor Sie es mit einem echten Zuhause verbinden.

Highlights

• Typisierter Home-Assistant-Zugriff: Entitäten, Geräte, Bereiche, Verlauf, Wetter, Kalender, Zeitpläne, Statistiken, Integrationen, Dashboards, To-do-Listen, Automatisierungen, Backups und Systemzustand.

• Begrenzte Schreibvorgänge: Klima, Lichter, Szenen, Mediaplayer, Staubsauger, Abdeckungen, Schlösser, Sirenen, Benachrichtigungen, Dashboards, Zeitpläne, Kalender, To-do-Einträge und Automatisierungen verwenden validierte Eingaben und enge Service-Whitelists.

• Sprinklerunterstützung: Live-Controller-Status, Zonenmetadaten, Konfiguration, Bewässerungsverlauf, Telemetrie-Aktualisierung, Zonen- oder Sequenzstarts und idempotente Stopp-Operationen.

• Energie und SolarEdge: Produktion, Modulvergleich, Leistungsfluss, Energie- Aufschlüsselungen, Speicherzusammenfassungen, Telemetrie, Warnungen und eine optionale Home-Assistant- Bridge-Integration.

• Persistente Fähigkeitssynchronisierung: Vergleicht das aktuelle Service-Register von Home Assistant alle fünf Minuten mit der geprüften Release-Baseline und meldet Abweichungen, ohne dynamisch neue Schreibvorgänge offenzulegen.

• Bereinigte Diagnose: optionale Festroute, Host/Laufzeit, Ausfall und festes Subnetz-LAN mit strengen Grenzen und ohne rohe Adressen, beliebige Ziele, Befehle oder Gerätesteuerung.

• OAuth-nativer Fernzugriff: Autorisierungscode-Fluss mit S256 PKCE, dynamischer Client-Registrierung, bereichsbezogenen Zugriffstokens und MCP-Ressourcenmetadaten.

Version 2.6.1 bewirbt derzeit 99 Tools. Siehe CHANGELOG.md für den Versionsverlauf.

Architektur

flowchart LR
    Client[ChatGPT, Codex, or MCP client]
    Edge[HTTPS edge<br/>Cloudflare Worker, tunnel, or reverse proxy]
    MCP[Home Assistant MCP<br/>OAuth + typed tools]
    HA[Private Home Assistant API]
    Data[(OAuth, audit, and<br/>capability-sync state)]
    Collector[Optional root-owned<br/>diagnostics collector]
    Export[Sanitized read-only export]

    Client -->|HTTPS + OAuth/PKCE| Edge
    Edge -->|loopback or shared-secret origin| MCP
    MCP -->|long-lived service token| HA
    MCP --> Data
    Collector --> Export --> MCP

Die Referenzbereitstellung bindet den MCP-Dienst an 127.0.0.1:8000. Nur der HTTPS-Rand ist öffentlich. Home Assistant kann lokal auf dem Host bleiben oder über ein privates Netzwerk erreichbar sein.

Tool-Oberfläche

Risikoreichere Aktionen sind als destruktiv gekennzeichnet und erfordern ein explizites Bestätigungsargument. Das genaue Register ist maßgeblich; prüfen Sie es nach der Bereitstellung über einen authentifizierten MCP-Client.

Anforderungen

• Home Assistant, erreichbar vom MCP-Host.

• Ein dediziertes Home-Assistant-Langzeit-Zugriffstoken. Verwenden Sie nach Möglichkeit eine separate Dienstidentität.

• Python 3.12 oder neuer und uv für Entwicklung und Tests.

• Docker mit Compose für die Referenz-Containerbereitstellung.

• Eine öffentliche HTTPS-URL für entfernte MCP-Clients.

• Ein HTTPS-Rand, der den MCP über Loopback erreicht oder das konfigurierte Origin-Shared-Secret injiziert. Die enthaltenen Caddy- und Cloudflare-Beispiele zeigen diese beiden Muster.

• Linux und systemd nur, wenn der optionale Host-Diagnosekollektor verwendet wird.

Die gebündelte Compose-Datei ist eine Produktionsreferenz, kein universelles Ein-Befehl- Installationsprogramm. Sie setzt Host-Netzwerk, eine vorhandene Home-Assistant-Konfiguration unter /opt/homeassistant/config und einen installierten Diagnoseexport unter /var/lib/ha-host-diagnostics/export voraus. Passen Sie diese Mounts an Ihre Installation an, ohne die Home-Assistant-API oder den Docker-Socket offenzulegen.

Schnellstart für die Entwicklung

Klonen Sie das Repository und installieren Sie die gesperrten Abhängigkeiten:

git clone https://github.com/shogun301/ha-chatgpt-mcp.git
cd ha-chatgpt-mcp
uv sync --frozen

Die Testsuite und die Public-Source-Prüfung benötigen keine Produktionsanmeldedaten:

uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

Um den Dienst auszuführen, kopieren Sie .env.example in eine ignorierte .env, ersetzen Sie jede Beispiel-Domain und Entitäts-ID und stellen Sie die erforderlichen Laufzeitpfade und Geheimnisdateien bereit, die unten beschrieben werden. Die Anwendung lädt .env nicht automatisch; exportieren Sie die Variablen in Ihrem Prozessmanager, verwenden Sie uvicorn --env-file .env oder lassen Sie Docker Compose sie laden.

Für einen lokalen Prozess nach der Konfiguration der Umgebung:

uv run uvicorn app.server:app --host 127.0.0.1 --port 8000 --no-proxy-headers

Für die Referenz-Containerbereitstellung nach der Anpassung seiner Mounts und optionalen Integrationen:

docker compose build --pull
docker compose up -d
curl --fail http://127.0.0.1:8000/healthz

Binden Sie Uvicorn nicht direkt an eine öffentliche Schnittstelle.

Konfiguration

Kerneinstellungen

Entitätsspezifische Variablen in .env.example ordnen die generische Tool-Oberfläche den Präsenz-, Benachrichtigungs-, Staubsauger-, Sprinkler-, Thermostat- und Zeitplan-Entitäten einer Bereitstellung zu. Bewahren Sie echte Entitäts-IDs in der lokalen Konfiguration auf, nicht in Git.

Erforderliche Geheimnisdateien

Der Server liest Geheimnisse aus Dateien statt aus Umgebungsvariablen:

Generieren Sie zufällige Werte mit einem kryptografisch sicheren Generator. Ein Argon2- Kennwort-Hash kann erzeugt werden, ohne das Kennwort in den Shell-Verlauf zu legen:

uv run python -c "from argon2 import PasswordHasher; from getpass import getpass; print(PasswordHasher().hash(getpass('OAuth password: ')))"
uv run python -c "import secrets; print(secrets.token_urlsafe(48))"

Speichern Sie die Ausgaben in separaten Dateien mit Nur-Eigentümer-Berechtigungen. Committen Sie niemals secrets/, .env, Tokens, Kennwörter, Hashes, private Domains, Entitäts- Inventare, Zeitpläne oder Netzwerktopologie.

Optionale SolarEdge-Konfiguration

Die SolarEdge-Unterstützung verwendet optionale Client-Anmeldedaten, einen verschlüsselten Token-Speicher, ein Bridge-Geheimnis, einen Redirect-URI und geschützte Portal-Fallback-Anmeldedaten. Wenn Sie SolarEdge nicht verwenden, lassen Sie die entsprechenden SOLAREDGE_*_FILE-Variablen weg. Die Referenz-Compose-Datei setzt diese Pfade, also stellen Sie entweder die Dateien bereit oder entfernen Sie diese Einträge in Ihrem lokalen Override.

OAuth-Bereiche

• mcp:read erlaubt Lese-Tools.

• mcp:write erlaubt die geprüfte Schreib-Oberfläche und erfüllt auch die aktuelle stärkste Kompatibilitäts-Gewährung.

• mcp:diagnostics erlaubt zusammen mit mcp:read privilegierte schreibgeschützte Host- und LAN-Diagnose, ohne Geräteschreibvorgänge zu gewähren.

Verbinden Sie Clients mit https://your-mcp-host.example/mcp. Der Server veröffentlicht OAuth-Autorisierungsserver-, geschützte Ressourcen-, OpenID-Konfigurations- und dynamische Client-Registrierungsmetadaten unter derselben Origin.

Edge-Optionen

Die Anwendung verlangt, dass Nicht-Loopback-Anfragen das konfigurierte Origin-Shared- Secret tragen. Zwei Beispiele sind enthalten:

• cloudflare/ enthält einen schmalen Cloudflare-Worker-Proxy. Er leitet nur die MCP-, OAuth-, Health- und SolarEdge-Callback-Pfade weiter, erzwingt ein 1-MiB-Anfragelimit, fügt das Origin-Geheimnis hinzu und entfernt unnötige Header.

• Caddyfile bietet einen HTTPS-Reverse-Proxy auf demselben Host zum Loopback-MCP-Listener.

Der enthaltene cloudflared-Dienst verwendet eine Token-Datei und veröffentlicht Metriken nur über Loopback. Ersetzen Sie alle Beispielrouten und halten Sie die MCP-Origin, die Home-Assistant- API und den Metrik-Listener vom öffentlichen Netzwerk fern.

Fähigkeitssynchronisierung

Home-Assistant-Integrationen können Dienste unabhängig von diesem Projekt hinzufügen oder entfernen. Der Server fragt daher alle fünf Minuten das Dienstregister von Home Assistant ab und speichert eine releasegebundene Baseline in /data/ha-capability-sync.json.

get_capability_sync_status meldet hinzugefügte oder entfernte Dienste und Feld-Schema- Änderungen über Neustarts hinweg. Der Monitor ist bewusst beobachtend: Er ruft niemals einen Dienst auf und macht niemals aus einem nicht geprüften Home-Assistant-Dienst ein neues MCP-Schreib-Tool. Neue Funktionalität sollte geprüft, als typisierte Tools implementiert, getestet und über Git veröffentlicht werden.

Optionale Host- und LAN-Diagnose

Der systemd-Kollektor unter collector/ hat keinen Listener und akzeptiert keinen vom Aufrufer gewählten Befehl, Pfad, Container, Log-Ausdruck oder URL. Er veröffentlicht begrenzte, bereinigte Snapshots und Journale in ein festes Verzeichnis. Der MCP- Container erhält nur dieses Verzeichnis als schreibgeschützten Mount – niemals den Docker- Socket, das Host-Journal, procfs, sysfs oder systemd-Steuerung.

Die LAN-Tools arbeiten nur innerhalb eines konfigurierten /24, geben undurchsichtige Knoten-IDs zurück, verwenden eine geschlossene TCP-Dienst-Whitelist, senden keine Anwendungs-Payloads und lassen rohe Adressen weg. Sie können keine beliebigen Netzwerke scannen oder Geräte steuern.

Siehe docs/operations.md und collector/README.md für das vollständige Datenmodell, Aufbewahrungsgrenzen, Bereitstellung, Verifizierung, Vorfall- und Rollback-Verfahren.

Sicherheitsmodell

Dieser Server ist bewusst enger gefasst als die Home Assistant API:

• Keine Shell-Ausführung, kein beliebiger WebSocket-Durchgriff, keine beliebigen Dateien, keine Roh-Logs, keine Docker-Verwaltung, kein Dienst-Neustart, kein Herunterfahren, kein Abruf von Anmeldedaten, keine Kamerabilder und keine Entschärfung der Alarmanlage.

• Generische Home Assistant-Dienstaufrufe sind nach Domäne und Dienst auf eine Positivliste beschränkt; dedizierte, typisierte Werkzeuge werden bevorzugt.

• Eingaben werden schemavalidierend geprüft, Ergebnisgrößen sind begrenzt und sensible Diagnosefelder werden rekursiv geschwärzt.

• Destruktive oder physische Operationen verwenden explizite Annotationen und Bestätigungsstufen.

• Prüfprotokolle enthalten Werkzeugnamen und begrenzte Metadaten, keine Anmeldedaten oder zurückgegebene Diagnosebelege.

• Der Container läuft als Benutzer ohne Privilegien mit einem schreibgeschützten Dateisystem, allen Linux-Capabilities entzogen und no-new-privileges aktiviert.

• Der Audit für die öffentliche Veröffentlichung prüft sowohl den aktuellen Baum als auch die Git-Historie vor der Veröffentlichung.

Verwenden Sie niemals einen Thermostat, ein Licht, ein Schloss, einen Staubsauger, einen Sprenger, eine Kamera, einen Lautsprecher, ein Fernsehgerät, ein Backup, eine Benachrichtigung oder einen anderen physischen Nebeneffekt als Konnektivitätstest.

Für die Meldung von Schwachstellen und den Umgang mit sensiblen Bereitstellungsinformationen lesen Sie SECURITY.md.

Bereitstellung und Verifizierung

Das PowerShell-Bereitstellungsskript in scripts/deploy-production.ps1 ist eine meinungsbildende AWS-Lightsail-Referenz. Es erfordert explizite AWS-Profil-, Region-, Instanz-, Frontend-URL- und MCP-URL-Parameter; verpackt den geprüften Quellcode; erstellt Backups; stellt den Collector und den Container bereit; führt die Verifizierung aus; und unterstützt Rollback. Prüfen Sie es sorgfältig, bevor Sie es an einen anderen Host anpassen.

Vor jedem öffentlichen Push oder jeder Produktionsveröffentlichung:

uv sync --frozen
uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

Verifizieren Sie dann, ohne den Gerätezustand zu ändern:

1. /healthz ist lokal und über den öffentlichen Edge erfolgreich.

2. Nicht authentifizierte und ungültige Token-MCP-Anfragen werden abgelehnt.

3. Die authentifizierte Erkennung meldet die erwartete Version und Werkzeuganzahl.

4. Schreibgeschützte Übersichts-, Fähigkeitssynchronisations-, Routen- und Integrationsprüfungen sind erfolgreich.

5. Der öffentliche Git-Commit, das bereitgestellte Artefakt und die gemeldete Dienstversion sind identisch.

Produktionsabläufe und Rollback-Stufen sind in docs/operations.md beschrieben.

Mitwirken

Issues und Pull Requests sind willkommen, wenn sie das begrenzte Sicherheitsmodell des Projekts bewahren.

Für neue Werkzeuge:

1. Bevorzugen Sie eine enge, typisierte Operation gegenüber generischem Durchgriff.

2. Definieren Sie schreibgeschützte, idempotente, schreibende oder destruktive Annotationen genau.

3. Validieren Sie Entitätsdomänen, Aufzählungen, Längen, Zeitfenster und Ergebnislimits.

4. Verlangen Sie eine explizite Bestätigung für folgenreiche physische oder administrative Aktionen.

5. Fügen Sie Autorisierungs-, Negativpfad-, Schwärzungs- und Regressionstests hinzu.

6. Aktualisieren Sie die Fähigkeitsdokumentation und führen Sie den öffentlichen Historie-Audit aus.

Nehmen Sie keine echten Haushaltskonfigurationen, privaten URLs, Anmeldedaten, Logs, Tokens, Zeitpläne, Topologien oder Anbieterantworten in ein Issue, eine Fixture, einen Screenshot, einen Commit oder einen Pull Request auf.

Lizenz

Derzeit ist keine Open-Source-Lizenz enthalten. Die öffentliche Sichtbarkeit gewährt keine Erlaubnis, den Code zu kopieren, zu modifizieren oder weiterzuverbreiten. Repository-Besitzer sollten vor der Annahme von Wiederverwendung oder Weiterverbreitung eine explizite Lizenz hinzufügen.

Referenzen

• Model Context Protocol

• OpenAI: Build an MCP server

• OpenAI: Authenticate users

• Cloudflare Tunnel monitoring

• Cloudflare Tunnel metrics