Home Assistant mit KI verbinden – MCP-Server für Claude, ChatGPT & Gemini einrichten
Home Assistant kann fast alles – aber genau deshalb tun sich viele Einsteiger schwer, eigene Automationen zu bauen, Dashboards zu gestalten oder Fehler zu debuggen: YAML lernen, Templates verstehen, Foren durchsuchen. Mit einem Home Assistant MCP Server gebt ihr genau diese Arbeit an eine KI ab.
Über einen MCP-Server (Model Context Protocol, eine offene Schnittstelle zwischen KIs und anderen Programmen) verbindet ihr Home Assistant direkt mit einer KI eurer Wahl – Claude, ChatGPT oder Gemini – und sagt in normaler Sprache, was ihr braucht, etwa „Baue mir eine Dashboard-Karte, die zeigt, welche Fenster offen sind“. Die KI findet die passenden Entitäten selbst, schreibt den Code und legt ihn in Home Assistant an.
Kurz gesagt
Für Automationen, Dashboards und Sensoren installiert ihr das kostenlose Community-Projekt ha-mcp in Home Assistant, macht es über Nabu Casa, einen Reverse Proxy oder einen Cloudflare Tunnel erreichbar und tragt es als Connector in eure KI ein. Zum Steuern und Auslesen reicht der offizielle MCP-Server von Home Assistant.
- Ihr braucht: Home Assistant ab 2026.8, besser die aktuelle Version, auf einem Raspberry Pi mit beliebiger Installationsart (OS, Supervised, Container oder Core) und einen KI-Account. Claude ist der einfachste Einstieg, ChatGPT baut Automationen erst ab dem Tarif Business, Gemini läuft außerhalb der USA über die kostenlose Antigravity CLI.
- Installation: ha-mcp als Custom Component über den Marketplace, der ab Home Assistant 2026.11 eingebaut ist. Bis 2026.10 nehmt ihr HACS.
- Offizieller Server: seit 2026.10 per Klick unter Einstellungen → System → KI, seit 2026.11 liest er auch Verlauf und Logs. Automationen und Dashboards baut er nicht.
- Vorab wichtig: Cloud-KI-Connectoren können kein von euch ausgestelltes Client-Zertifikat präsentieren – läuft Home Assistant hinter Cloudflare Access mit mTLS, braucht der MCP-Zugriff eine Ausnahme.
- Ein Konto nur für HA-MCP anlegen (Administrator, nur lokaler Zugriff)
- Unter Einstellungen → Marketplace „HA-MCP“ suchen und installieren (bis Version 2026.10 über HACS)
- Unter Einstellungen → Geräte & Dienste die Integration hinzufügen, den Eintrag „HA-MCP Server“ wählen und den Fernzugriff einschalten, z.B. „Geheime URL“
- Unter Konfigurieren die Webhook-URL kopieren (mit Nabu Casa oder eingetragener externer URL steht sie dort schon mit eurer externen Adresse) und auf claude.ai als Custom Connector eintragen
- Der KI eine erste Aufgabe geben, etwa „Welche Lichter sind gerade an?“
Mit Home Assistant OS oder Supervised geht es alternativ als App/Add-on, siehe „Schritt 1: ha-mcp installieren“.
Voraussetzungen
- Home Assistant ab Version 2026.8 auf einem Raspberry Pi. Das ist die technische Untergrenze, offiziell unterstützt das Projekt nur die aktuelle stabile Version. Für den empfohlenen Weg spielt die Installationsart keine Rolle: OS, Supervised, Container und Core funktionieren. Noch keine Hardware? Home Assistant läuft auf einem Raspberry Pi 5*, fertig vorinstalliert gibt es den Home Assistant Green*. Was zu euch passt, zeigt mein Home-Assistant-Hardware-Vergleich.
- Den Marketplace, darüber installiert ihr die Custom Component. Ab Home Assistant 2026.11 ist er unter Einstellungen eingebaut. Was für ältere Versionen gilt, steht in unserer HACS-Anleitung.
- Nur für den Weg als App/Add-on: Home Assistant OS oder Supervised mit dem App-Store unter Einstellungen → Apps (vor Home Assistant 2026.2: Einstellungen → Add-ons → Add-on-Store)
- Für den Zugriff durch Cloud-KIs (Claude, ChatGPT): ein Zugang von außen – Nabu Casa, ein bestehender Reverse Proxy oder ein eigener Cloudflare Tunnel
- Ein Account bei Claude, ChatGPT oder Google Gemini. Was ihr mit welcher KI und welchem Tarif bekommt, zeigt die Tabelle in Schritt 3.
Habt ihr noch keinen Fernzugriff, richtet ihn mit meiner Anleitung Cloudflare Tunnel auf dem Raspberry Pi einrichten ein – ohne Portfreigabe und mit mTLS-Absicherung.
Offizieller vs. inoffizieller MCP-Server
Home Assistant bringt seit Version 2025.2 einen eigenen, offiziellen MCP-Server mit. Die Community-Lösung ha-mcp kann deutlich mehr:
| Funktion | Offizieller MCP-Server | Inoffiziell (ha-mcp) |
|---|---|---|
| Entitäten-Zugriff | Je nach Einstellung nur für den Sprachassistenten Assist freigegebene oder alle Entitäten | Alle Entitäten im System |
| Geräte steuern, Aktionen ausführen | Ja | Ja |
| Verlauf und Logs lesen | Ja, seit 2026.11 | Ja |
| Automationen/Scripts erstellen/bearbeiten | Nein | Ja |
| Szenen erstellen/bearbeiten | Nur per Aktion scene.create | Ja |
| Dashboards bauen/bearbeiten | Nein | Ja |
| Automationen aus Traces debuggen | Nein | Ja |
| Helper, Areale, Zonen, Labels, Gruppen verwalten | Nein | Ja |
| Backups, Apps/Add-ons, HACS, Geräte-/Entity-Registry | Teilweise, etwa Backup anlegen oder App neu starten | Ja |
| Installationsarten | Alle | Alle als Custom Component, als App nur OS/Supervised |
| Setup-Aufwand | Gering | Mittel |
Soll eure KI nur steuern und Fragen beantworten („Licht im Wohnzimmer an“, „Was stand gestern im Log?“), reicht der offizielle Server. Für Automationen, Dashboards und Sensoren braucht ihr ha-mcp.
Offiziellen MCP-Server einrichten
Ab Home Assistant 2026.10 schaltet ihr den offiziellen Server so ein:
- Geht zu Einstellungen → System → KI.
- Klickt in der Karte „Model Context Protocol“ auf Aktivieren.
- Kopiert unter „Haupt-URL“ die Adresse mit URL kopieren. Sie endet auf
/api/mcp.
Claude, ChatGPT und andere Cloud-KIs greifen über das Internet zu. Home Assistant muss deshalb von außen erreichbar sein, etwa über Nabu Casa oder euren Tunnel.
Eine neue Einrichtung macht alle KI-Tools verfügbar und lässt nur Administratorkonten zu. Die KI meldet sich per OAuth mit eurem Home-Assistant-Konto an: Ihr bestätigt den Zugriff im Browser, euer Passwort bekommt die KI nicht.
Seit Home Assistant 2026.11 besteht der Server aus zwei Tool-Sets. Gerätesteuerung sieht und steuert nur, was ihr für Assist freigegeben habt. Home Assistant sieht alle Entitäten samt Verlauf und Logs und kann jede Aktion aufrufen, auf Home Assistant OS also auch den Host herunterfahren. Dieses Tool-Set setzt immer ein Administratorkonto voraus.
Was die KI darf, legt ihr unter Einstellungen → Geräte & Dienste → Model Context Protocol → Konfigurieren fest. Dort beschränkt Nur-Lese-Zugriff die KI auf Tools, die nichts ändern. Schaltet ihr Alle KI-Tools verfügbar machen aus, wählt ihr im selben Dialog nur Gerätesteuerung. Beides gilt für die Haupt-URL. Die einzelnen URLs, die auf der KI-Seite unter „Individuelle URLs“ stehen, ignorieren diese Einstellungen.
Offiziellen Server mit Claude verbinden
Legt auf claude.ai unter Customize → Connectors einen Custom Connector an und tragt die kopierte Adresse ein. Claude zeigt danach einen Dialog: Wählt bei der Anmeldung Sign in now und beim OAuth-Client Use Claude’s published identity. Klickt danach auf der Seite des Connectors auf Connect und meldet euch bei Home Assistant an. Zum Test fragt ihr Claude: „Welche Lichter sind gerade an?“ Die Schritte für ChatGPT und andere KIs stehen in der offiziellen Dokumentation.
Nur wenn Home Assistant bei euch hinter Cloudflare Access mit Client-Zertifikat läuft: Dann blockiert Cloudflare den Connector, denn die Ausnahme in Schritt 2 weiter unten gilt nur für den Webhook von ha-mcp, nicht für /api/mcp.
Welcher Weg passt zu euch?
ha-mcp gibt es als Custom Component, die direkt in Home Assistant läuft, und als App/Add-on mit denselben Werkzeugen. Welchen Weg ihr nehmt, hängt von eurer Installation ab:
| Ihr habt … | Nehmt … | Warum |
|---|---|---|
| Home Assistant OS oder Supervised | Custom Component (empfohlen) oder App/Add-on | Die Custom Component bringt den Fernzugriff gleich mit, die App kommt ohne HACS aus |
| Home Assistant Container oder Core (z.B. Docker auf dem Pi) | Custom Component | Apps gibt es dort nicht |
Wichtig: Betreibt nur einen der beiden Wege als Server, die Custom Component ersetzt die App vollständig. Einzige Ausnahme ist der optionale Eintrag für die YAML-Tools weiter unten, der ist kein zweiter Server.
Schritt 1: ha-mcp installieren
Das Projekt heißt „Home Assistant MCP Server“ (Repository homeassistant-ai/ha-mcp).
Custom Component (empfohlen, alle Installationsarten)
Die Custom Component läuft als Integration direkt in Home Assistant. Stand der Anleitung: Home Assistant 2026.11, November 2026. Legt zuerst ein eigenes Konto für HA-MCP an:
- Geht zu Einstellungen → Personen → Person hinzufügen und gebt einen Namen ein, z.B. „hamcp“
- Anmeldung erlauben einschalten, Benutzername und Passwort vergeben
- Nur lokaler Zugriff und Administrator einschalten. Ohne Administrator-Rechte klappt die Einrichtung nicht.
Warum ein eigenes Konto? HA-MCP erzeugt daraus ein Zugriffstoken namens „HA-MCP Server“, das nur in eurem Heimnetz gilt, und speichert das Passwort nicht. Home Assistant führt die Änderungen der KI dann unter diesem Konto. Alternativ geht ein langlebiges Zugriffstoken eures eigenen Kontos (Profil → Sicherheit). Das funktioniert aber auch von außerhalb, falls es mal in falsche Hände gerät.
Die Custom Component installiert ihr über den Marketplace, ein GitHub-Konto braucht ihr dafür nicht:
- Einstellungen → Marketplace öffnen und unter Durchstöbern nach „HA-MCP“ suchen. Beim ersten Öffnen zeigt der Marketplace einen Hinweis zu den Risiken, den ihr bestätigen müsst, bevor ihr etwas installieren könnt. Bis Home Assistant 2026.10 tragt ihr stattdessen in HACS über die drei Punkte oben rechts unter Benutzerdefinierte Repositories die URL
https://github.com/homeassistant-ai/ha-mcpmit dem Typ Integration ein.
- HA-MCP — Manage Home Assistant with AI (in älteren Versionen HA-MCP Custom Component) mit der Beschreibung „Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants“ öffnen. Die Suche zeigt auch „Ha Mcp For Xiaozhi“ – das ist ein anderes Projekt.
- Auf Installieren klicken und im Dialog noch einmal Installieren (in HACS: zweimal Herunterladen)
Der Marketplace bietet die aktuelle stabile Version an. Habt ihr ha-mcp früher über HACS mit dem Repository ha-mcp-integration installiert, müsst ihr nichts umstellen: Es bekommt laut Projekt weiter dieselben Releases. Lasst dafür im Marketplace die GitHub-Verbindung bestehen, sonst prüft er dieses Repository nicht mehr auf Updates.
- Zeigt Einstellungen oben eine Reparatur, die für HA-MCP einen Neustart verlangt, öffnet sie und bestätigt mit Neu starten. Öffnet sich stattdessen direkt die Einrichtung, überspringt ihr den nächsten Punkt und tragt gleich das Konto ein.
- Einstellungen → Geräte & Dienste → Integration hinzufügen, nach „HA-MCP“ suchen, HA-MCP — Manage Home Assistant with AI (ältere Versionen: HA-MCP Custom Component) wählen und dann HA-MCP Server (empfohlen)
- Im Dialog Benutzername und Passwort des neuen Kontos eintragen – nie euren eigenen Login. Wollt ihr euer eigenes Konto nutzen, fügt ihr oben stattdessen ein Zugriffstoken ein.
- Darunter legt ihr fest, wie eure KI den Server erreicht. Fernzugriff über Home Assistant und Netzwerkzugriff stehen anfangs auf „aus“. Zum schnellen Einstieg wählt ihr „Geheime URL (keine Anmeldung)“: Claude, ChatGPT und die Antigravity CLI verbinden sich dann allein mit der URL. Bleibt der Server dauerhaft aus dem Internet erreichbar, nehmt ihr „Home Assistant Anmeldung“, das empfiehlt das Projekt. Die KI meldet sich dann mit einem Administratorkonto von Home Assistant an, wie das geht, steht in Schritt 3. Für den Zugriff im Heimnetz wählt ihr zusätzlich „Local network“. Alle Optionen erkläre ich in Schritt 2.
- Mit OK bestätigen und den Dialog „Benennen und zuordnen“ mit Überspringen und fertigstellen schließen
- Auf der Seite der Integration am Eintrag „HA-MCP Server“ auf das Zahnrad (Konfigurieren) klicken. Unter „Verbindungs-URL(s)“ stehen eure Adressen.
Ihr bekommt zwei Adressen, beide mit einem zufälligen, geheimen Teil:
Webhook: http://<ha-ip>:8123/api/webhook/mcp_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
Direkt: http://<ha-ip>:9584/private_Xy7Kq2LmN9pRtW4vZs8b
Die direkte Adresse nutzt ihr nur im Heimnetz, die Webhook-Adresse ist die Grundlage für den Fernzugriff in Schritt 2. Behandelt beide wie ein Passwort: Wer sie kennt, kann alle Werkzeuge nutzen.
Die Einstellungen von ha-mcp findet ihr im neuen Seitenleisten-Eintrag HA-MCP. Dort schaltet ihr einzelne Werkzeuge ab, aktiviert den Nur-Lese-Modus oder ändert die Servereinstellungen. Es sind dieselben Schalter wie in der App.
App/Add-on (nur Home Assistant OS und Supervised)
- Geht zu Einstellungen → Apps → App-Store (bzw. Add-ons → Add-on-Store auf älteren HA-Versionen)
- Über die drei Punkte oben rechts → Repositorys die URL
https://github.com/homeassistant-ai/ha-mcphinzufügen - Seite neu laden, „Home Assistant MCP Server“ installieren und starten
Öffnet danach den Logs-Tab der App. Dort steht eure fertige, bereits mit einem 128-Bit-Zufallspfad abgesicherte MCP-Server-URL, zum Beispiel:
🔐 MCP Server URL: http://<ha-ip>:9583/private_zctpwlX7ZkIAr7oqdfLPxw
Diese lokale URL nutzt ihr im Heimnetz, etwa für Claude Desktop und Claude Code (Schritt 3), für Cloud-KIs kommt in Schritt 2 die Remote-URL dazu. Ein eigenes Token oder Passwort müsst ihr nicht anlegen – die App authentifiziert sich automatisch über den Home-Assistant-Supervisor, der Zufallspfad in der URL ist die eigentliche Absicherung.
Empfohlene Einstellungen (beide Wege)
Diese Einstellungen empfehle ich für beide Wege. Bei der Custom Component findet ihr sie im Panel „HA-MCP“ (dort auf Deutsch, z.B. „Nur-Lese-Modus“), bei der App im Konfigurations-Tab bzw. in der Tool-Settings-Weboberfläche über „Open Web UI“:
- Tool Search (
enable_tool_search): Standardmäßig deaktiviert – so lassen. Bei Clients mit eigener Tool-Suche, also claude.ai, Claude Desktop und Claude Code, unbedingt deaktiviert lassen, weil beide Suchen sonst kollidieren. Aktivieren lohnt sich für Clients ohne eigene Tool-Suche oder mit Modellen ohne sie (etwa Claude Haiku, Gemini oder lokale Modelle) und wenn euer Client die Toolanzahl begrenzt (z.B. auf 100). - Tool Security Policies (
enable_tool_security_policies): Optional aktivieren, wenn ihr bei kritischen Aktionen (Schlösser, Alarmanlage, Automationen schreiben) eine manuelle Freigabe in der Einstellungsoberfläche wollt. - Read Only Mode (
read_only_mode): Praktisch für den ersten Test oder gemeinsam genutzte Installationen – schaltet alle schreibenden Tools komplett ab. - Automatische Backups (
enable_auto_backup): Standardmäßig an – so lassen. ha-mcp speichert dann vor jeder Änderung eine Kopie von Automation, Skript, Dashboard oder Helfer, die ihr bei Bedarf wiederherstellt. - Einzelne Tools könnt ihr in der Einstellungsoberfläche gezielt deaktivieren oder anpinnen, falls ihr sie nicht braucht oder für zu gefährlich haltet.
Zusammen mit dem offiziellen MCP-Server: ha-mcp hängt seine Werkzeuge als weitere LLM-API in Home Assistant ein. Die Custom Component macht das von selbst und steht dann unter Einstellungen → System → KI bei „Individuelle URLs“ als „HA-MCP Server (tool search)“. Die App meldet sich als gefundener MCP-Server, den ihr erst bestätigt. Ist der offizielle Server aktiv, reicht er diese Werkzeuge mit der Standardeinstellung ebenfalls an die KI weiter. Wollt ihr das nicht, öffnet ihr die Integration „Model Context Protocol“, klickt auf Konfigurieren, schaltet „Alle KI-Tools verfügbar machen“ aus und wählt nur die Tool-Sets, die ihr wollt.
Im Heimnetz erreicht ihr ha-mcp jetzt schon über die lokale URL (App: Port 9583, Custom Component: Port 9584), z.B. mit VS Code, Cursor oder anderen HTTP-fähigen MCP-Clients.
Schritt 2: Fernzugriff einrichten
Damit Cloud-KIs wie Claude oder ChatGPT euren MCP-Server erreichen können, braucht ihr eine öffentlich erreichbare, HTTPS-gesicherte URL. Mit der Custom Component ist das fast erledigt, für die App gibt es zwei Optionen.
Custom Component: Der Webhook ist eingebaut
Die Custom Component registriert selbst einen Webhook in Home Assistant. Der läuft über den Zugang, den ihr ohnehin habt – Nabu Casa, Cloudflare Tunnel oder euren Reverse Proxy. Einen Webhook-Proxy oder einen zweiten Hostnamen braucht ihr nicht. Was erlaubt ist, legt ihr bei der Einrichtung unter Fernzugriff über Home Assistant fest:
- Deaktiviert (Standard): kein Zugriff über den Webhook. Das Panel und die Sprachassistenten von Home Assistant funktionieren trotzdem.
- Geheime URL (keine Anmeldung): Die Webhook-Adresse ist das einzige Geheimnis, wie bei der App.
- Home Assistant Anmeldung: Claude und ChatGPT finden die Anmeldung selbst und melden sich mit einem Home-Assistant-Administratorkonto an, die URL allein reicht dann nicht mehr. Für dauerhaften Zugriff aus dem Internet empfiehlt das Projekt diese Variante. Die geheime URL solltet ihr wie ein Passwort streng geheim halten.
- Legacy OAuth (Client-ID und Secret): für Clients, die eine Client-ID und ein Secret zum Einfügen verlangen
Netzwerkzugriff regelt dagegen den direkten Port 9584: „This machine only (loopback)“ sperrt ihn, „Local network“ öffnet ihn für Geräte in eurem Heimnetz. Später ändert ihr beides unter Konfigurieren. Dort ist „Fernzugriff über Home Assistant“ auf zwei Felder verteilt: „Remote-Zugriff über Webhook“ schaltet ihn an oder aus, „Authentifizierungsmodus“ wählt zwischen „Geheime Webhook-URL“, „Mit Home Assistant anmelden (OAuth)“ und „Legacy OAuth“. „Netzwerkzugriff“ heißt dort genauso. Eure externe Adresse ermittelt die Component laut Doku selbst. Nutzt ihr eine eigene Domain ohne Nabu Casa, tragt ihr sie dort unter Externe URL (optional) ein, ohne Port wie :8123.
Eure Remote-URL für Claude, ChatGPT und Co. ist die Webhook-Adresse aus Schritt 1 mit eurer externen Adresse vorne. Ist Nabu Casa aktiv oder eine externe URL eingetragen, zeigt Konfigurieren sie laut Doku als erste Verbindungs-URL an:
https://<eure-externe-adresse>/api/webhook/mcp_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
App, Option A: Webhook-Proxy-App (wenn ihr schon Nabu Casa oder einen Reverse Proxy nutzt)
Die „Webhook Proxy for HA MCP“-App (gleiches Repository) leitet den MCP-Traffic über euren bereits bestehenden Home-Assistant-Zugang – Nabu Casa, Cloudflare Tunnel, DuckDNS oder jeden anderen Reverse Proxy, der schon auf eure Home-Assistant-Instanz zeigt. Ihr braucht dafür keinen zusätzlichen Hostnamen und keinen zweiten Tunnel:
- Die MCP-Server-App aus Schritt 1 muss bereits laufen
- „Webhook Proxy for HA MCP“ (im App-Store mit „Nabu Casa“ im Namen) aus demselben App-Store installieren und starten
- Falls ihr kein Nabu Casa benutzt (z.B. bei einem eigenen Cloudflare Tunnel), muss eure öffentliche Home-Assistant-URL explizit in den Einstellungen der Webhook-Proxy-App eingetragen werden – mit Nabu Casa erkennt die App das automatisch

- Home Assistant neu starten (in den Einstellungen rechts oben einen kompletten Neustart durchführen)
- Im Logs-Tab der Webhook-Proxy-App die fertige Remote-URL kopieren, z.B.:
MCP Server URL (remote): https://<your-external-url>/api/webhook/mcp_7eacf143b0f5d31269417ae3304ee534
Die App findet eure MCP-Server-App automatisch. Der Webhook-Pfad (/api/webhook/mcp_...) bleibt auch über Neustarts hinweg stabil, weil die ID lokal gespeichert wird.
App, Option B: Eigener Cloudflared-Tunnel (wenn ihr noch keinen Fernzugriff habt)
Alternativ nutzt ihr einen dedizierten Tunnel nur für den MCP-Server, wie im Cloudflare-Tunnel-Artikel (Teil A) beschrieben. Mit der Custom Component braucht ihr das nicht: Dort reicht ein Tunnel zu Home Assistant selbst, der Webhook läuft darüber. Für die App kommt in die Cloudflared-App-Konfiguration:
additional_hosts:
- hostname: ha-mcp.euredomain.de
service: http://localhost:9583
Falls localhost aus dem Cloudflared-Container heraus nicht funktioniert (eigener Docker-Container), nehmt stattdessen den Container-Hostnamen der MCP-Server-App, den ihr auf deren Info-Seite findet (z.B. b37de126-ha-mcp). Startet danach die Cloudflared-App neu. Eure Remote-URL für Schritt 3 besteht aus dem neuen Hostnamen und dem Zufallspfad eurer lokalen URL.
Cloudflare-Fallen (für Custom Component und App)
⚠️ Wichtige Cloudflare-Falle: Cloudflare kann KI-Zugriffe sperren, auch wenn der Browser-Zugriff auf dieselbe URL problemlos funktioniert. Öffnet Security → Settings, filtert nach Bot traffic und wählt AI Crawler and Agent access policies. Dort darf Agents nicht auf Block stehen: Darunter fasst Cloudflare Zugriffe zusammen, die in Echtzeit im Auftrag einer Person laufen, so wie die Anfragen eurer KI an den MCP-Server. Neue Domains stehen ab Werk auf „Allow (do not block)“.
Länder-Sperre aktiv? Habt ihr in Cloudflare Länder blockiert, etwa mit der Beschränkung auf DE/AT/CH aus dem Cloudflare-Tunnel-Artikel, kann die Regel auch Claude und ChatGPT aussperren: Die Anfragen der KI kommen von Servern der Anbieter, nicht aus eurem Heimnetz, und deren IP-Adressen liegen nicht zwingend in den Ländern, die ihr freigegeben habt. Setzt deshalb an Position 1 eurer eigenen WAF-Regeln eine Skip-Regel für Anthropics ausgehende IP-Bereiche, die alle weiteren eigenen Regeln überspringt:
(ip.src in {160.79.104.0/21 153.61.208.0/20}) and http.host eq "homeassistant.eure-domain.com"

Nutzt ihr für die App einen eigenen MCP-Hostnamen (Option B), könnt ihr die Länder-Regel stattdessen auf euren Haupt-Hostnamen beschränken. Bei der Custom Component und bei Option A läuft alles über denselben Hostnamen, dort hilft nur die Skip-Regel. OpenAI veröffentlicht für ChatGPT zwar eine IP-Liste, die Bereiche ändern sich aber laufend. Soll ChatGPT durchkommen, ohne dass ihr die Liste ständig nachpflegt, nehmt den Pfad /api/webhook/ von der Länder-Regel aus. Der Schutz liegt dann allein im Zufallspfad der URL.
Client-Zertifikat (mTLS)? Schützt ihr Home Assistant mit Cloudflare Access und Client-Zertifikat, kommt keine Cloud-KI durch – warum, steht unten im Abschnitt „Sicherheit“. Läuft der Zugriff über den Webhook (Custom Component oder Option A), nehmt ihr nur diesen Pfad von der mTLS-Pflicht aus. Habt ihr die WAF-Regel aus dem Cloudflare-Tunnel-Artikel übernommen, ergänzt sie um diese Ausnahme:
(http.host eq "homeassistant.eure-domain.com" and not cf.tls_client_auth.cert_verified and not starts_with(http.request.uri.path, "/api/webhook/"))
Der Pfad /api/webhook/ bleibt trotzdem geschützt, weil der Webhook eine eigene, zufällige ID im Pfad trägt – diese ID ist die Authentifizierung für diesen einen Endpunkt. Mit eigenem MCP-Hostnamen (Option B) nehmt ihr stattdessen diesen Hostnamen von der mTLS-Pflicht aus.
Schritt 3: MCP-Server an eure KI anbinden
Wie einfach die Verbindung ist und wie weit ihr damit kommt, unterscheidet sich deutlich zwischen Claude, ChatGPT und Gemini:
| KI | Mindest-Tarif | Automationen bauen? | Setup-Ort | Desktop/Mobile |
|---|---|---|---|---|
| Claude | Free (1 Connector), sonst Pro/Max | Ja | claude.ai (Web), Custom Connector | Synct automatisch auf Desktop-App und iOS/Android |
| ChatGPT | Business/Enterprise, Pro nur lesend (Stand 10/2026) | Nur mit Business/Enterprise | chatgpt.com → Plugins → Add custom MCP server | Laut OpenAI-Hilfe nur auf ChatGPT im Web verfügbar |
| Gemini | Kostenlos (Antigravity CLI) | Ja, über die CLI | Antigravity CLI, agy mcp add | Web-App mit „Custom apps“ nur in den USA |
Eine eigene Anleitung für die KI müsst ihr nicht hinterlegen: ha-mcp bringt mit dem Werkzeug ha_get_skill_guide Best Practices mit, die die KI bei Bedarf selbst abruft, etwa wie sie Helfer, Utility-Meter oder Template-Sensoren richtig anlegt. Ob die Verbindung steht, prüft ihr nach dem Einrichten mit einer Leseaufgabe wie „Welche Lichter sind gerade an?“: Die KI ruft dafür Werkzeuge von ha-mcp auf und listet eure Lichter.
Claude anbinden (Web, Desktop, Smartphone)
Variante A – Web Connector (empfohlen): Einmal auf claude.ai eingerichtet, steht der Connector automatisch auch in der Claude Desktop App und den Claude-Apps für iOS und Android.
- Auf claude.ai einloggen, zu Anpassen → Konnektoren gehen (Customize – Claude)
- Mit dem Plus-Symbol (+) einen benutzerdefinierten Konnektor hinzufügen, z.B. „Home Assistant“ nennen

- Eure Remote-URL aus Schritt 2 eintragen und speichern. Habt ihr „Home Assistant Anmeldung“ eingestellt, erkennt Claude die Anmeldung selbst: Klickt auf der Seite des Connectors auf Connect und meldet euch mit einem Administratorkonto von Home Assistant an.
- Bei den schreibgeschützten Tools könnt ihr „immer erlauben“ einstellen, bei schreibenden/löschenden Tools würde ich Rückfragen aktiv lassen
Steht die Verbindung, erreicht ihr Home Assistant über Claude von überall:
Variante B – Nur Claude Desktop, rein lokal (kein Fernzugriff nötig, dafür nur auf diesem Rechner und ohne Sync aufs Smartphone): Claude Desktop startet lokale MCP-Server als eigenes Programm und spricht mit ihnen über stdio, also über Ein- und Ausgabe des Programms, nicht per URL. Die Brücke zur URL von ha-mcp baut das kleine Hilfsprogramm mcp-remote, das Claude Desktop über npx selbst startet. Dafür braucht ihr nur Node.js ab Version 20.18.1. Das geht unter Windows und macOS:
- Claude Desktop komplett beenden, unter Windows auch das Symbol im Infobereich rechts unten
- Node.js auf diesem Rechner installieren, unter Windows im Terminal per winget, unter macOS mit Homebrew:
# Windows
winget install --id=OpenJS.NodeJS.LTS -e
# macOS
brew install node
- Die Datei
claude_desktop_config.jsonöffnen: unter Windows in%APPDATA%\Claude, unter macOS in~/Library/Application Support/Claude. Liegt sie unter Windows nicht dort, etwa bei der Version aus dem Microsoft Store, zeigt die Windows-Anleitung von ha-mcp den Pfad.
- Folgenden Eintrag ergänzen. Steht schon etwas in der Datei, kommt der Block
home-assistantin das vorhandenemcpServers– bei Unsicherheit hilft euer KI-Assistent. Als Ziel tragt ihr die lokale URL aus Schritt 1 ein (App: Port 9583, Custom Component: die direkte Adresse mit Port 9584):
{
"mcpServers": {
"home-assistant": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://homeassistant.local:9583/private_Odhrwersdgh234", "--allow-http"]
}
}
}
- Claude Desktop wieder starten. Habt ihr Variante B früher mit dem Hilfsprogramm
mcp-proxyeingerichtet, ersetzt ihr den ganzen Eintrag durch diesen, das Projekt empfiehltmcp-proxynicht mehr.
Claude Code an Home Assistant anbinden
Für Claude Code reicht ein Befehl im Terminal, nicht in der laufenden Claude-Code-Sitzung. Fügt die lokale URL aus Schritt 1 ein oder, wenn ihr auch unterwegs arbeitet, die Remote-URL aus Schritt 2. Die lokale Adresse (Custom Component: Port 9584, dafür muss Netzwerkzugriff auf „Local network“ stehen) funktioniert in jedem Anmeldemodus. Habt ihr „Home Assistant Anmeldung“ gewählt, nehmt ihr sie statt der Remote-URL:
claude mcp add-json home-assistant '{
"url": "eure-mcp-server-url",
"type": "http"
}'
Claude Code muss einmal neu gestartet werden.
ChatGPT anbinden
Vorab: Volle MCP-Unterstützung mit Schreibzugriff gibt es laut OpenAI-Hilfe nur in den Tarifen Business und Enterprise/Edu (Stand Oktober 2026), in Business legen nur Admins und Owner eigene MCP-Server an. Mit Pro verbindet ihr eigene MCP-Server nur mit Lese- und Abrufrechten, den Tarif Plus nennt OpenAI dabei nicht. Privat ist Claude deshalb der einfachere Weg.
- Auf chatgpt.com die Seite Plugins öffnen und über das Plus-Symbol Add custom MCP server wählen
- Einen Namen vergeben, z.B. „Home Assistant“, und unter Connection eure Remote-URL aus Schritt 2 eintragen
- Als Authentifizierung bei „Geheime URL“ No authentication wählen – das Geheimnis steckt im Zufallspfad der URL. Mit „Home Assistant Anmeldung“ (und beim offiziellen Server) wählt ihr OAuth und meldet euch mit einem Administratorkonto von Home Assistant an.
- Den Warnhinweis mit I understand and want to continue bestätigen, Create as a plugin wählen und das Plugin danach installieren
- Im Chat tippt ihr
@und wählt das Plugin aus
Die Bezeichnungen stammen aus der englischen Oberfläche und der OpenAI-Dokumentation, einen Developer Mode braucht ihr dafür nicht. Ändert ihr später Werkzeuge in ha-mcp, lest ihr die Werkzeugliste in den Einstellungen des Plugins neu ein.
Gemini anbinden (Antigravity CLI)
Mit einem privaten Google-Konto bindet ihr Gemini über die kostenlose Antigravity CLI (agy) an. Sie hat die Gemini CLI am 18. Juni 2026 für Gratis-Konten und Google AI Pro/Ultra abgelöst, die Gemini CLI richtet sich seitdem an Organisationen mit Gemini Code Assist Standard oder Enterprise und an Nutzer mit kostenpflichtigen API-Schlüsseln. Ohne Abo gelten wöchentliche Limits, mit Google AI Pro oder Ultra sind sie höher. In der Gemini-Web-App könnt ihr eigene MCP-Server zwar als „Custom apps“ eintragen, das geht aber nur in den USA, ab 18 und auf Englisch.
- Antigravity CLI installieren, unter Windows in PowerShell, unter macOS und Linux im Terminal:
# Windows (PowerShell)
irm https://antigravity.google/cli/install.ps1 | iex
# macOS/Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash
- Ein neues Terminal öffnen, erst dort findet es den Befehl
agy.agystarten, Farbschema und Darstellung wählen und euch im Browser mit eurem Google-Konto anmelden. Den Code, den Google danach anzeigt, fügt ihr im Terminal ein. - ha-mcp eintragen, im Heimnetz mit der lokalen URL aus Schritt 1, von unterwegs mit der Remote-URL aus Schritt 2. Mit „Home Assistant Anmeldung“ nehmt ihr die lokale URL, sie funktioniert in jedem Anmeldemodus:
agy mcp add home-assistant eure-mcp-server-url
- Mit
agy mcp listprüfen, obhome-assistantalsenablederscheint. Dannagystarten und die erste Aufgabe geben, etwa „Welche Lichter sind gerade an?“. Vor jedem Werkzeug-Aufruf fragt die CLI nach eurer Freigabe.
Der Befehl schreibt den Eintrag in die Datei ~/.gemini/config/mcp_config.json (unter Windows %USERPROFILE%\.gemini\config\mcp_config.json). Pflegt ihr sie von Hand, gehört die Adresse in das Feld serverUrl. Das Feld httpUrl der alten Gemini CLI versteht die Antigravity CLI nicht. Ein Token braucht ihr nicht, der Zufallspfad in der URL ist die Authentifizierung.
Sicherheit: MCP-Zugriff neben einem gehärteten Cloudflare-Setup
Viele von euch schützen Home Assistant mit Cloudflare Access und einem Client-Zertifikat (mTLS), eine der sichersten Varianten, ein Smart Home öffentlich erreichbar zu machen. Für den MCP-Zugriff hat das einen Haken:
Cloud-KI-Connectoren können kein von euch ausgestelltes Client-Zertifikat präsentieren. Sowohl Claude als auch ChatGPT rufen euren Server nicht von eurem Gerät aus auf, sondern aus der eigenen Cloud-Infrastruktur des Anbieters. Euer Client-Zertifikat ist an einen privaten Schlüssel gebunden, den nur euer Gerät besitzt – den kann kein KI-Anbieter mitschicken. ChatGPT legt laut OpenAI-Dokumentation inzwischen zwar ein eigenes, von OpenAI verwaltetes Client-Zertifikat vor. Das stammt aber nicht aus eurer Zertifizierungsstelle und kommt deshalb an einer Cloudflare-Regel, die euer Zertifikat verlangt, nicht vorbei.
Die Lösung, eine Ausnahme nur für den Pfad /api/webhook/, steht in Schritt 2 bei den Cloudflare-Fallen. Eure Home-Assistant-Oberfläche bleibt geschützt, ein zweiter Hostname ist nicht nötig.
Alternative, wenn ihr einen dedizierten MCP-Hostnamen nutzt (Option B)
Mit einem eigenen MCP-Hostnamen wie ha-mcp.euredomain.de (Schritt 2, Option B) braucht ihr keine Pfad-Ausnahme, nehmt diesen Hostnamen einfach von der mTLS-Pflicht aus. Ihn schützt dann der Zufallspfad der URL. Zusätzlich könnt ihr ihn per Cloudflare-Firewall-Regel auf Anthropics IP-Bereiche beschränken, wie bei der Skip-Regel in Schritt 2. Für ChatGPT taugt das kaum, weil OpenAI seine IP-Bereiche laufend ändert.
Ausblick: offizielle Tunnel-Lösungen ganz ohne öffentliche Exposition
Bei einem Tunnel baut ein kleiner Agent bei euch zu Hause eine ausgehende Verbindung zur KI-Cloud auf, euer MCP-Server braucht dann keinen öffentlichen Port mehr. OpenAI bietet das mit dem „Secure MCP Tunnel“ (offener tunnel-client auf GitHub) bereits an, unter anderem für ChatGPT und Codex. Eingerichtet wird er in den Organisationseinstellungen der OpenAI-API-Plattform (Tunnel-Verwaltung, Rollen, API-Schlüssel). Anthropic hat „MCP Tunnels“ als Research Preview mit Zugang auf Anfrage, bisher nur für die Claude API und die Console, nicht für Connectoren auf claude.ai.
Optional und potenziell gefährlich: YAML-Konfiguration bearbeiten lassen
Manche Home-Assistant-Funktionen – etwa REST-Template-Sensoren – lassen sich nur über die configuration.yaml anlegen, nicht über die Benutzeroberfläche. Die Tools dafür (ha_config_set_yaml, Datei-Lese-/Schreibzugriff) sind als Beta-Funktionen markiert und brauchen den zweiten Eintrag der Custom Component, HA-MCP File & YAML Tools. Den legt ihr auf der Seite der Integration über Eintrag hinzufügen an. Betreibt ihr ha-mcp als App, installiert ihr die Custom Component nur für diesen Eintrag. Freigeschaltet werden die Tools in den Einstellungen von ha-mcp (Panel „HA-MCP“ bzw. Weboberfläche der App, Beta-Master-Toggle plus einzelne Unter-Schalter). Weil sich diese Beta-Funktionen noch ändern, schaut für die Details in die Projekt-Doku.
Bevor ihr das aktiviert: Erstellt ein Backup. Eine KI, die eure configuration.yaml bearbeitet und dabei versehentlich die Hälfte des Inhalts verwirft, kann euer System lahmlegen. Aktiviert diese Funktion nur, wenn ihr versteht, was ihr damit freigebt.
Was ihr damit in der Praxis bauen könnt
- Neue Sensoren: „Erstelle mir einen Sensor, der die heutige Regenmenge meiner Wetterstation anzeigt“ – die KI findet die passende Quell-Entität, legt einen Utility-Meter-Helfer an und konfiguriert ihn korrekt.
- Dashboard-Elemente: Neue Badges, Karten oder ganze Dashboard-Bereiche auf Zuruf, ohne selbst eine Zeile Karten-YAML zu schreiben.
- Automationen reparieren/anpassen: „Die Automation im Kinderzimmer dimmt ab 21 Uhr nicht mehr richtig“ – die KI findet die richtige Automation, analysiert Traces, erklärt den vorgeschlagenen Fix und wendet ihn nach eurer Bestätigung an. Wer die Grundlagen von Trigger, Condition und Action erstmal selbst verstehen will, findet die in unserem Automationen-Einsteiger-Guide.
Die KI baut nur mit dem, was Home Assistant kennt. Fenster-, Bewegungs- und Präsenzmelder bindet ihr am einfachsten per Zigbee ein: Welche Sensoren sich bewährt haben, steht in Zigbee-Sensoren in Home Assistant, welcher Stick dafür passt, in der Zigbee-Gateway-Kaufberatung. Wollt ihr Home Assistant auch ohne Cloud per Sprache steuern, hilft mein Artikel zum lokalen Sprachassistenten.
Die KI kann euch auch fehlerhaften oder unsinnigen Code vorschlagen. Prüft insbesondere bei Automationen mit realen Auswirkungen (Heizung, Sicherheitsfunktionen) den vorgeschlagenen Code, bevor ihr ihn dauerhaft laufen lasst.
Troubleshooting
| Problem | Lösung |
|---|---|
| KI-Client kann sich über Cloudflare nicht verbinden, Browser-Zugriff funktioniert aber | Checkt das zuerst, bevor ihr euch in WAF-Regeln verliert: Eine häufige Ursache ist die KI-Sperre von Cloudflare (Security → Settings → AI Crawler and Agent access policies). Agents auf „Allow (do not block)“ stellen. Zusätzlich prüfen, ob eine Länder-WAF-Regel die Anfragen der KI blockiert (siehe „Länder-Sperre aktiv?“ in Schritt 2). |
| „Apps“ bzw. „Add-ons“ fehlt im Menü | Ihr habt Home Assistant Container oder Core, dort gibt es keine Apps. Nehmt die Custom Component aus Schritt 1. Seit 2026.2 heißt der Menüpunkt „Apps“ statt „Add-ons“. |
| „HA-MCP“ taucht unter Integration hinzufügen nicht auf | Über den Marketplace startet die Einrichtung direkt nach dem Installieren. Über HACS oder wenn eine Reparaturmeldung es verlangt, startet ihr Home Assistant einmal neu. |
| Einrichtung der Custom Component klappt nicht | Das Konto für HA-MCP braucht „Anmeldung erlauben“ und Administrator-Rechte. Tragt nie euren eigenen Login ein, für euer Konto nehmt ihr stattdessen ein Zugriffstoken. |
| Werkzeuge doppelt oder Verbindungsfehler | App und Custom Component laufen gleichzeitig oder sind beide im Client eingetragen. Entfernt einen der beiden Wege. |
| Tool bekannt, aber Aufruf schlägt mit „Unknown tool“ fehl | Nach Änderungen an Tool-Einstellungen (Tool Search, Read Only Mode, aktivierte/deaktivierte Tools) merkt sich euer KI-Client die alte Tool-Liste zwischen. Ein Neustart der App/Home Assistant reicht nicht – trennt und verbindet den Connector im Client neu (z.B. Connector in ChatGPT neu hinzufügen, Claude Desktop komplett schließen und neu öffnen). |
| Connector findet den MCP-Server nicht | Custom Component: Ist unter Konfigurieren „Remote-Zugriff über Webhook“ ausgeschaltet (bei der Einrichtung: Fernzugriff „Deaktiviert“)? Webhook-Proxy-App: Home Assistant nach der Installation neu gestartet? Ohne Neustart bleibt die Verbindung inaktiv. |
| ChatGPT: „Add custom MCP server“ fehlt | Eigene MCP-Server gibt es voll nur in Business und Enterprise/Edu, dort legen sie Admins und Owner bzw. freigegebene Mitglieder an. Mit Pro geht es nur lesend. Im Workspace fragt ihr euren Admin. |
| MCP-Verbindung über den mTLS-Hostnamen schlägt fehl | Erwartet bei Client-Zertifikat-Pflicht. Nutzt die Custom Component oder die Webhook-Proxy-App mit der /api/webhook/-Ausnahme in der WAF-Regel (siehe Sicherheits-Abschnitt) oder einen separaten Hostnamen ohne mTLS. |
Nur bis Home Assistant 2026.10. Ab 2026.11 installiert ihr die Custom Component von ha-mcp über den eingebauten Marketplace unter Einstellungen. Die App/das Add-on kommt ohne HACS aus, ihr installiert sie über den App-Store per Repository-URL – das geht aber nur mit Home Assistant OS oder Supervised. Die optionalen YAML-/Dateizugriffs-Tools brauchen in beiden Fällen die Custom Component.
Ja, mit der Custom Component von ha-mcp. Sie läuft als Integration in Home Assistant selbst und damit auf jeder Installationsart, auch Container und Core. Die App/das Add-on braucht dagegen den Supervisor.
Den Fernzugriff aus Schritt 2 braucht ihr nicht, wenn der Client in eurem Heimnetz läuft: Claude Desktop über mcp-remote, Claude Code oder Editoren wie VS Code und Cursor sprechen die lokale URL direkt an. Die KI selbst rechnet dabei aber weiter in der Cloud des Anbieters. Komplett lokal wird es nur mit einem lokalen Sprachmodell in einem MCP-fähigen Client, das zeigt dieser Artikel nicht.
Ja, wenn ihr ihn begrenzt: Deaktiviert gefährliche Einzel-Tools über das Panel „HA-MCP“ bzw. die Tool-Settings-Weboberfläche der App, nutzt bei Bedarf Read Only Mode oder Tool Security Policies für Freigaben, und teilt eure MCP-Server-URL mit niemandem – der Zufallspfad darin wirkt wie ein Passwort.
Claude bietet aktuell die einfachste Anbindung, weil ein einmal eingerichteter Connector automatisch auf Desktop- und Smartphone-App synct. ChatGPT braucht für Schreibzugriff Business oder Enterprise/Edu. Gemini bindet ihr außerhalb der USA über die kostenlose Antigravity CLI an.



















