ha-mcp: Home Assistant als Werkzeugkasten für MCP-Clients
The Unofficial and Awesome Home Assistant MCP Server
Auf einen Blick
- Was ist das?
- Der inoffizielle MCP-Server für Home Assistant läuft als HACS-Integration direkt im Prozess, versteht 87 Tools und ersetzt Add-on, Docker und stdio. Wer ihn einsetzt, sollte wissen, warum die Dokumentation ein Beta-Verzeichnis führt.
- Für wen ist es gedacht?
- Wer Home Assistant OS oder Supervised betreibt und Claude Desktop, Claude.ai oder ChatGPT anbinden will, fährt mit der HACS-Integration am einfachsten, weil kein Token verwaltet werden muss. Wer bereits ein Add-on oder einen Docker-Container laufen hat, darf die In-Process-Variante nicht zusätzlich starten, sonst konkurrieren zwei Server um dieselbe Instanz.
- Darf ich es kommerziell nutzen?
- Ja. MIT ist eine freizügige Lizenz: Sie dürfen darauf aufbauende Software nutzen, verändern und verkaufen, solange Sie die Urheberrechts- und Lizenzhinweise beibehalten.
- Wird es noch gepflegt?
- Ja. Das Repository hat innerhalb des letzten Tages neue Commits erhalten.
- In welcher Sprache ist es geschrieben?
- Hauptsächlich Python, laut der Sprachstatistik von GitHub.
Die Antworten beruhen auf den GitHub-Daten des Projekts (zuletzt abgeglichen am 15. September 2026) und auf unserer Analyse. Sie sind keine Rechtsberatung.
TIEFGEHENDE OPEN-SOURCE-ANALYSE
Welches Problem der Server löst und für wen er gedacht ist
Home Assistant hat eine REST-API, eine WebSocket-Schnittstelle und einen Dienst-Aufrufmechanismus, aber kein Sprachmodell weiß von sich aus, welche Entität gerade welchen Zustand hat oder welcher Service welche Parameter erwartet. Genau diese Lücke füllt ha-mcp. Der Server beschreibt sich selbst als Model Context Protocol Server, der KI-Assistenten in die Lage versetzt, Geräte zu steuern, Zustände abzufragen, Services auszuführen und Automatisierungen zu verwalten. Die Zielgruppe sind also nicht Entwickler, die eine Bibliothek einbinden, sondern Betreiber, die einen fertigen MCP-Client wie Claude Desktop oder ChatGPT mit ihrer Installation verbinden wollen.
Der Umfang ist beträchtlich. Das Repository nennt 87 Tools, und das README dokumentiert mehrere Installationswege mit ausdrücklichem Hinweis, dass pro Client genau einer davon verwendet werden darf. Diese Warnung ist der wichtigste Satz im Einstiegsteil, denn sie beschreibt keinen Stilbruch, sondern eine technische Randbedingung: die Varianten sind unabhängige Server, die auf dieselbe Home-Assistant-Instanz zeigen.
In-Process statt Sidecar: der eigentliche Architekturunterschied
Die empfohlene Variante ist eine HACS-Integration namens HA-MCP Custom Component. Sie läuft laut README in-process, also im selben Prozess wie Home Assistant, und funktioniert auf jeder Installationsart: Home Assistant OS, Supervised, Container und Core, jeweils mit voller Funktionsparität. Das ist der entscheidende Unterschied zu einem Add-on oder einem Docker-Container, die als getrennte Prozesse daneben stehen und sich über die API verbinden müssen.
Daraus folgen zwei Dinge. Erstens entfällt ein Zugriffstoken, weil der Server bereits innerhalb der Instanz arbeitet. Zweitens ist die Reichweite größer: ein Add-on setzt Home Assistant OS oder Supervised voraus, die In-Process-Variante nicht. Der Preis ist die Kopplung. Der Server teilt sich Lebensdauer und Ressourcen mit Home Assistant, und das README sagt ausdrücklich, man solle ihn nicht parallel zu einem anderen Installationsweg betreiben. Zwei Einträge in derselben Oberfläche sind kein Load-Balancing, sondern eine Fehlerquelle.
Für entfernte Clients registriert die Integration einen Webhook unter dem Pfad /api/webhook/<webhook-id>, erreichbar über Nabu Casa oder einen Reverse Proxy, der bereits auf Home Assistant zeigt. Lokal lautet die Adresse http://<ha-host>:8123/api/webhook/<webhook-id>. Für Clients im selben Netz gibt es zusätzlich einen direkten Port unter http://<ha-ip>:9584/private_<random>. Der Zufallsteil dieser URL ist offenbar der einzige Schutz im Standardfall.
Webhook-URL als Credential und die Option ha_auth
Wer den Webhook aktiviert, macht die Geheimhaltung der URL zur Authentifizierung. Das README beschreibt genau das: die URL dient als Credential. Für ein Heimnetz ist das eine vertretbare Abwägung, für eine über Nabu Casa erreichbare Instanz ist es eine Entscheidung, die man bewusst treffen sollte. Die Alternative ist dokumentiert: In den Optionen des Eintrags lässt sich Webhook authentication auf ha_auth setzen, dann verlangt der Server eine Anmeldung mit einem Home-Assistant-Konto statt der geheimen URL.
Wer den Webhook gar nicht braucht, kann Remote access via webhook in den Optionen abschalten. Dann wird nach Angabe des README überhaupt kein Webhook registriert, während der direkte Port und das Seitenleisten-Panel weiter funktionieren. Das ist der sauberste Rückzugsweg für Installationen, die ausschließlich im lokalen Netz genutzt werden.
Nebenbei entsteht ein Administrationspunkt: Während der Server läuft, erscheint ein nur für Administratoren sichtbares HA-MCP-Panel in der Seitenleiste, über das sich Tools, Feature-Flags, Backups und Themes verwalten lassen. Das Panel ist kein Zusatzprodukt, sondern Teil der Integration.
Installation über HACS in fünf Schritten
Der Weg ist im README Schritt für Schritt beschrieben. Zuerst die Integration als Custom Repository in HACS hinzufügen, Quelle https://github.com/homeassistant-ai/ha-mcp-integration, Kategorie Integration, dann Download. Danach Home Assistant neu starten. Anschließend unter Einstellungen, Geräte und Dienste, Integration hinzufügen nach HA-MCP Custom Component suchen, HA-MCP Server auswählen und mit Submit bestätigen. Das Anlegen des Eintrags startet den Server.
Die Verbindungs-URL steht danach im Configure-Bildschirm des Eintrags und zusätzlich im Home-Assistant-Log, begleitet von einer Benachrichtigung. Diese URL wird in den KI-Client eingefügt. Wer HACS nicht nutzen kann, kopiert custom_components/ha_mcp_tools/ aus dem Repository in das Verzeichnis config/custom_components/ der eigenen Installation, startet neu und legt den Eintrag wie beschrieben an.
Ein zweiter Eintragstyp existiert: HA-MCP File & YAML Tools. Er ist nur nötig, wenn die optionalen Datei- und YAML-Werkzeuge aktiviert werden, die über Feature-Flags standardmäßig ausgeschaltet sind. Er lässt sich jederzeit nachträglich hinzufügen und funktioniert mit jedem Server-Typ. Wer nur Geräte steuern will, überspringt ihn.
YAML-Bearbeitung als Beta und die Folgekosten
Ganz oben im README steht ein Hinweis, der leicht überlesen wird: Mit v7.3.0 wurde ha_config_set_yaml nach beta verschoben, Verweis auf docs/beta.md. Ein Tool, das Konfigurations-YAML schreibt, ist inhärent riskant, weil ein fehlerhafter Schreibvorgang eine laufende Installation beschädigen kann. Die Verschiebung nach beta ist damit keine Formalie, sondern eine Aussage über den Reifegrad.
Daraus ergibt sich der eigentliche Wartungsaufwand. Das Projekt veröffentlicht Entwicklungs-Builds im Abstand von Stunden: v8.4.3.dev2608 am 2026-09-09T12:29:00Z, v8.4.3.dev2605 am selben Tag um 09:06:37Z, v8.4.3.dev2602 um 01:55:30Z. Diese Kadenz bedeutet, dass die Versionsnummer im Betrieb wenig über den getesteten Stand aussagt. Wer Aktualisierungen einspielt, sollte vorher prüfen, ob sich Tool-Namen oder Feature-Flags verschoben haben, denn die Breaking-Change-Notiz zeigt, dass solche Umzüge vorkommen.
Lizenzseitig steht das Projekt unter MIT, was Weitergabe und Änderung erlaubt, solange Copyright- und Lizenzhinweis erhalten bleiben. Das gilt für das Repository; für die HACS-Integration existiert ein separates Repository, dessen Lizenz aus dem vorliegenden Material nicht hervorgeht. Wer die Integration weiterverbreitet, sollte das klären, bevor er sich auf die MIT-Angabe des Servers beruft. Rechtsberatung ist das nicht.
Wann ein anderer Weg die bessere Wahl ist
Das README selbst nennt die Alternative: das Home Assistant App (Add-on). Es läuft auf Home Assistant OS und Supervised, ebenfalls ohne Zugriffstoken, und verbindet Claude Desktop, Claude.ai, ChatGPT sowie andere MCP-Clients im lokalen Netz oder über konfigurierten Fernzugriff. Der Unterschied liegt im Betriebsmodell. Das Add-on ist ein eigener Prozess mit eigenem Lebenszyklus, den man neu starten kann, ohne Home Assistant anzufassen. Die In-Process-Integration kann das nicht, weil sie Teil der Instanz ist.
Für Betreiber einer Container- oder Core-Installation stellt sich die Frage ohnehin nicht, dort gibt es kein Add-on. Für Betreiber auf Home Assistant OS mit häufigen Neustarts des Servers ist das Add-on die entspanntere Wahl. Die dritte Variante, Docker oder PyPI über uvx mit stdio, taucht im README nur als eine der unabhängigen Installationsarten auf, ohne dass Details im vorliegenden Auszug stehen. Wer diesen Weg braucht, muss die verlinkte Dokumentation selbst lesen.
Grenzen, die aus dem Material selbst sichtbar werden
Die wichtigste Einschränkung ist die Ein-Server-Regel. Das README verlangt ausdrücklich, nur eine Installationsmethode pro Client zu betreiben. Wer bereits ein Add-on laufen hat und die HACS-Integration ausprobiert, ohne das Add-on zu stoppen, betreibt zwei Server gegen dieselbe Instanz. Das ist kein theoretischer Fall, sondern der wahrscheinlichste Fehler beim Umstieg.
Die zweite Grenze betrifft die Reichweite der Steuerung. Der Server kann Geräte steuern, Zustände abfragen, Services ausführen und Automatisierungen verwalten. Ob ein Sprachmodell dabei die richtige Entität trifft, hängt von der Qualität der Namen in der eigenen Installation ab, nicht vom Server. 87 Tools lösen kein Namenschaos.
Die dritte Grenze ist der Beta-Status der YAML-Werkzeuge. Wer Automatisierungen per Sprache schreiben lassen will, arbeitet in einem Bereich, den das Projekt selbst als nicht allgemein freigegeben markiert. Die vierte ist struktureller Natur: Die Dokumentation im vorliegenden Auszug bricht mitten im Satz ab, und Details zu Docker und stdio fehlen. Wer diese Wege plant, kann sich auf dieser Grundlage kein Urteil bilden.
Was vor der Übernahme zu prüfen ist
Vor dem ersten Start sollte klar sein, welcher Installationsweg bereits aktiv ist. Ein Blick in Einstellungen, Geräte und Dienste zeigt, ob ein HA-MCP-Eintrag existiert, und die App-Liste zeigt, ob das Add-on läuft. Erst danach entscheidet sich, ob die HACS-Integration zusätzlich sinnvoll ist oder ob sie einen bestehenden Server ersetzt.
Danach lohnt die Frage, ob Fernzugriff nötig ist. Wird Remote access via webhook abgeschaltet, entfällt die geheime URL als einziges Credential, und der direkte Port auf 9584 bleibt nutzbar. Wer Fernzugriff braucht, sollte Webhook authentication auf ha_auth stellen, statt sich auf die Unauffindbarkeit der URL zu verlassen.
Zuletzt ist der Changelog-Punkt zu v7.3.0 zu prüfen, bevor YAML-Tools aktiviert werden. Der Hinweis steht nicht ohne Grund an erster Stelle des README.
Redaktionelles Fazit
Wer Home Assistant OS oder Supervised betreibt und Claude Desktop, Claude.ai oder ChatGPT anbinden will, fährt mit der HACS-Integration am einfachsten, weil kein Token verwaltet werden muss. Wer bereits ein Add-on oder einen Docker-Container laufen hat, darf die In-Process-Variante nicht zusätzlich starten, sonst konkurrieren zwei Server um dieselbe Instanz. Wer YAML direkt bearbeiten will, muss zuerst die Feature-Flags aktivieren und den zweiten Eintrag HA-MCP File & YAML Tools anlegen. Vor dem Umstieg lohnt ein Blick in den Changelog zu v7.3.0, weil dort ha_config_set_yaml nach beta verschoben wurde.
Community-Notizen