Home Assistant trifft Claude Code: Smarthome-Steuerung via MCP

Ich rede schon länger mit meinem Smarthome. Nicht auf diese klobige “Hey Alexa, schalte das Licht ein”-Art, sondern richtig - mit Kontext, mit Folgefragen, mit echten Analysen. Möglich macht das der Model Context Protocol (MCP) Server für Home Assistant, der den KI-Assistenten direkt mit der HA-API verbindet. Was dabei herauskommt, wenn man Claude Code in ein neues Projekt startet und einfach drauflosfrägt - das zeige ich in diesem Artikel.

Was ist MCP überhaupt?

Das Model Context Protocol ist ein offener Standard, den Anthropic 2024 veröffentlicht hat. Die Idee dahinter ist simpel: KI-Modelle sollen nicht nur Text verarbeiten, sondern aktiv auf externe Systeme zugreifen können - Datenbanken, APIs, Dateisysteme, und eben auch Home Assistant. Statt einen starren Chatbot anzubinden, bekommt Claude über MCP ein echtes Werkzeugset: Entities abfragen, Services aufrufen, Dashboards erstellen, Automationen anlegen.

Der ha-mcp Server ist die Community-Implementierung davon für Home Assistant. Mit aktuell über 95 Tools deckt er alles ab, von einfachen Zustandsabfragen bis hin zu Backup-Operationen. Und er hat zuletzt erheblich an Fahrt aufgenommen - über 1.000 GitHub-Stars in kurzer Zeit sprechen für sich.

Architektur: stdio vs. HTTP

Bevor wir loslegen, kurz zur wichtigsten Designentscheidung: Wie verbindet sich Claude Code mit ha-mcp?

Es gibt zwei Transport-Arten:

stdio (Standard I/O) ist der einfachste Weg. Claude Code startet ha-mcp als Subprozess direkt auf demselben Rechner und kommuniziert über stdin/stdout. Kein offener Port, keine Netzwerkkonfiguration - ha-mcp läuft nur, wenn Claude Code läuft. Ideal wenn alles auf einem einzigen Rechner läuft.

HTTP ist der persistente Ansatz. ha-mcp läuft als dauerhafter HTTP-Server, Claude Code verbindet sich per URL. Das macht Sinn, wenn HA auf einem separaten Host läuft - zum Beispiel als Home Assistant OS auf einem Raspberry Pi oder Mini-PC - und man von einem anderen Gerät im Netz darauf zugreift.

Mein Setup ist genau dieser Fall: HA läuft auf einem eigenen Host im lokalen Netz, Claude Code auf meinem Windows-PC. Der ha-mcp Server läuft als Supervisor Add-on direkt auf dem HA-Host und ist von dort per HTTP im LAN erreichbar. Claude Code auf Windows verbindet sich per URL zum Add-on - kein lokaler uvx-Prozess, kein dauerhaft offenes Terminal nötig.

Claude Code (Windows)
       ↓  HTTP (lokales Netz)
  ha-mcp Add-on (Supervisor, HA-Host)
       ↓  intern
  Home Assistant Core

Das ist die eleganteste Lösung für dieses Setup: der Server startet automatisch mit HA, läuft im Hintergrund, und ist für jeden Client im Netz verfügbar.

Setup: ha-mcp installieren und mit Claude Code verbinden

Das Setup teilt sich in zwei unabhängige Teile: den Server (ha-mcp Add-on auf dem HA-Host) und den Client (Claude Code Konfiguration auf dem Windows-PC).

Server-Seite: HA Add-on installieren

Das ha-mcp Add-on lässt sich direkt über den HA Supervisor installieren. Im Setup Wizard auf der Projektseite unter Claude Code → Local Network → HA OS findet sich die fertige Anleitung, hier der Ablauf in Kurzform:

In Home Assistant unter Einstellungen → Add-ons → Add-on Store das Repository https://github.com/homeassistant-ai/ha-mcp hinzufügen. Danach erscheint “Home Assistant MCP Server” in der Liste - installieren, dann im Add-on unter Konfiguration den Port (Standard: 8808) und optional die erlaubten Hosts eintragen.

Bevor das Add-on gestartet wird, braucht es einen Long-Lived Access Token: In HA unter Profil → Sicherheit → Long-Lived Access Tokens → Token erstellen. Den Token sofort kopieren - er wird nur einmal angezeigt. Den Token in der Add-on-Konfiguration unter HA_TOKEN eintragen, dann Add-on starten.

Das Add-on läuft jetzt unter http://<HA-IP>:8808 und ist im lokalen Netz erreichbar.

Client-Seite: Claude Code unter Windows konfigurieren

Für Windows muss uv installiert sein - das ist das Python-Package-Tool, das ha-mcp im Hintergrund für den lokalen Transport verwendet. Installation per winget:

winget install astral-sh.uv

Jetzt muss Claude Code wissen, wo der MCP-Server läuft. Hier gibt es zwei Varianten mit einem wichtigen Unterschied:

User-weit (alle Projekte): claude mcp add ohne weiteres Flag legt den Server in ~/.claude.json ab - er steht dann in jeder Claude Code Session zur Verfügung, egal in welchem Verzeichnis man startet.

claude mcp add ha-mcp --transport http http://192.168.1.x:8808/mcp

Projekt-spezifisch (empfohlen): Wer einen sauberen, isolierten Setup bevorzugt, legt eine .mcp.json direkt im Projektverzeichnis an. Claude Code liest diese Datei automatisch beim Start, wenn man sich in diesem Verzeichnis befindet - und nur dort.

{
  "mcpServers": {
    "ha-mcp": {
      "type": "http",
      "url": "http://192.168.1.x:8808/mcp"
    }
  }
}

Die .mcp.json-Variante lässt sich ins Git-Repository committen, sodass der MCP-Setup reproduzierbar bleibt. Der Token steckt ja im Add-on auf dem HA-Host, nicht in dieser Datei - also nichts Sensitives dabei.

Ob alles geklappt hat, zeigt /mcp innerhalb einer Claude Code Session:

> /mcp
⎿ MCP Server Status
⎿
⎿ • ha-mcp: connected (97 tools)

97 Tools - da hat man was zu arbeiten.

Ein neues Projekt from scratch starten

Ich starte ein frisches Claude Code Projekt mit einer sauberen, projekt-lokalen MCP-Konfiguration - so ist alles selbsterklärend und nichts hängt von globalen Settings ab.

Zuerst das Projektverzeichnis anlegen und die .mcp.json darin ablegen:

mkdir ha-assistant
cd ha-assistant

{
  "mcpServers": {
    "ha-mcp": {
      "type": "http",
      "url": "http://192.168.1.x:8808/mcp"
    }
  }
}

Dann Claude Code starten:

claude

Beim ersten Start fragt Claude Code nach Bestätigung für die projekt-lokale .mcp.json - eine Sicherheitsmaßnahme, damit man nicht versehentlich fremde MCP-Configs aus geclonten Repos akzeptiert. Einmal bestätigen, fertig. Danach zeigt /mcp den Status:

> /mcp
⎿ MCP Server Status
⎿
⎿ • ha-mcp: connected (97 tools)

97 Tools - da hat man was zu arbeiten. Wer dieses Verzeichnis später clont und claude startet, hat denselben Setup automatisch. Kein “funktioniert bei mir”-Problem.

Abfrage: Der produktivste Tag meiner Balkon-PV

Ich betreibe eine Balkon-PV-Anlage mit vier Panels, angebunden über einen Hoymiles Mikroinverter und die OpenDTU-Integration in Home Assistant. Die Entities, die mich interessieren:

• sensor.hoymiles_yieldday - Tagesproduktion gesamt (in Wh)
• sensor.hoymiles_yieldtotal - Gesamtproduktion seit Inbetriebnahme (in kWh)
• sensor.hoymiles_ch1_yieldday bis sensor.hoymiles_ch4_yieldday - Tagesproduktion pro Panel

Die erste Frage:

Ich möchte wissen, welcher Tag bisher die höchste Produktion meiner 
Balkon-PV hatte. Schau dir die historischen Daten von 
sensor.hoymiles_yieldday an und finde den produktivsten Tag sowie 
die Gesamtproduktion an diesem Tag aufgeteilt auf die vier Panels 
(sensor.hoymiles_ch1_yieldday bis sensor.hoymiles_ch4_yieldday).

Claude Code ruft ha_get_statistics auf - man sieht live, wie die Tool-Calls in der Session erscheinen. Die Antwort kommt nach ein paar Sekunden:

Der produktivste Tag war der 20. Juni 2025 mit einer 
Gesamtproduktion von 11,13 kWh.

Aufschlüsselung nach Panels:
┌────────┬───────────────────────┐
│ Panel  │      Produktion       │
├────────┼───────────────────────┤
│ CH1    │ 2.722 Wh (2,72 kWh)   │
├────────┼───────────────────────┤
│ CH2    │ 2.495 Wh (2,50 kWh)   │
├────────┼───────────────────────┤
│ CH3    │ 3.011 Wh (3,01 kWh)   │
├────────┼───────────────────────┤
│ CH4    │ 2.906 Wh (2,91 kWh)   │
├────────┼───────────────────────┤
│ Gesamt │ 11.134 Wh (11,13 kWh) │
└────────┴───────────────────────┘

CH3 war das stärkste Panel an diesem Tag, CH2 das schwächste.
Die Verteilung ist aber insgesamt sehr gleichmäßig.

Top 5 produktivste Tage (zum Vergleich):
┌────────────┬────────────┐
│   Datum    │ Produktion │
├────────────┼────────────┤
│ 20.06.2025 │ 11,13 kWh  │
├────────────┼────────────┤
│ 12.06.2025 │ 10,91 kWh  │
├────────────┼────────────┤
│ 13.06.2025 │ 10,91 kWh  │
├────────────┼────────────┤
│ 30.06.2025 │ 10,89 kWh  │
├────────────┼────────────┤
│ 11.06.2025 │ 10,89 kWh  │
└────────────┴────────────┘

Der Juni 2025 war offensichtlich ein sehr sonniger Monat —
alle Top-5-Tage liegen darin.

Zwei Dinge fallen sofort auf: 11 kWh an einem Tag ist für ein Balkonkraftwerk wirklich beachtlich - zum Vergleich, ein durchschnittlicher Haushalt verbraucht etwa 8-10 kWh pro Tag. Und die Top-5-Liste zeigt einen klaren Cluster: alles Juni 2025. Claude hat das selbst kommentiert, ohne dass ich danach gefragt hätte.

Die Panel-Verteilung ist mit 2,5 bis 3,0 kWh pro Einheit sehr gleichmäßig - kein Panel fällt stark ab, was auf eine gute Installation ohne nennenswerte Verschattung hindeutet.

Was hier konzeptuell wichtig ist: Ich habe keine SQL-Abfrage geschrieben, keine InfluxDB-Query formuliert, keine Python-Auswertung gebaut. Ich habe auf Deutsch gefragt, und Claude Code hat die richtigen MCP-Tools in der richtigen Reihenfolge aufgerufen und das Ergebnis direkt sauber aufbereitet.

Das ist der eigentliche Mehrwert von MCP: nicht dass Claude etwas kann, was vorher unmöglich war - sondern dass die Hürde zum Abfragen von Daten auf null sinkt.

Dashboard mit Bubble Cards erstellen

Bubble Cards ist eine populäre Custom-Card für Home Assistant Lovelace, die ein modernes, abgerundetes UI-Design bringt. Vorausgesetzt, Bubble Card ist über HACS installiert, kann ha-mcp das Dashboard direkt über die HA-API anlegen.

Erstelle ein neues Home Assistant Dashboard mit dem Titel 
"Balkon PV" und füge folgende Bubble Cards hinzu:

1. Eine Bubble Card mit dem aktuellen Tagesertrag 
   (sensor.hoymiles_yieldday)
2. Eine Bubble Card mit dem Gesamtertrag 
   (sensor.hoymiles_yieldtotal)
3. Vier Bubble Cards für die einzelnen Panels 
   (sensor.hoymiles_ch1_yieldday bis ch4_yieldday), 
   jeweils mit passendem Icon (mdi:solar-panel)

Verwende für alle Cards tap_action: more-info und setze 
das Theme auf dark falls verfügbar.

Claude Code ruft zuerst ha_get_dashboard_guide und ha_get_card_documentation auf, um die aktuelle Dashboard-Syntax zu kennen - inklusive der Bubble Card Version, die in HA installiert ist. Dann generiert es das YAML und übergibt es per ha_config_set_dashboard direkt an Home Assistant. Die Bestätigung kommt sofort:

Das Dashboard wurde erfolgreich erstellt. Hier die Zusammenfassung:

Dashboard "Balkon PV" ist unter /balkon-pv erreichbar und in der 
Sidebar sichtbar.

Konfiguration:
Abschnitt "Gesamtübersicht":
- sensor.hoymiles_yieldday  — Tagesertrag  (mdi:solar-power-variant)
- sensor.hoymiles_yieldtotal — Gesamtertrag (mdi:counter)

Abschnitt "Einzelne Panels":
- sensor.hoymiles_ch1_yieldday — Panel 1 (mdi:solar-panel)
- sensor.hoymiles_ch2_yieldday — Panel 2 (mdi:solar-panel)
- sensor.hoymiles_ch3_yieldday — Panel 3 (mdi:solar-panel)
- sensor.hoymiles_ch4_yieldday — Panel 4 (mdi:solar-panel)

Alle Cards haben tap_action: more-info und das Theme ist auf dark 
gesetzt. Das Layout nutzt den modernen sections-Typ mit 
Bubble Card v3.1.4.

Das Dashboard ist sofort in der HA-Sidebar sichtbar - kein manuelles YAML-Editieren, kein Neuladen, kein Navigieren durch die Lovelace-Oberfläche. Ein Prompt, fertig.

Was hier auffällt: Claude hat nicht einfach blindes YAML generiert, sondern die installierte Bubble Card Version (3.1.4) abgerufen und den modernen sections-Layout-Typ verwendet, der in neueren Versionen empfohlen wird. Genau dafür ist der ha_get_card_documentation Tool-Call da.

Iteration: Das Unavailable-Problem

Nach dem ersten Blick auf das Dashboard fällt auf: alle sechs Cards zeigen “Unavailable”. Layout und Icons stimmen, aber keine Werte. Die naheliegende Vermutung - falsche Entity-IDs - lässt sich sofort prüfen:

Die Entities im Dashboard zeigen "Unavailable". Suche nach allen 
Entities die mit "hoymiles" zusammenhängen und zeig mir die 
genauen Entity-IDs.

Claude Code ruft ha_search_entities auf und liefert nicht nur die Entity-Liste, sondern findet dabei zwei aufschlussreiche Sensoren:

┌──────────────────────────────────┬───────┐
│            Entity ID             │ State │
├──────────────────────────────────┼───────┤
│ binary_sensor.hoymiles_reachable │ off   │
├──────────────────────────────────┼───────┤
│ binary_sensor.hoymiles_producing │ off   │
└──────────────────────────────────┴───────┘

Diagnose: Der Inverter ist aktuell nicht erreichbar (reachable = off).
Das ist der Grund für "Unavailable" — nicht falsche Entity-IDs.
Hoymiles-Wechselrichter trennen sich nach Sonnenuntergang vom Netzwerk.
Die historischen Statistiken funktionieren weiterhin, weil die Daten
bereits in der HA-Datenbank gespeichert sind.

Die Entity-IDs sind korrekt - es ist schlicht Nacht. Der Wechselrichter schläft. Aber damit ist das Folgeproblem klar: tagsüber zeigt das Dashboard Live-Werte, nachts nichts. Die nächste Frage:

Die Entities sind nachts unavailable weil der Wechselrichter offline ist.
Kannst du das so lösen, dass die Cards den letzten bekannten Wert 
anzeigen statt "Unavailable"? Ich möchte auch nachts sehen was heute 
produziert wurde.

Claude denkt sich eine saubere Lösung aus - keine Workarounds, sondern Home Assistant-native Mechanismen:

Alles eingerichtet. Hier die Zusammenfassung:

6 input_number-Helfer (speichern den letzten Wert dauerhaft):
- input_number.hoymiles_yieldday_last_known
- input_number.hoymiles_yieldtotal_last_known
- input_number.hoymiles_ch1_yieldday_last_known bis ch4

Automation "hoymiles_letzten_bekannten_wert_speichern":
- Läuft im parallel-Modus für alle 6 Sensoren gleichzeitig
- Aktualisiert den jeweiligen Helfer sobald ein Sensor einen
  gültigen Wert liefert (nicht unavailable/unknown)
- Ignoriert unavailable-Übergänge — der Helfer behält den letzten Wert

Dashboard zeigt jetzt die input_number-Helfer statt der direkten
Sensor-Entities.

Das Verhalten danach:

┌────────────────────────────┬──────────────────────────────────────────┐
│         Situation          │                 Anzeige                  │
├────────────────────────────┼──────────────────────────────────────────┤
│ Inverter online (tagsüber) │ Live-Wert, wird laufend aktualisiert     │
├────────────────────────────┼──────────────────────────────────────────┤
│ Inverter offline (nachts)  │ Letzter Wert vor dem Abschalten          │
├────────────────────────────┼──────────────────────────────────────────┤
│ HA-Neustart                │ Wert bleibt erhalten (input_number ist   │
│                            │ persistent)                              │
└────────────────────────────┴──────────────────────────────────────────┘

Was hier passiert ist, ist mehr als ein Dashboard-Fix: Claude hat in einem einzigen Gespräch das Problem selbst diagnostiziert, sechs Helfer-Entities angelegt, eine Automation mit parallelem Modus geschrieben und das Dashboard aktualisiert. Alles ohne YAML-Editor, ohne den Automations-Assistenten, ohne manuelles Helfer-Anlegen über die UI.

Das ist der eigentliche Charakter dieser Kombination: kein einzelnes Tool ist revolutionär, aber das Gespräch als Arbeitseinheit - Problem erkennen, lösen, verfeinern, alles im Kontext - das ist neu.

Bonus: Dashboard-Redesign im Plan Mode

Bubble Cards funktionieren, aber optisch bin ich nicht restlos zufrieden. Also: nochmal nachfragen.

okay das ist schon seeeeehr cool. Ich bin nicht glücklich mit der Optik 
kannst du das alles optisch ansprechender machen? Es muss nicht mit 
Bubble Cards gelöst sein.

Statt sofort loszuschreiben aktiviert Claude Code hier den Plan Mode - und das ist einen eigenen Screenshot wert. Claude inventarisiert zuerst die verfügbaren Custom Cards in der HA-Instanz (Mushroom v5.0.12, layout-card v2.4.7, native statistics-graph), zieht die echten aktuellen Datenwerte als Design-Referenz heran und strukturiert das Dashboard in drei Sections neu:

Der Plan zeigt eine durchdachte Struktur - Tagesübersicht mit zwei Mushroom Template Cards nebeneinander, ein 14-Tage Statistik-Balkendiagramm für den Produktionsverlauf, und die vier Panel-Cards im 2×2-Grid. Bonus: ein Badge auf der Tagesertrag-Card der subtil auf den Offline-Status des Inverters hinweist, wenn binary_sensor.hoymiles_reachable = off ist. Das Problem von vorhin, elegant als Feature verpackt.

Nach Bestätigung des Plans setzt Claude das YAML direkt um:

Ideen: Was man noch damit machen kann

Das PV-Beispiel ist nur der Einstieg. Ha-mcp hat 97 Tools - hier sind ein paar Use Cases, die sich damit sofort umsetzen lassen:

Automationen per Sprache erstellen. “Erstelle eine Automation, die mich benachrichtigt, wenn die Balkon-PV mehr als 100W produziert und gleichzeitig der Geschirrspüler aus ist - dann soll er automatisch starten.” Claude kennt die HA-Automations-Syntax und schreibt das direkt in die Config.

Troubleshooting. “Meine Bewegungsmelder-Automation für den Flur löst nachts nicht aus. Schau dir die letzten Automations-Traces an und sag mir warum.” Claude ruft ha_get_automation_traces auf und analysiert die Trace-Logs - das spart oft 20 Minuten manuelles Debugging.

Energieplanung. “Welche Geräte verbrauchen tagsüber am meisten Strom? Gibt es Muster, wann ich meine PV-Produktion besser nutzen könnte?” Mit Zugriff auf History und Statistics kann Claude echte Optimierungsvorschläge machen.

Geräte umbenennen und organisieren. Wenn nach einer langen Installationsphase 40 Entities mit kryptischen Namen in HA schlummern, ist “Benenne alle Entities, die mit ‘zigbee2mqtt_’ beginnen, in lesbare Namen um” eine deutlich angenehmere Arbeit als das manuelle Durchklicken.

Scripts für Routinen. “Erstelle ein Script ‘Feierabend’, das: alle Lichter im Büro ausschaltet, die Heizung auf 21°C setzt, die Rollos hochfährt und mir eine Benachrichtigung schickt.” Ein Prompt, fertig.

Dashboard-Iteration. Dashboards in HA sind traditionell zeitaufwändig. Mit Claude als YAML-Generator wird das zu einem Gespräch: erst eine Grundstruktur, dann verfeinern, dann Cards hinzufügen - und alles landet direkt in HA ohne manuelles Editieren.

Fazit

Der ha-mcp Server ist eines der nützlichsten Dinge, die ich in letzter Zeit in mein Home-Assistant-Setup integriert habe. Nicht weil er Dinge möglich macht, die vorher unmöglich waren - HA konnte immer schon alles, wofür ich Claude jetzt benutze. Aber die Reibung ist weg. Historische Daten analysieren, Dashboards bauen, Automationen schreiben: alles passiert jetzt in einem natürlichen Gesprächsfluss statt in YAML-Editoren und Dokumentationsseiten.

Das stdio vs. HTTP-Setup ist in fünf Minuten erledigt, die Hoymiles-Abfragen haben auf Anhieb funktioniert, und das Dashboard war in einem einzigen Prompt fertig. Für alle, die Home Assistant ernsthaft nutzen und Claude Code sowieso im Einsatz haben, ist ha-mcp ein No-Brainer.

---

Alle verwendeten Entity-Namen basieren auf der OpenDTU-Integration für Hoymiles-Wechselrichter. Die genauen Namen können je nach Integrationsversion leicht abweichen.