Claude Code läuft im Terminal und versteht normale Sätze. Über das Model Context Protocol, kurz MCP, redet es direkt mit Home Assistant: Geräte schalten, Zustände abfragen, Automationen schreiben lassen. Anders als bei Claude Desktop brauchst du dafür kein Hilfsprogramm. Ein Befehl genügt.
Diese Anleitung ist Stand September 2026, geprüft mit Claude Code 2.1.263 und Home Assistant 2026.9.1.
Was du brauchst
Bevor wir loslegen, kurz die Voraussetzungen. Du brauchst Home Assistant ab Version 2025.2, weil erst ab da die eingebaute Integration Model Context Protocol Server existiert. Dazu ein Claude-Abo, also Pro, Max, Team oder Enterprise. Der kostenlose Plan schließt Claude Code aus. Alternativ funktioniert ein API-Key auf Abrechnung, also pay as you go.
Auf der Rechnerseite reicht macOS 13 oder neuer, Windows 10 ab Build 1809 oder Ubuntu 20.04 aufwärts. 4 GB RAM genügen. Dein Home Assistant muss im selben Netz erreichbar sein, meist unter http://homeassistant.local:8123. Eine öffentliche URL oder Nabu Casa brauchst du nicht.
Und was du ausdrücklich nicht brauchst: Node.js. Ältere Anleitungen führen darüber, der native Installer bringt ein fertiges Programm mit.
Schritt 1: Claude Code installieren
Der Installer ist tatsächlich eine der leichtesten Übungen. Auf macOS und Linux schnappst du dir einfach diesen Befehl:
curl -fsSL https://claude.ai/install.sh | bashWer Homebrew nutzt, nimmt stattdessen:
brew install --cask claude-codeUnter Windows sieht das in PowerShell so aus:
irm https://claude.ai/install.ps1 | iexOder über WinGet:
winget install Anthropic.ClaudeCodeEin genereller Hinweis: Wenn du Commands aus dem Internet ins Terminal kopierst, solltest du kurz nachschauen, ob die Quelle vertrauenswürdig ist. Den Installer findest du auch auf der offiziellen Claude Code Seite, falls du das lieber selbst prüfen möchtest.
Danach das Terminal einmal komplett schließen und neu öffnen, damit der Pfad zum Programm bekannt ist.
Schritt 2: Installation prüfen
Einfacher Test: Version abfragen.
claude --version
# Beispiel-Ausgabe: 2.1.263 (Claude Code)
claude doctorclaude doctor prüft Installation und Einstellungen, ohne eine Sitzung zu starten. Beim ersten Start von claude öffnet sich der Browser für die Anmeldung mit deinem Konto. Wenn das funktioniert, bist du mit dem Claude-Setup eigentlich schon fertig. Mehr war das gar nicht.
Schritt 3: MCP-Server in Home Assistant hinzufügen
Die Integration ist eingebaut, aber nicht vorinstalliert. Geh zu Einstellungen, dann Geräte und Dienste, direkt über homeassistant.local:8123/config/integrations. Klick auf Integration hinzufügen, such nach Model Context Protocol Server und bestätige. Es gibt nichts weiter zu konfigurieren. Danach liegt der Server unter /api/mcp bereit.
Wenn du möchtest, kannst du unter den Systemoptionen der Integration noch zwei Schalter anpassen: ob neu hinzugefügte Entitäten automatisch verfügbar werden sollen und ob Claude Zustandsänderungen aktiv abfragen darf. Das kannst du dir aussuchen, ist aber für den Start nicht entscheidend.
Schritt 4: Entitäten für Assist verfügbar machen
Das ist der Schritt, an dem die meisten hängenbleiben. Claude sieht ausschließlich Entitäten, die als verfügbar markiert sind. Alles andere existiert für die Verbindung nicht, egal welchen Token du verwendest.
Die Einstellung findest du unter Einstellungen, Sprachassistenten, Reiter Verfügbarkeit, direkt über homeassistant.local:8123/config/voice-assistants/expose. Die Liste zeigt jede Entität mit Name, Bereich und den Assistenten, für die sie freigegeben ist.
Auf dem Reiter Assistenten gibt es zusätzlich den Schalter Neue Entitäten verfügbar machen. Steht er an, wandert alles Neue automatisch in die Liste, ausgenommen Geräte, die Home Assistant als Sicherheitsgeräte einstuft.
Meine Empfehlung: Fang mit einem Raum an. Türschlösser, Alarmanlage und Garagentor gehören nicht in die erste Auswahl. Der MCP-Server behandelt ein Schloss wie jedes andere Gerät, Einschalten heißt dort abschließen und Ausschalten aufschließen. Das ist einfach nichts, wo man KI-Befehle durchrouten möchte, bevor man das Setup wirklich kennt.
Der angezeigte Name ist übrigens der Name, den Claude versteht. Sprechende Gerätenamen zahlen sich hier doppelt aus.
Schritt 5: Long-Lived Access Token erstellen
Unten links auf den eigenen Benutzernamen klicken, dann auf den Reiter Sicherheit und ganz nach unten scrollen. Rechts unten sitzt die Schaltfläche Token erstellen. Der Dialog fragt nur nach einem Namen, zum Beispiel claude-code.
Der Token erscheint genau einmal. Sofort in den Passwortmanager kopieren, bevor das Fenster zugeht. Er ist zehn Jahre gültig und hat die vollen Rechte deines Benutzerkontos. Wenn du den weitergibst und jemand deine Home-Assistant-Adresse kennt, kommt er damit überall rein. Also sorgsam damit umgehen.
Schritt 6: Home Assistant in Claude Code einbinden
Jetzt kommt das eigentliche Herzstück. Ein einziger Befehl:
claude mcp add --transport http home-assistant \
http://homeassistant.local:8123/api/mcp \
--header "Authorization: Bearer DEIN_TOKEN"Statt homeassistant.local funktioniert auch die IP, etwa http://192.168.1.50:8123/api/mcp. Der Pfad /api/mcp bleibt immer gleich.
Ohne weitere Angabe gilt die Verbindung nur im aktuellen Ordner. Mit --scope user steht sie in jedem Projekt zur Verfügung, was ich eigentlich praktischer finde.
Schritt 7: Verbindung prüfen
claude mcp list
# home-assistant: http://homeassistant.local:8123/api/mcp (HTTP) - ✔ ConnectedSteht dort Connected, ist das Setup fertig. Kein Neustart, keine Konfigurationsdatei, kein zweites Programm. Das war alles.
Schritt 8: Die ersten Befehle
claude im Terminal starten und dann einfach in normalen Sätzen arbeiten:
> Welche Geräte im Wohnzimmer sind gerade an?
> Wie warm ist es im Schlafzimmer und wieviel Strom zieht das Haus?
> Mach das Licht im Wohnzimmer aus und fahr die Jalousien auf halb.Mit /mcp siehst du in der Sitzung die verbundenen Server und ihre Werkzeuge. Beim ersten Zugriff fragt Claude Code um Erlaubnis. Solange du dich einarbeitest, ist die Bestätigung pro Werkzeug der sichere Weg. Ich würde da nicht einfach alles durchwinken, bevor man weiß was passiert.
Das Licht im Wohnzimmer per Sprachbefehl steuern ist natürlich nur ein Spielzeug-Beispiel. Interessant wird es, wenn du sagst, prüf meine Konfiguration auf veraltete Einträge, oder erkläre mir, warum diese Automation nicht auslöst. Da merkt man wirklich, was das Setup kann.
Schritt 9: Die Grenzen kennen
Der offizielle MCP-Server liefert 27 Werkzeuge: Licht, Rolladen, Klima, Lüfter, Staubsauger, Medienwiedergabe, To-do-Listen, Durchsagen und aktuelle Zustände. Er kann steuern und abfragen.
Was er nicht kann: Automationen anlegen, Skripte ändern, Dashboards bauen, YAML schreiben. Wer danach fragt, bekommt eine Erklärung statt einer Umsetzung. Das ist kein Fehler in der Einrichtung, das ist einfach so gewollt.
Schritt 10: Automationen trotzdem schreiben lassen
Claude Code hat neben MCP ein Terminal und Dateizugriff. Damit erreicht es die komplette REST-Schnittstelle von Home Assistant, ganz ohne MCP-Werkzeug. Das ist eigentlich ziemlich praktisch.
1# Alle Zustände lesen
2curl -s -H "Authorization: Bearer DEIN_TOKEN" \
3 http://homeassistant.local:8123/api/states
4
5# Eine Vorlage auswerten, praktisch für Diagnosen
6curl -s -X POST -H "Authorization: Bearer DEIN_TOKEN" \
7 -H "Content-Type: application/json" \
8 -d '{"template":"{{ states.automation | list | count }}"}' \
9 http://homeassistant.local:8123/api/template
10
11# Eine Automation anlegen oder überschreiben
12curl -s -X POST -H "Authorization: Bearer DEIN_TOKEN" \
13 -H "Content-Type: application/json" \
14 -d @automation.json \
15 http://homeassistant.local:8123/api/config/automation/config/1725800000000Die Zahl am Ende ist die ID der Automation. Eine neue ID legt eine neue Automation an, eine bestehende überschreibt sie. Danach die Automationen neu laden, über die Oberfläche oder den Dienst automation.reload.
In der Praxis fragst du dann so:
> Schau dir meine Automation für die Bürobeleuchtung an und erklär mir,
warum sie morgens nicht auslöst.
> Bau mir eine Automation, die die Jalousien schließt, wenn die
Innentemperatur über 24 Grad steigt.Schritt 11: Ausbaustufe ha-mcp
Wer lieber fertige Werkzeuge statt roher API-Aufrufe hat, kann den Community-Server ha-mcp ausprobieren. Er bringt 87 Werkzeuge mit und beherrscht zusätzlich Automationen, Dashboards, Helfer, Backups, HACS, Kamerabilder und Ablaufprotokolle. Lizenz MIT, rund 4.700 Sterne auf GitHub.
Installationswege gibt es ein paar:
- Als Custom Component über HACS, das ist der empfohlene Weg. Der Server läuft dann direkt in Home Assistant selbst.
- Als Add-on bei Home Assistant OS.
- Als Docker-Image
ghcr.io/homeassistant-ai/ha-mcp. - Direkt mit
uvx ha-mcp@latest.
Der Einrichtungsassistent erzeugt die passende Konfiguration für dich.
Allerdings: Mehr Werkzeuge sind nicht automatisch besser. 87 Beschreibungen gehen bei jeder Anfrage mit und kosten Kontext. Ich würde mit dem offiziellen Server anfangen und wechseln, wenn dir wirklich etwas fehlt.
Schritt 12: Einen eigenen Skill für dein Setup
Skills sind Anleitungen, die Claude Code sich selbst dazuholt. Ein Skill ist ein Ordner mit einer einzigen Datei. Das Ganze ist wahnsinnig praktisch, weil du dann nicht bei jeder Sitzung wieder erklären musst, wie dein Setup aussieht.
mkdir -p ~/.claude/skills/mein-smarthomeDann die Datei ~/.claude/skills/mein-smarthome/SKILL.md anlegen:
1---
2name: mein-smarthome
3description: Wissen über meine Home-Assistant-Instanz. Nutzen bei allen Fragen
4 zu meinen Geräten, Räumen und Automationen.
5---
6
7# Meine Instanz
8
9Adresse: http://homeassistant.local:8123
10Token: liegt in der Umgebungsvariable HA_TOKEN
11
12## Räume und Namensschema
13
14Lampen heißen "Licht <Raum>", Rolladen heißen "Jalousie <Raum>".
15Der Raum Büro heißt in Entity-IDs "buro", ohne Umlaut.
16
17## Regeln
18
19Automationen nie ohne Rückfrage überschreiben.
20Türschloss und Alarmanlage sind tabu.Ab dem nächsten Start kennt Claude diese Angaben. Der letzte Abschnitt ist der wichtigste: Regeln, die einmal aufgeschrieben sind, gelten in jeder Sitzung. Das spart unheimlich viele Token und ganz viel Erklärungsarbeit.
Wer weitergehen will: Plugins bündeln Skills, Unteragenten und Automatiken zu einem Paket, das über /plugin installiert wird. Hooks führen vor oder nach bestimmten Aktionen etwas aus, etwa eine Sicherung der Konfiguration, bevor eine Datei geändert wird. Mehr dazu findest du in der Skills-Dokumentation.
Tipps und Troubleshooting
command not found: claude
Das Terminal kennt den neuen Pfad noch nicht. Schließen und neu öffnen. Hilft das nicht, prüfen, ob ~/.local/bin im PATH steht.
In claude mcp list steht Failed statt Connected
Adresse falsch, Home Assistant nicht erreichbar oder Token abgelehnt. Die URL einfach mal im Browser aufrufen. Antwortet sie, den Eintrag mit claude mcp remove home-assistant löschen und mit frisch kopiertem Token neu anlegen.
Claude findet ein Gerät nicht Die Entität ist nicht als verfügbar markiert. Unter Sprachassistenten im Reiter Verfügbarkeit nachtragen, die Änderung wirkt sofort, ohne Neustart.
Claude kann keine Automation anlegen Kein Fehler in der Einrichtung, dem offiziellen Server fehlt das Werkzeug dafür. Den Weg über die REST-Schnittstelle aus Schritt 10 nehmen oder ha-mcp installieren.
Sicherheit
claude mcp get home-assistant zeigt den Token im Klartext. Beim Bildschirmteilen und in Screenshots aufpassen. Verlorene Tokens löschst du im Profil unter Sicherheit über das Papierkorb-Symbol, die Verbindung entfernst du mit claude mcp remove home-assistant.
Datenschutz Das ist ein Punkt, den ich wichtig finde und den man klar kommunizieren sollte: Gerätenamen und Zustände, die Claude für eine Antwort braucht, verlassen dein Netz und gehen an Anthropic. Auch wenn sich das Setup lokal anfühlt, ist es das nicht vollständig. Wer das nicht möchte, ist mit einem lokalen Modell besser bedient. Ich habe dazu auch schon ein Video gemacht, falls dich das interessiert.
Nutzt du Claude Code schon für andere Dinge, oder ist Home Assistant der erste Use Case für dich? Schreib es gerne in die Kommentare.
