hass-mcp – HiTech-Lab-Edition

Gepflegt und optimiert von HiTech Lab Quelle: https://github.com/voska/hass-mcp

Hass-MCP

Ein Model Context Protocol (MCP)-Server für die Home-Assistant-Integration mit Claude und anderen LLMs.

Überblick

Hass-MCP ermöglicht es KI-Assistenten wie Claude, direkt mit deiner Home-Assistant-Instanz zu interagieren. Sie können damit:

• Den Zustand von Geräten und Sensoren abfragen

• Lichter, Schalter und andere Entitäten steuern

• Zusammenfassungen deines Smart Homes abrufen

• Automatisierungen und Entitäten debuggen

• Nach bestimmten Entitäten suchen

• Geführte Gespräche für häufige Aufgaben erstellen

Related MCP server: Hass-MCP

Screenshots

Funktionen

• Entitätsverwaltung: Zustände abrufen, Geräte steuern und nach Entitäten suchen

• Domain-Zusammenfassungen: Hochrangige Informationen über Entitätstypen abrufen

• Automatisierungsunterstützung: Automatisierungen auflisten und steuern

• Geführte Gespräche: Prompts für häufige Aufgaben wie das Erstellen von Automatisierungen verwenden

• Intelligente Suche: Entitäten nach Name, Typ oder Zustand finden

• Live-Dashboard-Bearbeitung: Lovelace-Dashboards (Karten und Ansichten) über die WebSocket-API von Home Assistant lesen und bearbeiten – Änderungen erscheinen sofort in geöffneten Browsern, mit automatischen Backups und einer Dry-Run-Vorschau

• Token-Effizienz: Schlanke JSON-Antworten, um den Token-Verbrauch zu minimieren

Installation

Voraussetzungen

• Home-Assistant-Instanz mit Long-Lived Access Token

• Eine der folgenden Optionen:

  • Docker (empfohlen)

  • Python 3.13+ und uv

Einrichtung mit Claude Desktop

Docker-Installation (empfohlen)

1. Docker-Image abrufen:

   docker pull voska/hass-mcp:latest

2. Den MCP-Server zu Claude Desktop hinzufügen:

   a. Claude Desktop öffnen und zu den Einstellungen gehen b. Zu Entwickler > Konfiguration bearbeiten navigieren c. Die folgende Konfiguration zu deiner claude_desktop_config.json-Datei hinzufügen:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e",
           "HA_URL",
           "-e",
           "HA_TOKEN",
           "voska/hass-mcp"
         ],
         "env": {
           "HA_URL": "http://homeassistant.local:8123",
           "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
         }
       }
     }
   }

   d. YOUR_LONG_LIVED_TOKEN durch dein tatsächliches Home-Assistant-Long-Lived-Access-Token ersetzen e. Die HA_URL aktualisieren:

   • Wenn Home Assistant auf demselben Rechner läuft: http://host.docker.internal:8123 verwenden (Docker Desktop unter Mac/Windows)

   • Wenn Home Assistant auf einem anderen Rechner läuft: die tatsächliche IP-Adresse oder den Hostnamen verwenden

   f. Die Datei speichern und Claude Desktop neu starten

3. Das Tool „Hass-MCP" sollte nun in deinem Claude-Desktop-Tools-Menü erscheinen

Hinweis: Wenn du Home Assistant in Docker auf demselben Rechner betreibst, musst du möglicherweise --network host zu den Docker-Argumenten hinzufügen, damit der Container auf Home Assistant zugreifen kann. Alternativ kannst du die IP-Adresse deines Rechners anstelle von host.docker.internal verwenden.

uv/uvx

1. Installiere uv auf deinem System.

2. Den MCP-Server zu Claude Desktop hinzufügen:

   a. Claude Desktop öffnen und zu den Einstellungen gehen b. Zu Entwickler > MCP-Konfiguration bearbeiten navigieren c. Die folgende Konfiguration zu deiner claude_desktop_config.json-Datei hinzufügen:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "uvx",
         "args": ["hass-mcp"],
         "env": {
           "HA_URL": "http://homeassistant.local:8123",
           "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
         }
       }
     }
   }

   d. YOUR_LONG_LIVED_TOKEN durch dein tatsächliches Home-Assistant-Long-Lived-Access-Token ersetzen e. Die HA_URL aktualisieren:

   • Wenn Home Assistant auf demselben Rechner läuft: http://host.docker.internal:8123 verwenden (Docker Desktop unter Mac/Windows)

   • Wenn Home Assistant auf einem anderen Rechner läuft: die tatsächliche IP-Adresse oder den Hostnamen verwenden

   f. Die Datei speichern und Claude Desktop neu starten

3. Das Tool „Hass-MCP" sollte jetzt in deinem Claude-Desktop-Tools-Menü erscheinen

Andere MCP-Clients

Cursor

1. Gehe zu Cursor-Einstellungen > MCP > Neuen MCP-Server hinzufügen

2. Fülle das Formular aus:

   • Name: Hass-MCP

   • Typ: command

   • Befehl:

     docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp

   • Ersetze YOUR_LONG_LIVED_TOKEN durch dein tatsächliches Home-Assistant-Token

   • Aktualisiere die HA_URL, sodass sie der Adresse deiner Home-Assistant-Instanz entspricht

3. Klicke auf „Hinzufügen", um zu speichern

Claude Code (CLI)

Für die Verwendung mit Claude Code CLI kannst du den MCP-Server direkt über den Befehl mcp add hinzufügen:

Mit Docker (empfohlen):

claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

Ersetze YOUR_LONG_LIVED_TOKEN durch dein tatsächliches Home-Assistant-Token und aktualisiere die HA_URL, sodass sie der Adresse deiner Home-Assistant-Instanz entspricht.

HTTP-Transport (streamable)

Für Bereitstellungen, die kein stdio verwenden können – etwa hinter einem MCP-Gateway, gehostet auf Smithery, ein Server für mehrere Clients oder die Verbindung über netzwerkbasierte Tools wie LibreChat oder OpenWebUI – unterstützt Hass-MCP den MCP streamable HTTP transport. Der Server läuft im zustandslosen Modus (kein Mcp-Session-Id, JSON-Antworten), geeignet für horizontal skalierte Hosts.

[!CAUTION] Der HTTP-Modus legt die vollständige Home-Assistant-Steuerung über das Netzwerk offen. Jeder, der den Port erreichen kann, kann jedes Tool aufrufen – Lichter ausschalten, Türen entriegeln, Automatisierungen auslösen, HA neu starten. Die MCP-Spezifikation bringt in diesem Server noch keine eingebaute Authentifizierungsschicht mit. Bis dahin musst du ihn zwingend hinter eine der folgenden Optionen platzieren:

• Einen Reverse-Proxy (nginx, Caddy, Traefik) mit Basic-Auth- oder Bearer-Token-Validierung

• Ein VPN oder Zero-Trust-Netzwerk (Tailscale, WireGuard, Cloudflare Access)

• Nur Localhost-Bindung (Standard – ändere --host nur, wenn du weißt, was du tust)

Setze :8000 nicht ohne Authentifizierung dem offenen Internet aus.

Lokal ausführen

Mit uvx:

HA_URL=http://homeassistant.local:8123 \
HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
uvx hass-mcp --http --port 8000

Der Server bindet standardmäßig 127.0.0.1. Überschreibe dies nur mit --host 0.0.0.0, wenn du davor auch eine Authentifizierung konfiguriert hast.

In Docker ausführen

docker run --rm -p 8000:8000 \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest --http --host 0.0.0.0 --port 8000

--host 0.0.0.0 ist innerhalb von Docker erforderlich, damit der Port über die Brücke erreichbar ist. Binde die Veröffentlichung (-p) an 127.0.0.1:8000:8000, wenn du sie nur vom Host aus erreichbar machen möchtest, oder setze einen Reverse-Proxy davor.

Endpunkt

Der MCP-Endpunkt befindet sich unter /mcp. Richte deinen Client auf http://<host>:<port>/mcp aus.

Smithery / PaaS

Das Server beachtet die Umgebungsvariable PORT (Smithery-Konvention) zusätzlich zu MCP_PORT. Eine Smithery-Bereitstellung erfordert den Modus --http und liest PORT automatisch.

Benutzerdefinierte / private Zertifizierungsstelle

Wenn deine Home-Assistant-Instanz ein Zertifikat ausstellt, das von deiner eigenen Zertifizierungsstelle signiert ist (step-ca, smallstep, Homelab-OpenSSL), kann hass-mcp es ohne Deaktivierung von TLS verifizieren:

• Lokal: Installiere die CA-Root in deinem Betriebssystem-Vertrauensspeicher (macOS-Schlüsselbund, Windows-Zertifikatsspeicher oder update-ca-certificates unter Linux). hass-mcp erkennt sie automatisch über truststore.

• In Docker (oder einer anderen Sandbox-Laufzeit): Binde die CA-Datei per Bind-Mount ein und weise SSL_CERT_FILE darauf.

docker run --rm \
  -v /path/to/your-ca.crt:/etc/ssl/certs/your-ca.crt:ro \
  -e SSL_CERT_FILE=/etc/ssl/certs/your-ca.crt \
  -e HA_URL=https://homeassistant.example.internal:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest

SSL_CERT_FILE hat immer Vorrang vor dem Betriebssystem-Speicher, wenn es gesetzt ist. verify=False wird absichtlich nicht unterstützt – verwende HA_URL=http://..., wenn du wirklich unverschlüsselten lokalen LAN-Verkehr möchtest.

Verwendungsbeispiele

Hier sind einige Beispiele für Prompts, die du mit Claude verwenden kannst, sobald Hass-MCP eingerichtet ist:

• „Wie ist der aktuelle Zustand meiner Wohnzimmerlichter?"

• „Schalte alle Lichter in der Küche aus"

• „Wie ist die Temperatur im Schlafzimmer?"

• „Liste alles im Gästezimmer auf"

• „Liste alle meine Sensoren auf, die Temperaturdaten enthalten"

• „Gib mir eine Zusammenfassung meiner Klima-Entitäten"

• „Erstelle eine Automatisierung, die die Lichter bei Sonnenuntergang einschaltet"

• „Hilf mir, zu diagnostizieren, warum meine Schlafzimmer-Bewegungssensor-Automatisierung nicht funktioniert"

• „Suche nach Entitäten, die mit meinem Wohnzimmer zu tun haben"

• „Zeig mir die letzten 50 ERROR-Zeilen aus dem Home-Assistant-Log"

• „Was ist heute bei der mqtt-Integration fehlgeschlagen?"

• „Zeig mir den Stromverbrauch pro Tag für den letzten Monat"

• „Was ist letzten Dienstag mit dem Haustürsensor passiert?"

Verfügbare Tools

Hass-MCP bietet mehrere Tools für die Interaktion mit Home Assistant:

• get_version: Die Home-Assistant-Version abrufen

• get_entity: Den Zustand einer bestimmten Entität mit optionaler Feldfilterung abrufen

• entity_action: Aktionen an Entitäten ausführen (einschalten, ausschalten, umschalten)

• list_entities: Eine Liste von Entitäten mit optionaler Domain-Filterung und Suche abrufen

• search_entities_tool: Nach Entitäten suchen, die einer Abfrage entsprechen

• domain_summary_tool: Eine Zusammenfassung der Entitäten einer Domain abrufen

• list_automations: Eine Liste aller Automatisierungen abrufen

• call_service_tool: Jeden Home-Assistant-Dienst aufrufen

• restart_ha: Home Assistant neu starten

• get_history: Den Zustandsverlauf einer Entität abrufen (letzte N Stunden)

• get_history_range: Den Zustandsänderungsverlauf einer Entität über einen expliziten Datums-/Zeitbereich abrufen (start_time / end_time, ISO-8601)

• get_statistics: Langfristige aggregierte Statistiken (Mittelwert / Min / Max pro Bucket) für eine Entität über die letzten N Stunden abrufen – funktioniert auch für Daten, die älter als das Kurzzeit-Retention-Fenster des Recorders sind

• get_statistics_range: Dasselbe, aber für einen expliziten Datums-/Zeitbereich – nützlich für monatliche / jährliche Trendabfragen

• get_error_log: Das Home-Assistant-Fehlerprotokoll abrufen, mit optionalen level / integration / search_term / lines-Filtern, die serverseitig angewendet werden, damit laute Protokolle Claudes Kontext nicht sprengen

• get_entities_by_area: Entitäten in einem bestimmten Bereich / Raum auflisten

Dashboard- (Lovelace-) Bearbeitung

Dashboards über die WebSocket-API von Home Assistant lesen und live bearbeiten. Das Speichern überträgt die Änderung sofort an jeden geöffneten Browser – kein Neustart erforderlich.

• list_dashboards: Dashboards auflisten (das Standard-Dashboard plus alle Benutzer-Dashboards), jeweils mit url_path und mode (storage / yaml)

• get_dashboard_config: Die vollständige Konfiguration eines Dashboards abrufen

• set_dashboard_config: Die vollständige Konfiguration eines Dashboards ersetzen (Low-Level)

• add_card / update_card / remove_card / move_card: Karten innerhalb einer Ansicht bearbeiten (die Ansicht wird per Index oder über ihren path / title ausgewählt)

• list_view_sections: Die Abschnitte einer Ansicht vom Typ „sections" auflisten

• add_view / remove_view / update_view: Die Ansichten eines Dashboards bearbeiten

• list_dashboard_backups / restore_dashboard: Die automatischen Pre-Save-Backups auflisten und wiederherstellen

Sections-Ansichten: Der moderne Ansichtstyp von Home Assistant (type: sections) speichert seine Karten in Abschnitten statt in einer einzigen Liste auf oberster Ebene. Für solche Ansichten list_view_sections aufrufen und das Argument section (Index, Titel oder Überschrift) an die Kartentools übergeben. Kartenbearbeitungen an einer Sections-Ansicht ohne section werden mit der Liste der verfügbaren Abschnitte abgelehnt – statt stillschweigend eine Karte zu speichern, die nie gerendert würde.

Jedes Bearbeitungstool akzeptiert dry_run=true, um die resultierende Konfiguration und eine Änderungszusammenfassung ohne Speichern zu prüfen.

Wichtige Hinweise:

• Admin-Token erforderlich. Das Speichern der Lovelace-Konfiguration erfordert, dass das Long-Lived Token zu einem Admin-Benutzer gehört.

• Nur Storage-Modus. Nur UI-verwaltete („storage") Dashboards können bearbeitet werden. YAML-Modus-Dashboards werden erkannt und mit einer klaren Meldung abgelehnt – bearbeite stattdessen direkt deren YAML-Dateien.

• Ganz-Konfiguration-Schreibvorgänge. Home Assistant hat keine API für Teilbearbeitungen; jede Änderung ist ein Read-Modify-Write des gesamten Dashboards. Die High-Level-Karten-/Ansichtstools erledigen das für dich.

• Automatische Backups. Vor jedem Schreibvorgang wird die aktuelle Konfiguration in HASS_MCP_BACKUP_DIR gespeichert (Standard ~/.hass-mcp/dashboard-backups/). Bei Ausführung in Docker ein Volume an diesem Pfad einhängen, sonst gehen Backups verloren, wenn der Container neu erstellt wird.

Prompts für geführte Gespräche

Hass-MCP enthält mehrere Prompts für geführte Gespräche:

• create_automation: Leitfaden zum Erstellen von Home Assistant-Automationen basierend auf dem Auslösertyp

• debug_automation: Hilfe zur Fehlerbehebung für Automationen, die nicht funktionieren

• troubleshoot_entity: Diagnostiziere Probleme mit Entitäten

• routine_optimizer: Analysiere Nutzungsmuster und schlage optimierte Routinen basierend auf dem tatsächlichen Verhalten vor

• automation_health_check: Überprüfe alle Automationen und finde Konflikte, Redundanzen oder Verbesserungsmöglichkeiten

• entity_naming_consistency: Prüfe Entitätsnamen und schlage Standardisierungsverbesserungen vor

• dashboard_layout_generator: Erstelle optimierte Dashboards basierend auf Benutzerpräferenzen und Nutzungsmustern

Verfügbare Ressourcen

Hass-MCP stellt die folgenden Ressourcen-Endpunkte bereit:

• hass://entities/{entity_id}: Den Zustand einer bestimmten Entität abrufen

• hass://entities/{entity_id}/detailed: Detaillierte Informationen zu einer Entität mit allen Attributen abrufen

• hass://entities: Alle Home Assistant-Entitäten gruppiert nach Domäne auflisten

• hass://entities/domain/{domain}: Eine Liste von Entitäten für eine bestimmte Domäne abrufen

• hass://search/{query}/{limit}: Nach Entitäten suchen, die einer Abfrage entsprechen, mit benutzerdefiniertem Ergebnislimit

Entwicklung

Tests ausführen

uv run pytest tests/

Lizenz

MIT License