Home Assistant mit Claude Desktop steuern (MCP)

Claude Desktop verbindet sich über MCP direkt mit deiner Home-Assistant-Instanz. Komplett lokal, ohne öffentliche URL, ohne Nabu Casa. Du tippst „Schalte das Licht im Flur an" und Claude macht es. Ich zeige dir den ganzen Weg Schritt für Schritt: vom Token bis zum ersten Test.

Was du brauchst

Bevor wir loslegen, kurz die Voraussetzungen. Du brauchst Home Assistant ab Version 2025.2 mit der Integration „Model Context Protocol Server", die Claude Desktop App (kostenlos, dazu gleich mehr) und Python bzw. uv auf deinem Mac oder PC. Die Installation von uv schauen wir uns gleich gemeinsam an.

Ein paar Entities müssen außerdem für Assist freigegeben sein, sonst sieht Claude schlicht nichts von deinem Smart Home.

Was Claude Desktop kostet

MCP funktioniert in allen Plänen, also auch komplett kostenlos. Der Free-Plan unterstützt allerdings nur einen Custom Connector gleichzeitig. Das reicht für Home Assistant, schränkt aber ein, wenn du noch andere MCP-Server laufen hast.

Zum Vergleich: ChatGPT erlaubt Schreibaktionen per MCP laut eigener Doku nur im Business-, Enterprise- oder Edu-Plan. Bei Claude Desktop gibt es diese Einschränkung nicht.

Was MCP eigentlich ist

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

Claude Desktop startet den MCP-Server als lokalen Prozess auf deinem Rechner. Die Verbindung zwischen deinem Mac und Home Assistant bleibt komplett im Heimnetz. Die KI-Verarbeitung selbst findet bei Anthropic in der Cloud statt. Deine Befehle verlassen also das Haus, dazu aber später noch mehr.

Schritt 1: MCP-Server-Integration in Home Assistant einrichten

Den ersten Schritt erledigt Home Assistant selbst und er dauert wirklich nur ein paar Sekunden.

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

Ab jetzt lauscht Home Assistant unter /api/mcp. Das ist der Endpoint, den Claude später über den Proxy erreicht.

Schritt 2: Entities für Assist freigeben

Ohne Freigabe sieht Claude nichts. Diese Liste ist gleichzeitig deine Sicherheitsgrenze, also überleg hier kurz, was du wirklich freigeben möchtest.

Geh auf Einstellungen → Sprachassistenten und wähle den Reiter „Freigegebene Entitäten". Dort wählst du bewusst aus, was Claude steuern und sehen darf: Wohnzimmerlicht, Temperatursensoren, Szenen. Sensibles wie Türschlösser oder Kameras lässt du lieber draußen.

Die Faustregel: Was du auch per Sprachbefehl steuern würdest, gibst du frei. Der Rest bleibt außen vor. Wenn du eine große Home-Assistant-Instanz hast, schränk die Auswahl außerdem bewusst ein, weil bei jeder Anfrage alle freigegebenen Entities mitgeschickt werden und das bei 400+ Entities einfach zu viel wird.

Schritt 3: Long-Lived Access Token erstellen

Der Token authentifiziert den MCP-Proxy später gegenüber Home Assistant. Er wird dir nur ein einziges Mal angezeigt, also gleich sicher wegspeichern.

Klick unten links auf deinen Namen, geh auf den Reiter „Sicherheit" und scroll ganz nach unten zu „Langlebige Zugriffs-Tokens". Klick auf „Token erstellen", vergib einen Namen wie Claude MCP und kopiere den Token sofort.

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

Schritt 4: uv und mcp-proxy installieren

Claude Desktop kann keine HTTP-Endpoints direkt ansprechen. Der winzige mcp-proxy übersetzt zwischen dem stdio-Kanal von Claude und dem HTTP-Endpoint von Home Assistant.

uv installieren

uv ist ein schneller Python-Paketmanager. Falls du ihn schon hast, überspring diesen Schritt. Ansonsten öffne dein Terminal und führ einen der folgenden Befehle aus:

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

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

Starte das Terminal danach neu, damit uv im PATH liegt.

Ein kurzer Hinweis dazu: Sei generell vorsichtig mit Befehlen, die du einfach ins Terminal kopierst. Diese hier findest du eins zu eins in der offiziellen Dokumentation von astral.sh, also kein Quatsch.

mcp-proxy installieren

uv tool install mcp-proxy

Prüf danach mit which mcp-proxy, ob der Pfad gefunden wird. Das Ergebnis merkst du dir, denn wenn Claude ihn später nicht findet, trägst du den vollen Pfad in die Config ein.

Schritt 5: Claude Desktop konfigurieren

Die Config-Datei liegt je nach Betriebssystem an unterschiedlichen Stellen. Auf dem Mac ist es ~/Library/Application Support/Claude/claude_desktop_config.json, unter Windows findest du sie unter %APPDATA%\Claude\claude_desktop_config.json.

Config öffnen

Am einfachsten geht das direkt aus Claude Desktop: Menüleiste öffnen → Settings → Developer → Edit Config. Alternativ im Terminal:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

MCP-Server eintragen

Füge diesen Block ein und passe IP-Adresse und Token an deine Instanz an:

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_AUS_SCHRITT_3"
12      }
13    }
14  }
15}

Die URL muss auf die Adresse zeigen, unter der dein Mac Home Assistant erreicht. Das kann homeassistant.local, eine IP wie 192.168.1.100 oder deine Nabu-Casa-URL sein. Für den lokalen Weg brauchst du kein HTTPS und keine öffentliche Adresse.

Falls du schon andere MCP-Server in der Config hast, fügst du "Home Assistant": { ... } als weiteren Eintrag innerhalb von "mcpServers" hinzu. Achte darauf, dass die JSON-Struktur valide bleibt, also Kommas an den richtigen Stellen.

Claude Desktop neu starten

Claude Desktop komplett beenden (Cmd+Q auf dem Mac) und neu öffnen. Ein Fenster schließen reicht nicht. Die Config wird nur beim Start geladen.

Schritt 6: Testen

Nach dem Neustart taucht „Home Assistant" bei den verfügbaren Tools auf. Klick auf das + im Chat-Eingabefeld und dann auf Connectors. Dort sollte „Home Assistant" stehen.

Beim ersten Aufruf fragt Claude, ob du die Tool-Nutzung erlauben willst. Bestätige das, am besten mit „immer erlauben", damit er nicht bei jeder Aktion nachfragt.

Dann einfach mal ausprobieren:

• „Welche Lampen sind gerade an?"
• „Schalte das Licht im Flur an."
• „Wie warm ist es im Wohnzimmer?"
• „Aktiviere die Szene Filmabend."

Was mich dabei immer wieder fasziniert: Du sagst ihm nicht, er soll in Home Assistant nachschauen. Den Schluss zieht er selbst, weil er weiß, dass der MCP-Server zur Verfügung steht.

Troubleshooting

Wenn etwas nicht funktioniert, hier die häufigsten Probleme und ihre Lösung.

Claude findet mcp-proxy nicht (ENOENT). Der Pfad liegt nicht im PATH von Claude Desktop. Trag bei "command" den vollen Pfad ein, zum Beispiel /Users/deinname/.local/bin/mcp-proxy, also das Ergebnis von which mcp-proxy.

„Home Assistant" taucht nicht unter Connectors auf. Config-Datei prüfen: valides JSON? Komma zwischen mehreren Servern? Danach Claude Desktop beenden (Cmd+Q) und neu starten.

401 / nicht autorisiert. Token falsch oder widerrufen. Neuen Token erstellen. Der Schlüssel muss exakt API_ACCESS_TOKEN heißen.

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

mcp-proxy startet nicht. Veraltete Installation. Mit uv tool install --force mcp-proxy neu installieren und Claude neu starten.

Endpoint manuell testen. Ein POST an /api/mcp mit Authorization-Header zeigt dir, ob der Server überhaupt antwortet:

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

HTTP 200 mit serverInfo.name: home-assistant bedeutet, der Server läuft. 401 ist ein Token-Problem, 404 bedeutet, die MCP-Server-Integration fehlt.

Logs prüfen:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Bonus: ha-mcp, der Community-Server mit 88+ Tools

Der offizielle MCP-Server kann nur das, was die Assist-API hergibt. Das Community-Projekt ha-mcp geht deutlich weiter. Über 4.600 Stars auf GitHub, MIT-Lizenz, und 88+ Werkzeuge, mit denen Claude auch Automationen erstellen und bearbeiten, Dashboards bauen, Helpers verwalten, History abfragen, Backups anlegen und vieles mehr kann.

Voraussetzungen für ha-mcp

Du brauchst Python 3.13 oder 3.14 auf deinem Rechner. ha-mcp läuft nicht mit älteren Versionen. uv ist bereits installiert aus Schritt 4.

Installation und Konfiguration

ha-mcp bringt einen Setup Wizard mit, der die passende Config für deinen Client generiert.

Öffne homeassistant-ai.github.io/ha-mcp/setup/, wähle Claude Desktop als Client, trage deine HA-URL und den Long-Lived Token ein. Der Wizard generiert den fertigen JSON-Block für deine claude_desktop_config.json. Block einfügen, Claude Desktop neu starten, fertig.

Alternativ die Quick-Installation für macOS:

curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh

Oder manuell per uvx:

1{
2  "mcpServers": {
3    "ha-mcp": {
4      "command": "uvx",
5      "args": ["ha-mcp@latest"],
6      "env": {
7        "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
8        "HOMEASSISTANT_TOKEN": "DEIN_LANGLEBIGER_TOKEN"
9      }
10    }
11  }
12}

Was ha-mcp zusätzlich kann

Beispiel-Prompts, die mit ha-mcp funktionieren

• „Erstelle eine Automation: Wenn die Haustür geöffnet wird, schalte das Flur-Licht für 5 Minuten ein."
• „Zeig mir die Temperatur-Historie des Wohnzimmers der letzten 24 Stunden."
• „Welche Automationen laufen gerade und welche sind deaktiviert?"
• „Erstelle einen Toggle-Helper namens Urlaubsmodus."
• „Mach ein Backup bevor du etwas änderst."

Das ist eigentlich der Punkt, wo es für mich wirklich interessant wird. Du musst nicht mehr überlegen, wie eine Automation in YAML aufgebaut sein muss oder welche Syntax Helpers brauchen. Du beschreibst einfach, was du willst.

Offiziell vs. ha-mcp: wann was?

Für den Einstieg reicht der offizielle MCP-Server. Wer mehr will, installiert ha-mcp zusätzlich oder als Ersatz.

Was geht, was nicht

Mit dem offiziellen MCP-Server kannst du Lichter, Schalter, Szenen, Klima und Cover schalten, Sensorwerte abfragen und mehrere Schritte in einem Satz kombinieren, zum Beispiel „Mach das Wohnzimmer gemütlich und stell die Heizung auf 21 Grad".

Was er nicht kann: Automationen oder YAML anlegen, Entities sehen, die nicht für Assist freigegeben sind, Benachrichtigungen verschicken oder Dashboards und Helpers verwalten. Für all das ist ha-mcp die bessere Wahl.

Datenschutz

Sobald Claude im Spiel ist, verlässt deine Anfrage das Haus und landet bei Anthropic. Die MCP-Verbindung zwischen deinem Rechner und Home Assistant bleibt lokal, aber die KI-Verarbeitung passiert in der Cloud. Wer das nicht möchte, und das kann ich gut verstehen, bleibt bei der lokalen Assist-Sprachsteuerung oder setzt auf ein lokales LLM. Wie das geht, ist ein eigenes Thema.

Vergleich: Claude Desktop vs. ChatGPT

Claude Desktop ist die bessere Wahl, wenn Home Assistant nur im Heimnetz erreichbar ist und du keine Plan-Einschränkungen willst. ChatGPT bietet dafür eine grafische Einstellungsoberfläche statt JSON-Config.

Die offizielle Home-Assistant-Dokumentation zum MCP-Server erklärt die Integration außerdem noch mal ausführlich, falls du einzelne Schritte nachlesen möchtest. Stand dieses Guides ist September 2026.

Nutzt du Claude oder ein anderes KI-Modell für dein Smart Home? Was hast du bisher damit gemacht und was würdest du dir noch wünschen?