ha-mcp über HACS: KI baut Automationen in Home Assistant

Ich habe mir in letzter Zeit einiges zum Thema MCP und Home Assistant angeschaut. Einen eigenen MCP-Server aufzusetzen, ihn mit Claude Code oder ChatGPT zu verbinden, das habe ich in früheren Artikeln schon gezeigt. Was mich an der bisherigen Lösung gestört hat: Der Server lief auf meinem lokalen Rechner. Ist der Rechner aus, ist der Server weg. Das ändert ha-mcp jetzt. Die Custom Component installiert sich direkt über HACS und startet den vollständigen MCP-Server innerhalb von Home Assistant. Kein Add-on, kein Container, kein Long-Lived-Token. Du bekommst eine Verbindungs-URL, trägst sie in deinen KI-Client ein, und ab da kann die KI Automationen anlegen, Dashboards bauen und Fehler auswerten, direkt in deiner Instanz.

Was mich dabei besonders interessiert: Der eingebaute MCP-Server von Home Assistant hat rund 15 Werkzeuge und kommt schnell an seine Grenzen. ha-mcp bringt 87 Werkzeuge mit und hebt die meisten dieser Grenzen auf. Der Unterschied ist im Alltag tatsächlich spürbar.

Was du brauchst

Bevor du anfängst, ein paar Voraussetzungen, die wirklich alle erfüllt sein müssen:

Home Assistant 2026.8.0 oder neuer. HACS prüft das beim Installieren, der Konfigurationsdialog prüft es ebenfalls. Deine aktuelle Version findest du unter Einstellungen, System, dann oben rechts im Drei-Punkte-Menü unter Systeminformationen.

HACS. Die Integration liegt nicht im Standard-Store und wird als eigenes Repository hinzugefügt. Falls HACS bei dir noch nicht läuft, findest du auf hacs.xyz eine Anleitung.

Einen MCP-fähigen Client. Ich zeige das hier mit Claude Code und ChatGPT. Der Setup-Assistent des Projekts listet über 15 weitere Clients auf, falls du etwas anderes nutzt.

Für ChatGPT zusätzlich eine extern erreichbare Adresse. ChatGPT verbindet sich aus der Cloud, eine rein lokale URL reicht nicht. Claude Code im Heimnetz kommt auch ohne aus.

Ein aktuelles Backup. Die KI darf nach der Einrichtung deine Konfiguration wirklich ändern, das ist ja der Sinn der Sache. Aber einen Rücksetzpunkt vorher anlegen ist trotzdem sinnvoll, aus ganz vielen verschiedenen Gründen.

Und noch ein wichtiger Hinweis vorab: Wenn bei dir schon ein ha-mcp Add-on, ein Docker-Container oder eine uvx-Installation läuft, darfst du den In-Process-Server nicht zusätzlich starten. Die Projektdokumentation nennt zwei parallel laufende Server als bekannte Ursache für hängende Verbindungen. Stoppe die alte Installation, bevor du die neue anlegst.

Schritt 1: Repository in HACS hinzufügen

Die Integration liegt in einem eigenen Spiegel-Repository und taucht deshalb in der normalen HACS-Suche nicht auf. So fügst du sie hinzu:

1. Öffne HACS in der Seitenleiste.
2. Klicke oben rechts auf das Drei-Punkte-Menü und wähle Benutzerdefinierte Repositories.
3. Trage als Repository-URL ein:

https://github.com/homeassistant-ai/ha-mcp-integration

4. Wähle als Kategorie Integration und bestätige mit Hinzufügen.
5. Suche in HACS nach HA-MCP Custom Component und klicke auf Herunterladen.

Das Repository ha-mcp-integration ist bewusst ein separates Spiegel-Repository. Wer die Komponente früher direkt aus dem Server-Repository ha-mcp gezogen hat, bekommt später eine Reparatur-Meldung mit dem Titel Component installed from the legacy repository und sollte dann auf das Spiegel-Repository wechseln.

Schritt 2: Home Assistant neu starten

Nach dem Download ist ein Neustart nötig, damit Home Assistant die neue Integration kennt. Einstellungen, System, oben rechts das Netzschalter-Symbol, Home Assistant neu starten. Das dauert vielleicht eine Minute, danach ladedie Seite am besten einmal hart neu. Auf dem Mac hilft Command Shift R, damit du nicht mit einem gecachten Frontend weiterarbeitest.

Schritt 3: Die Integration anlegen

1. Gehe zu Einstellungen, Geräte & Dienste, Integration hinzufügen.
2. Suche nach HA-MCP Custom Component.
3. Es erscheint ein Auswahlmenü mit zwei Einträgen. Der erste ist HA-MCP Server, der vollständige Server, der direkt in Home Assistant läuft. Den willst du. Der zweite Eintrag, HA-MCP File & YAML Tools, ist optional und nur nötig, wenn du die Datei- und YAML-Werkzeuge freischalten möchtest oder dein Server außerhalb von Home Assistant läuft.
4. Wähle HA-MCP Server und bestätige mit Absenden.

Der erste Start dauert etwas länger, weil Home Assistant das Paket ha-mcp per pip nachinstalliert. Das läuft im Hintergrund und verzögert den Systemstart nicht. Sobald der Server läuft, erscheint eine Benachrichtigung mit dem Titel HA-MCP Server.

Was dabei im Hintergrund passiert: Die Integration legt sich einen eigenen Administrator-Token an, mit dem der Server über die lokale Schleife auf Home Assistant zugreift. Sie startet den Server in einem eigenen Thread, damit ein langsamer Werkzeugaufruf die Ereignisschleife von Home Assistant nicht blockiert. Und sie registriert einen Webhook, über den der Server von außen erreichbar ist.

Schritt 4: Die Verbindungs-URL holen

Die URL steht nicht in der Benachrichtigung, und das ist Absicht. Benachrichtigungen sieht jeder angemeldete Nutzer, und die URL ist das Passwort.

Du findest sie unter Einstellungen, Geräte & Dienste, HA-MCP Custom Component, HA-MCP Server, Konfigurieren. Zusätzlich steht sie im Home-Assistant-Protokoll. Beide Orte sind nur für Administratoren sichtbar.

Es gibt drei Formen:

1Remote über Nabu Casa oder Reverse-Proxy:
2https://deine-domain/api/webhook/mcp_xxxxxxxxxxxx
3
4Lokal im Heimnetz:
5http://deine-ha-adresse:8123/api/webhook/mcp_xxxxxxxxxxxx
6
7Direkt auf dem Server-Port:
8http://deine-ha-ip:9584/private_xxxxxxxxxxxx

Port 9584 ist bewusst gewählt: Das Add-on nutzt 9583, damit sich beide nicht in die Quere kommen. Behandle jede dieser URLs wie ein Passwort und gib sie nicht weiter, vor allem nicht, wenn du mit einer öffentlichen Adresse arbeitest.

Schritt 5: Claude Code verbinden

Ein Befehl im Terminal, die URL aus Schritt 4 eingesetzt:

claude mcp add --transport http home-assistant https://deine-domain/api/webhook/mcp_xxxxxxxxxxxx

Danach claude starten und mit /mcp prüfen, ob der Server verbunden ist. Ein guter erster Test ist die Frage, ob Claude deine Home-Assistant-Instanz sieht.

Schritt 6: ChatGPT verbinden

ChatGPT verbindet sich aus der Cloud, deine URL muss also öffentlich erreichbar sein. Eine Adresse, die nur im Heimnetz funktioniert, reicht nicht aus.

1. Aktiviere in ChatGPT den Entwicklermodus und lege einen neuen Connector an.
2. Trage die Webhook-URL aus Schritt 4 ein.
3. Bestätige die Verbindung.

Zwei Stolpersteine, die genau hier häufig zuschlagen:

Kein Port in der URL. Die öffentliche Adresse darf kein :8123 und keinen anderen Port enthalten. Im eigenen Browser funktioniert das trotzdem, entfernte Clients kommen damit nicht durch. Home Assistant darf intern weiter auf 8123 lauschen, solange ein Proxy oder Tunnel den Hostnamen bedient.

Cloudflare blockiert KI-Bots. Wer Cloudflare davorhat, findet unter Domains, Übersicht, Control AI Crawlers die Einstellung Block AI training bots. Steht sie auf blockieren, kommt kein Client durch, obwohl die URL im Browser lädt. Das Gleiche gilt für Länder-Sperren in jedem anderen Reverse-Proxy.

Wenn du Home Assistant gar nicht öffentlich machen willst, gibt es den OpenAI-Tunnel als Community-Integration. Er baut eine ausgehende Verbindung auf, ohne Portfreigabe.

Schritt 7: Das Einstellungs-Panel nutzen

Solange der Server läuft, erscheint in der Seitenleiste ein Eintrag HA-MCP. Dahinter liegt die Weboberfläche des Servers: Werkzeuge einzeln ein- und ausschalten, anheften, Funktions-Flags setzen, Backups und Themes verwalten.

Das Panel ist nur für Administratoren zugänglich. Beim Öffnen entsteht eine kurzlebige Sitzung für deinen Home-Assistant-Login, und jede Anfrage prüft erneut, ob dein Konto noch Administrator ist. Ein Geheimnis taucht dabei nie in der Adresszeile auf.

Schritt 8: Sicherheit einstellen

Der Werkzeugkasten umfasst 87 Werkzeuge, und sie laufen mit Administratorrechten. Drei Stellschrauben, die du kennen solltest:

Read Only Mode. Ein Schalter, nach dem die KI nur noch lesen darf. Ideal für die ersten Tage, in denen du dich an das Zusammenspiel gewöhnst.

Werkzeuge einzeln abschalten. Im Panel, pro Werkzeug. Was aus ist, ist überall aus.

Authentifizierungsmodus. Unter Konfigurieren stehen drei Möglichkeiten: Secret Webhook URL (Standard), bei der die URL das Passwort ist, Mit Home Assistant anmelden (OAuth), bei der sich Clients mit deinem Home-Assistant-Konto anmelden, und Legacy OAuth für Clients, die zwingend eine Client-ID brauchen.

Wenn eine URL abhandengekommen ist: In den Optionen Verbindungs-Secrets jetzt neu generieren ankreuzen und speichern. Beide Geheimnisse werden sofort neu gezogen, alle alten URLs sind ungültig. Danach die Clients neu eintragen.

Schritt 9: Assist und Sprache mit demselben Werkzeugkasten

Das ist der Teil, den viele übersehen. Während der Server läuft, meldet er seinen Werkzeugkasten zusätzlich als LLM-API in Home Assistant an. Jeder Konversationsagent kann ihn auswählen, egal ob OpenAI, Google, Anthropic oder ein lokales Ollama.

1. Richte einen Konversationsagenten ein.
2. Wähle in dessen Einstellungen unter Home Assistant steuern den Eintrag HA-MCP Server (tool search).
3. Sprich den Agenten über den Assist-Dialog, die Companion-App oder einen Sprachsatelliten an.

Ab da kann ein Satz wie „erstelle eine Automation, die das Licht ausschaltet, wenn alle das Haus verlassen" tatsächlich eine Automation anlegen.

Zwei Einschränkungen, die du kennen solltest: Konversationsagenten begrenzen die Anzahl der Werkzeugaufrufe pro Antwort auf etwa zehn, komplexe Aufgaben brauchen also eine Nachfrage. Und sicherheitstechnisch gibst du damit jedem, der mit diesem Agenten sprechen darf, die Rechte des Servers. Bei einem Sprachsatelliten im Wohnzimmer heißt das: jedem in Hörweite. Lass die LLM-API auf Pipelines aus, bei denen das nicht gewollt ist.

Schritt 10: Die erste Automation bauen lassen

Ein guter Einstieg, weil das Ergebnis sofort sichtbar ist. Ich habe das selbst ausprobiert, indem ich Claude folgendes gegeben habe:

Lege eine Automation an, die die Außenbeleuchtung bei Sonnenuntergang einschaltet
und um 23 Uhr wieder aus.

Danach einfach im Automationseditor nachsehen, was entstanden ist. Genau das ist der Vorteil gegenüber dem eingebauten MCP-Server von Home Assistant: Der arbeitet über die Assist-Pipeline und sieht nur Geräte, die du für Assist freigegeben hast. ha-mcp sieht alles, legt an, ändert und liest Traces mit.

Damit die KI die richtigen Entitäten findet, lohnt es sich, vorher kurz zu prüfen, welche davon für Assist freigeschaltet sind. Unter Einstellungen, Sprachassistenten findest du die Liste. Entitäten, die du für Automationen brauchst, kannst du dort einzeln hinzufügen. Ha-mcp greift allerdings unabhängig davon auf alle Entitäten zu, die du nicht aktiv gesperrt hast.

Tipps & Troubleshooting

Updates laufen automatisch, in zwei getrennten Spuren. Der Server aktualisiert sich selbst aus dem gewählten Release-Kanal, geprüft wird alle sechs Stunden. Die Komponente selbst kommt weiterhin über HACS. Das sind zwei verschiedene Versionsnummern, aktuell Server 8.4.3 und Komponente 2.1.3.

Reparatur-Meldung „server update waiting for a component update". Bringt ein Server-Update auch eine neuere Komponente mit, wird das Update zurückgehalten, statt eine ungetestete Kombination zu starten. HACS zeigt das Komponenten-Update zu diesem Zeitpunkt meistens noch nicht an, weil es seine Repository-Informationen nur alle paar Tage erneuert. Wenn es nicht von allein auftaucht: in HACS das Repository öffnen, Drei-Punkte-Menü, Update information.

Die Verbindung hängt. Erste Frage: Läuft noch eine zweite ha-mcp-Installation? Ein Client, der gleichzeitig einen lokalen uvx-Eintrag und die Komponenten-URL kennt, ist die dokumentierte Standardursache.

Claude.ai meldet „Couldn't reach the MCP server". Beim ersten Handschlag ist das normal. Prüfen kannst du es über den Konfigurieren-Knopf am Connector: Werden dort Werkzeuge gelistet, steht die Verbindung.

Nur lokal betreiben. In den Optionen Remote-Zugriff über Webhook ausschalten. Dann wird gar kein Webhook registriert, auch Nabu Casa kommt nicht mehr durch. Direktzugriff über den Server-Port und das Seitenleisten-Panel funktionieren weiter.

Server pausieren statt löschen. Den Konfigurationseintrag deaktivieren hält den Server an, ohne die Einstellungen zu verlieren. Beim Entfernen des Eintrags wird zusätzlich der intern angelegte Token widerrufen.

Bessere Ergebnisse mit Agent Skills. Ein MCP-Server gibt der KI Werkzeuge, aber keine Meinung darüber, wie eine gute Automation aussieht. Die Agent Skills des Projekts liefern genau dieses Fachwissen und sind bereits eingebaut, erreichbar über das Werkzeug ha_get_skill_guide.

Nutzt du ha-mcp schon, oder hast du bisher den eingebauten MCP-Server von Home Assistant verwendet? Was sind deine Erfahrungen damit?