Home Assistant mit ChatGPT steuern: MCP-Server einrichten

Ab Home Assistant 2025.2 gibt es einen offiziellen MCP-Server als Integration. Damit kann ein KI-Client wie ChatGPT oder Claude direkt mit deiner Instanz reden: Licht schalten, Szenen starten, Sensorwerte abfragen. Ich habe mir das Ganze mal von Grund auf angeschaut und hier ist die Anleitung, die ich mir damals gewünscht hätte.

Was du brauchst

Home Assistant ab Version 2025.2 mit der Integration Model Context Protocol Server. Mindestens ein paar Entities müssen für Assist freigegeben sein, sonst sieht die KI nichts. Für die lokalen Wege, also Claude Desktop und ChatGPT Desktop, brauchst du außerdem einen Long-Lived Access Token aus deinem HA-Profil. Für ChatGPT im Browser brauchst du stattdessen eine öffentlich erreichbare HA-URL mit HTTPS, zum Beispiel über Nabu Casa, und OAuth.

Ein Punkt, der mich am Anfang überrascht hat: Nicht jeder ChatGPT-Plan kann wirklich alles. Hier eine kurze Übersicht:

Für echte HA-Steuerung per ChatGPT brauchst du also aktuell Business, Enterprise oder Edu. Pro kann abfragen, aber nicht steuern. Claude Desktop hat diese Einschränkung nicht.

Noch ein wichtiger Unterschied: ChatGPT Desktop startet einen lokalen Prozess auf deinem Rechner und erreicht damit homeassistant.local oder private IPs. chatgpt.com im Browser kann das nicht. Dort läuft die Verbindung aus der OpenAI-Cloud und braucht öffentliches HTTPS plus OAuth.

Was ist der MCP-Server eigentlich?

MCP steht für Model Context Protocol, ein offener Standard. Ein KI-Client spricht darüber mit einem Server, der Werkzeuge anbietet. Der HA-MCP-Server stellt die Assist-Werkzeuge bereit, also dieselben Aktionen wie die HA-Sprachsteuerung. Der Client sieht und steuert dabei nur die Entities, die du bewusst für Assist freigegeben hast.

Das ist auch der Grund, warum ich das Ganze sinnvoll finde: Du entscheidest vorher, was die KI überhaupt sehen darf.

Schritt 1: Entities für Assist freigeben

Ohne Freigabe sieht die KI nichts. Diese Liste ist gleichzeitig deine Sicherheitsgrenze, also nimm dir kurz Zeit dafür.

Geh auf Einstellungen, dann Sprachassistenten und öffne den Reiter „Freigegebene Entitäten". Dort wählst du bewusst aus, was die KI steuern und sehen darf, zum Beispiel Wohnzimmerlicht, Temperatursensoren oder Szenen. Sensibles wie Türschlösser oder Kameras würde ich bewusst draußen lassen.

Meine Faustregel: Was ich auch per Sprachbefehl steuern würde, gebe ich frei. Der Rest bleibt außen vor.

Schritt 2: MCP-Server-Integration hinzufügen

Das ist wahnsinnig einfach. Geh auf Einstellungen, dann Geräte & Dienste und klick auf „Integration hinzufügen". Such nach Model Context Protocol Server und wähle die Integration aus. Im Dialog wählst du dann die bereitzustellende LLM-API. Standard ist Assist, das reicht für Licht, Szenen und Sensoren. Bestätigen, fertig.

Ab jetzt lauscht Home Assistant unter /api/mcp. Das ist der Endpoint für beide Clients. Hast du mehrere LLM-APIs konfiguriert, erreichst du Assist gezielt unter /api/mcp/assist, aber im Normalfall reicht /api/mcp.

Schritt 3: Externe Erreichbarkeit klären (nur für ChatGPT im Browser)

Dieser Schritt ist nur nötig, wenn du HA über chatgpt.com steuern willst. Die Desktop-Apps verbinden sich direkt von deinem Rechner aus und brauchen nur eine lokale Adresse.

Am einfachsten geht das mit Home Assistant Cloud (Nabu Casa). Du bekommst eine feste URL wie https://abc123.ui.nabu.casa. Alternativ funktioniert auch ein eigener Reverse Proxy mit gültigem HTTPS-Zertifikat.

Schritt 4: Long-Lived Access Token erstellen

Der Token ist das Passwort für die lokalen Proxy-Wege. Für ChatGPT im Browser brauchst du ihn nicht, dort läuft alles über OAuth.

Klick unten links auf deinen Namen, öffne den Reiter „Sicherheit" und scroll ganz nach unten zu „Langlebige Zugriffs-Tokens". Dort auf „Token erstellen" klicken, einen Namen vergeben, zum Beispiel ChatGPT MCP, und den Token sofort kopieren. Home Assistant zeigt ihn nur ein einziges Mal.

Behandle den Token wie ein Passwort. Er authentifiziert sich gegenüber der gesamten HA-API mit den Rechten seines Benutzers, nicht nur gegenüber MCP. Am sichersten legst du einen eigenen HA-Nutzer ohne Admin-Rechte an und erzeugst den Token unter diesem Account.

Schritt 5 (Weg A): Claude Desktop über lokalen Proxy

Claude Desktop kann HTTP-MCP-Server über Custom Connectors ansprechen, allerdings läuft dieser Traffic über Anthropics Cloud und erreicht keine lokale IP. Für dein Heimnetz setzt du deshalb mcp-proxy davor, einen kleinen Übersetzer zwischen dem stdio-Kanal von Claude und dem HTTP-Endpoint von HA. Die HA-Verbindung läuft dann komplett lokal. Die KI-Verarbeitung selbst findet aber bei Anthropic in der Cloud statt.

5.1 uv installieren

uv ist ein schneller Python-Paketmanager, der mcp-proxy installiert. Falls du uv schon hast, überspring diesen Schritt.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

Nach der Installation das Terminal neu starten, damit uv im PATH liegt.

5.2 mcp-proxy installieren

uv tool install git+https://github.com/sparfenyuk/mcp-proxy

5.3 Claude-Konfiguration bearbeiten

Auf dem Mac liegt die Datei unter ~/Library/Application Support/Claude/claude_desktop_config.json, auf Windows unter %APPDATA%\Claude\claude_desktop_config.json. Diesen Block einfügen und IP, Port und Token anpassen:

1{
2  "mcpServers": {
3    "Home Assistant": {
4      "command": "mcp-proxy",
5      "args": [
6        "--transport=streamablehttp",
7        "--stateless",
8        "http://homeassistant.local:8123/api/mcp"
9      ],
10      "env": {
11        "API_ACCESS_TOKEN": "DEIN_LANGLEBIGER_TOKEN"
12      }
13    }
14  }
15}

5.4 Testen

Claude Desktop komplett neu starten. Danach taucht „Home Assistant" bei den verfügbaren Tools auf. Zum Test einfach tippen: „Schalte das Licht im Flur an."

Falls Claude beim Start „ENOENT" meldet, findet es mcp-proxy nicht im PATH. Dann bei "command" den vollen Pfad eintragen, zum Beispiel das Ergebnis von which mcp-proxy.

„Lokal" bezieht sich hier auf die Verbindung zwischen deinem Rechner und HA, die braucht kein Internet. Die KI-Verarbeitung selbst findet bei Anthropic statt, deine Befehle verlassen also trotzdem das Haus.

Schritt 6 (Weg B): ChatGPT Desktop oder Web

Es gibt zwei technisch verschiedene ChatGPT-Wege. Wichtig zu wissen: Im Feld „Bearer-Token-Umgebungsvariable" der App gehört nur der Name einer bereits existierenden Betriebssystem-Variable, nicht der Token selbst. Und ChatGPT im Web kann keine private URL wie http://10.x.x.x erreichen. Der robuste lokale Weg verwendet STDIO plus mcp-proxy, der Web-Weg verwendet HTTPS plus OAuth.

B1: ChatGPT Desktop lokal (STDIO)

Der Proxy läuft auf deinem Rechner und verbindet die Desktop-App mit der lokalen HA-Adresse. HA muss weder öffentlich erreichbar sein noch HTTPS verwenden. Diese MCP-Konfiguration wird von ChatGPT Desktop und Codex auf demselben Rechner gemeinsam genutzt.

Zuerst uv installieren, falls uv im Terminal nicht erkannt wird. Auf dem Mac curl -LsSf https://astral.sh/uv/install.sh | sh ausführen, auf Windows irm https://astral.sh/uv/install.ps1 | iex in PowerShell. Danach das Terminal neu starten. Erst dann uv tool install git+https://github.com/sparfenyuk/mcp-proxy ausführen. Mit which mcp-proxy den vollständigen Pfad ermitteln.

In der ChatGPT-App: Einstellungen → Plugins → Reiter „MCPs" → „Hinzufügen" → „MCP-Server hinzufügen". Als Typ STDIO auswählen.

Als Name home_assistant eintragen. Als Befehl den vollständigen Pfad zu mcp-proxy eintragen. Die Argumente als drei getrennte Einträge anlegen: --transport=streamablehttp, dann --stateless, dann http://homeassistant.local:8123/api/mcp. Die Adresse an deine Instanz anpassen.

Auf „+ Umgebungsvariable hinzufügen" klicken. Als Schlüssel API_ACCESS_TOKEN eintragen, als Wert den Long-Lived Token. Ohne diesen Eintrag kann sich die App nicht bei HA anmelden. Den Schlüssel muss exakt API_ACCESS_TOKEN heißen, sonst funktioniert das nicht.

Speichern klicken und ChatGPT komplett beenden und neu öffnen. Einen neuen Chat öffnen, mit /mcp den Verbindungsstatus prüfen. home_assistant soll als verbunden erscheinen. Dann fragen: „Welche Lampen sind gerade an?"

Diese Konfiguration wurde mit Home Assistant MCP Server 1.29.1 erfolgreich getestet. Der Server liefert dabei 27 Werkzeuge für Zustände, Licht, Klima, Medien, Listen und Staubsauger.

B2: ChatGPT im Browser (Remote-MCP)

Für chatgpt.com. Die Verbindung läuft aus der OpenAI-Cloud zu Home Assistant. Deshalb muss die HA-Adresse öffentlich per HTTPS erreichbar sein und OAuth zulassen. Private IPs oder homeassistant.local funktionieren hier nicht. Für Schreibaktionen wie Licht schalten brauchst du außerdem einen Business-, Enterprise- oder Edu-Plan.

Externe HA-Adresse prüfen, zum Beispiel https://deine-instanz.ui.nabu.casa. Die Adresse muss außerhalb deines WLANs erreichbar sein und ohne Zertifikatswarnung öffnen.

Auf chatgpt.com einloggen: Einstellungen → Apps → Erweiterte Einstellungen → Developer Mode einschalten. Fehlt die Option, unterstützt der Plan oder die Workspace-Richtlinie diesen Weg nicht.

Unter Apps auf „Erstellen" klicken. Name: Home Assistant. MCP-Server-URL: https://DEINE-EXTERNE-HA-URL/api/mcp. Authentifizierung: OAuth. Zuerst die automatische Erkennung versuchen.

Falls die Auto-Discovery scheitert, manuell eintragen: Client ID https://chatgpt.com, Auth URL https://DEINE-URL/auth/authorize, Token URL https://DEINE-URL/auth/token.

ChatGPT leitet dann auf die HA-Anmeldung weiter. Dort einloggen und den Zugriff bestätigen. Neuen Chat öffnen, im Apps-Menü „Home Assistant" auswählen und testen: „Welche Lampen sind gerade an?"

B1 ist die beste Wahl im Heimnetz: keine öffentliche HA-Adresse nötig, reproduzierbar getestet. B2 ist der richtige Weg, wenn du ausdrücklich auf chatgpt.com oder von unterwegs arbeiten willst und bereits eine sichere externe HA-URL hast.

Bei beiden Optionen verarbeitet OpenAI deine Anfrage. Bei B1 bleibt nur die MCP-Verbindung zwischen Rechner und HA lokal. Bei B2 erreicht die OpenAI-Cloud deine externe HA-URL direkt.

Vergleich: Claude vs. ChatGPT

Wenn HA nur im Heimnetz erreichbar ist, sind ChatGPT Desktop und Claude Desktop die passenden Wege. Beide verwenden denselben lokalen Proxy. ChatGPT bietet dafür eine Einstellungsoberfläche, Claude eine JSON-Konfiguration. Claude Desktop ist ohne Bezahl-Abo nutzbar und hat keine Einschränkung bei Schreibaktionen.

Was geht, was nicht

Der MCP-Server über Assist kann Lichter, Schalter, Szenen, Klima und Cover schalten und Sensorwerte auslesen, auch mehrere Schritte in einem Satz. Was er nicht kann: Automationen oder YAML anlegen, Dinge sehen die nicht für Assist freigegeben sind, oder Benachrichtigungen aus dem MCP-Server heraus verschicken.

Sobald ChatGPT oder Claude im Spiel ist, verlässt deine Anfrage das Haus und landet bei OpenAI oder Anthropic. Das gilt auch für den Claude-Weg: die HA-Verbindung ist lokal, aber die KI-Verarbeitung passiert in der Cloud. Wer das nicht will, bleibt bei der lokalen Assist-Sprachsteuerung.

Troubleshooting

KI sieht keine Geräte. Nichts für Assist freigegeben. Zurück zu Schritt 1.

ChatGPT Web erreicht HA nicht. Private HTTP-Adresse, ungültiges Zertifikat oder HA nicht von außen erreichbar. Eine öffentliche HTTPS-Adresse verwenden, bevorzugt Nabu Casa.

Desktop-MCP bei /mcp nicht sichtbar. App nach dem Speichern nicht neu gestartet oder der Proxy konnte nicht starten. ChatGPT vollständig neu starten. Den Pfad zu mcp-proxy, die drei Argumente und den API_ACCESS_TOKEN-Eintrag prüfen.

MCP-Server verbunden, aber keine Aktion. Alter Chat oder unklare Formulierung. Neuen Chat öffnen, mit /mcp den Status prüfen und dann ausdrücklich schreiben: „Nutze Home Assistant und sage mir, welche Lampen an sind."

command not found: uv. uv ist noch nicht installiert. Auf dem Mac curl -LsSf https://astral.sh/uv/install.sh | sh ausführen, danach das Terminal neu starten. Auf Windows irm https://astral.sh/uv/install.ps1 | iex in PowerShell.

STDIO: „ENOENT" oder „Befehl nicht gefunden". mcp-proxy ist nicht im PATH. Betrifft Claude und ChatGPT. Den vollen Pfad eintragen, zum Beispiel das Ergebnis von which mcp-proxy.

mcp-proxy startet nicht, Fehler „request_ctx". Veraltete oder inkonsistente Installation. Mit uv tool install --force git+https://github.com/sparfenyuk/mcp-proxy neu installieren und die App neu starten.

SSL-Zertifikatsfehler. Selbstsigniertes Zertifikat beim Reverse Proxy. Ein gültiges Zertifikat verwenden, zum Beispiel Let's Encrypt oder Nabu Casa.

401 / nicht autorisiert (Desktop). Token falsch, widerrufen oder falscher Variablenname. Neuen Token erstellen. Beim STDIO-Proxy muss der Schlüssel exakt API_ACCESS_TOKEN heißen.

OAuth schlägt wiederholt fehl (Web). Externe URL oder OAuth-Felder falsch. URL und manuelle OAuth-Werte exakt prüfen. Falls IP-Bans aktiv sind, ip_bans.yaml in HA kontrollieren.

„Create" oder Developer Mode fehlt. Plan, Workspace-Richtlinie oder App-Version unterstützt die Funktion nicht. ChatGPT aktualisieren oder den Workspace-Admin fragen.

Endpoint testen. Ein einfacher GET reicht bei MCP nicht. Eine POST-Initialize-Anfrage mit Authorization-Header an /api/mcp senden. HTTP 200 mit serverInfo.name: home-assistant heißt der Server läuft. 401 bedeutet Token-Problem, 404 bedeutet die MCP-Server-Integration fehlt in HA.

1read -s "HA_TOKEN?Home-Assistant-Token: "; echo
2curl -i -X POST \
3  -H "Authorization: Bearer $HA_TOKEN" \
4  -H "Content-Type: application/json" \
5  -H "Accept: application/json, text/event-stream" \
6  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"ha-test","version":"1.0"}}}' \
7  http://homeassistant.local:8123/api/mcp
8unset HA_TOKEN

Abgeglichen mit der offiziellen Home-Assistant-Dokumentation und der offiziellen OpenAI-Dokumentation zu MCP. Stand: 31. August 2026.

Nutzt du ChatGPT oder eher Claude für dein Smart Home? Und welchen Weg hast du gewählt, Desktop oder Browser? Ich bin gespannt, was bei euch funktioniert.