Home Assistant Admin MCP

Ein sicherheitsorientierter Model Context Protocol (MCP)-Server zum Inspizieren, Steuern, Diagnostizieren und selektiven Verwalten einer Home-Assistant-Instanz. Er kombiniert die REST- und WebSocket-APIs von Home Assistant mit einem optionalen, eingeschränkten Home-Assistant-Konfigurations-Mount.

Der Server enthält kein LLM. Ein MCP-Client wählt Werkzeuge aus; dieser Server validiert Eingaben, setzt die Bereitstellungsrichtlinie durch, kommuniziert mit Home Assistant und liefert strukturierte Ergebnisse.

[!NOTE] Dieses Projekt wurde mit KI-gestützten Entwicklungswerkzeugen erstellt.

[!WARNING] Der admin-Modus kann Geräte, Registries, Helfer, Automatisierungen, Skripte, Szenen, Integrationen und die YAML-Konfiguration ändern und Home Assistant neu starten. Starten Sie im read_only-Modus, verwenden Sie ein dediziertes Home-Assistant-Konto, überprüfen Sie Trockenläufe und setzen Sie den HTTP-Endpunkt nur für vertrauenswürdige Clients ein.

Umfang und Grenzen

Die implementierten Fähigkeiten umfassen:

• Laufzeitstatus, Dienste/Aktionen, Ereignisse, Verlauf, Logbuch, Statistiken und Protokollprüfung der aktuellen Sitzung mit kondensiertem system_log-Fallback.

• Registry- und Integrationserkennung mit verknüpften Bereichen, Geräten, Entitäten und Konfigurationseinträgen.

• Validierte Dienstaufrufe mit expliziten Zielen und Live-Dienstdefinitionen von Home Assistant.

• Editor-verwaltete Lese- und Mutationsoperationen für Automatisierungen, Skripte und Szenen.

• Speichergestützte Helfer und ausgewählte Registry-/Konfigurationseintrags-Mutationen über die internen APIs von Home Assistant.

• Diagnose, Abhängigkeitsanalyse, Suchen über Registries/Editor-Ressourcen/erlaubte YAML-Dateien, Ablaufverfolgungen, Konfigurationsdiffs, Checkpoints und begrenzte Git-Historie.

• Strukturelle YAML-Patches unter einer expliziten Dateisystem-Allowlist.

Explizite Nicht-Ziele und Einschränkungen:

• Keine Home-Assistant-Supervisor-API, Add-on-Verwaltung, Host-Verwaltung oder Home-Assistant-Backup-API.

• Keine Docker-API, kein Docker-Socket, kein Container-Lebenszyklus, keine Image-Verwaltung und kein Container-Log-Zugriff. Die Bereitstellung mountet /var/run/docker.sock nicht.

• Keine beliebige Shell-Ausführung und kein beliebiger Dateisystemzugriff.

• Keine generische Config-Flow-/Options-Flow-Implementierung und kein Mechanismus zum Übermitteln beliebiger Integrationsanmeldeinformationen. Integrationstools lesen nur Konfigurationseinträge, ändern die implementierten Präferenzen, aktivieren/deaktivieren oder fordern ein Neuladen an.

• Keine Annahme, dass jeder Home-Assistant-Benutzer jeden Endpunkt aufrufen kann. Das langlebige Token erbt die Berechtigungen und den Administratorstatus seines Home-Assistant-Benutzers.

Related MCP server: hass-mcp-server

Architektur

flowchart LR
    Client["MCP client"] -->|"Streamable HTTP + MCP bearer token"| HTTP["HTTP transport /mcp"]
    Client -->|"stdio"| Stdio["stdio transport"]
    HTTP --> Policy["MCP tools, schemas, mode, risk and confirmation policy"]
    Stdio --> Policy
    Policy --> REST["Home Assistant REST client"]
    Policy --> WS["Home Assistant WebSocket client"]
    REST --> HA["Home Assistant Core"]
    WS --> HA
    Policy --> TX["Filesystem transaction layer"]
    TX --> Mount["/ha-config allowlisted read-write mount"]
    TX --> Checkpoints[".ha-mcp/backups"]
    TX --> Git["Optional local Git commits"]
    TX -->|"check config, reload, health"| REST
    NoDocker["No Supervisor or Docker socket access"]

Der HTTP-Transport ist auf der MCP-Handler-Ebene zustandslos. Der Anwendungsprozess teilt sich weiterhin seine Home-Assistant-Verbindung/den Cache und serialisiert Dateisystemtransaktionen.

Home-Assistant-API-Matrix

Überprüft am 20.08.2026 anhand der aktuellen Home-Assistant-Dokumentation und der dev-Quellen von home-assistant/core. Ein Quelllink zeigt, dass ein interner Befehl derzeit existiert; er ist keine Stabilitätsgarantie.

Die Home-Assistant-API erfordert Authorization: Bearer <HA token>. Siehe die offizielle Authentifizierungs-API. Der MCP-HTTP-Endpunkt hat ein separates Bearer-Token.

Interne API-Kompatibilität

• Interne Endpunkte können umbenannt, eingeschränkt oder mit geänderten Schemata versehen werden, ohne dass es eine öffentliche API-Abkündigungsfrist gibt. Testen Sie gegen die exakte Home-Assistant-Version, bevor Sie admin in der Produktion aktivieren.

• Registry-, Helfer-, Trace-, System-Health-, Logbuch-WebSocket-, Recorder-Metadaten-, Konfigurationseintrags- und Editor-Operationen können bei inkompatiblen Versionen HA_WS_UNSUPPORTED, HA_INTERNAL_API_UNAVAILABLE, HELPER_STORAGE_API_UNAVAILABLE, Berechtigungsfehler oder Antwortvalidierungsfehler zurückgeben.

• Das aktuelle Home-Assistant-Core markiert viele Registry-Mutationen und Trace-Lesevorgänge als nur für Administratoren. Verwenden Sie ein Token, das einem Administrator gehört, wenn diese Werkzeuge benötigt werden; ein Nicht-Admin-Token kann für eine reine Lese-/Steuerungsbereitstellung weiterhin geeignet sein, wenn seine Home-Assistant-Berechtigungen ausreichen.

• Editor-Mutationen sind auf editorverwaltete automations.yaml-, scripts.yaml- und scenes.yaml-Ressourcen beschränkt. Eine laufende YAML-Ressource ohne verwendbare Editor-ID wird als nicht bearbeitbar gemeldet.

• Unterstützte Helfer sind input_boolean, input_button, input_text, input_number, input_datetime, input_select, counter, timer und schedule. Ihre akzeptierten Felder werden durch die installierte Home-Assistant-Version bestimmt.

• Konfigurationseintrags-Operationen starten keine Konfigurationsabläufe, Optionsabläufe, Reauthentifizierung, Reparaturen, OAuth oder Anmeldedateneingabe. Verwenden Sie für diese Operationen die Home-Assistant-Benutzeroberfläche.

• Trockenlauf-Vorschauen für Helfer, Registries, Bereiche, Geräte, Entitäten und Konfigurationseinträge rufen die Mutationsvalidatoren von Home Assistant nicht auf. Ihr Ergebnis enthält Einschränkungen, die diese Tatsache beschreiben.

Produktionsbereitstellung

Voraussetzungen

• Docker Engine mit Compose v2 und BuildKit.

• Eine erreichbare Home-Assistant-Core-Instanz mit aktivierter API. Die Home-Assistant-Oberfläche stellt sie normalerweise bereit; reine API-Installationen benötigen die api-Integration.

• Ein Home-Assistant-Langzeit-Zugriffstoken.

• Ein Host-Pfad, der die Home-Assistant-Konfiguration enthält, wenn Dateisystem-, Checkpoint-, Editor-Mutationssicherheits- oder Git-Funktionen benötigt werden.

• Host-Eigentümerschaft/Berechtigungen, die es der konfigurierten Nicht-Root-UID/GID erlauben, diesen Pfad zu lesen und zu schreiben.

GitHub-Releases veröffentlichen Multi-Architektur-Images auf docker.io/lemanjo/hac-mcp. Verwenden Sie für reproduzierbare Bereitstellungen ein exaktes Release-Tag anstelle von latest. Lokale Builds bleiben unterstützt.

Ein Home-Assistant-Token erstellen

1. Melden Sie sich bei Home Assistant als der Benutzer an, als den dieser Dienst agieren soll.

2. Öffnen Sie Benutzerprofil und dann den Tab Sicherheit.

3. Wählen Sie unter Langzeit-Zugriffstokens die Option Token erstellen und benennen Sie es für diese Bereitstellung.

4. Notieren Sie das Token, wenn es angezeigt wird; Home Assistant speichert die Token-Zeichenfolge nicht für eine spätere Anzeige.

5. Verwenden Sie ein Administratorkonto nur, wenn interne Admin-Werkzeuge erforderlich sind.

Home Assistant dokumentiert die Profilverwaltung hier und Langzeit-Tokens hier. Langzeit-Tokens sind hochwertige Anmeldeinformationen und sollten nicht eingecheckt, in config.example.yaml platziert oder einem MCP-Client ausgesetzt werden.

Compose-Einrichtung

cp .env.example .env
cp config.example.yaml config.yaml
install -d -m 700 secrets
openssl rand -hex 32 > secrets/mcp_auth_token
read -rsp "Home Assistant token: " HA_TOKEN
printf '%s' "$HA_TOKEN" > secrets/home_assistant_token
unset HA_TOKEN
chmod 600 secrets/home_assistant_token secrets/mcp_auth_token

Setzen Sie diese Werte in .env:

• HOME_ASSISTANT_URL: vom Container aus erreichbar. http://host.docker.internal:8123 erreicht einen von Linux-Docker-Host veröffentlichten Home-Assistant-Port, da Compose einen host-gateway-Eintrag installiert. Eine Home-Assistant-LAN-URL funktioniert ebenfalls.

• HA_CONFIG_PATH: vorhandenes Host-Verzeichnis der Home-Assistant-Konfiguration. Es wird Lese-/Schreibzugriff unter /ha-config gemountet; Compose weigert sich, einen fehlenden Quellpfad zu erstellen.

• MCP_SETTINGS_FILE: verwenden Sie ./config.yaml, nachdem Sie bereitstellungsspezifische Änderungen vorgenommen haben.

• PUID und PGID: Nicht-Root-IDs mit Zugriff auf HA_CONFIG_PATH.

• MCP_ALLOWED_HOSTS: jeder DNS-Name oder jede IP, die Clients in den HTTP-Host-Header setzen.

• MCP_BIND_IP: behalten Sie 127.0.0.1 für einen lokalen Reverse-Proxy/Client bei; verwenden Sie 0.0.0.0 nur für absichtliche LAN-Exposition.

Validieren, bauen und starten:

docker compose config
docker compose build --pull
docker compose up -d
docker compose ps
docker compose logs -f hac-mcp

Um ein veröffentlichtes Release anstelle eines lokalen Builds zu verwenden, setzen Sie ein exaktes Image-Tag und deaktivieren Sie Builds:

MCP_IMAGE=docker.io/lemanjo/hac-mcp:0.1.0 docker compose pull hac-mcp
MCP_IMAGE=docker.io/lemanjo/hac-mcp:0.1.0 docker compose up -d --no-build hac-mcp

Health-Endpunkte:

curl --fail http://127.0.0.1:3000/livez
curl --fail http://127.0.0.1:3000/readyz

/livez meldet, dass der HTTP-Prozess bedient. /readyz führt eine authentifizierte Home-Assistant-/api/-Anfrage durch und gibt 503 zurück, wenn Home Assistant nicht verfügbar ist. Keiner der Endpunkte erfordert das MCP-Bearer-Token. Das Image und der Compose-Healthcheck verwenden /livez, sodass ein vorübergehender Home-Assistant-Ausfall keine Neustartschleife verursacht.

Das Laufzeit-Dateisystem ist schreibgeschützt, außer für /tmp, Docker-Secret-Mounts und /ha-config. Das Image läuft als Nicht-Root-Benutzer und verwendet tini als PID 1; SIGTERM/SIGINT erreichen Node, das den HTTP-Handler und die Home-Assistant-WebSocket-Verbindung schließt. Git- und CA-Zertifikate sind installiert, aber es ist kein Shell-Ausführungs-MCP-Werkzeug implementiert.

Netzwerkplatzierung

Das mitgelieferte Compose-Netzwerk ist eine isolierte Brücke mit einem veröffentlichten MCP-Port. Es verwendet niemals Host-Netzwerke und mountet niemals einen Docker-Socket.

Für Home-Assistant-Konnektivität:

• Home Assistant auf dem Docker-Host mit einem veröffentlichten Port: verwenden Sie http://host.docker.internal:8123.

• Home Assistant im LAN oder in einem macvlan/ipvlan-Netzwerk: verwenden Sie seinen LAN-DNS-Namen oder seine IP.

• Home Assistant in einem anderen benutzerdefinierten Bridge-Netzwerk: hängen Sie hac-mcp an dieses externe Netzwerk an und verwenden Sie den Container-DNS-Namen von Home Assistant. Ersetzen Sie die untere Netzwerkdeklaration durch ein external: true-Netzwerk oder fügen Sie dem Dienst ein zweites externes Netzwerk hinzu.

Für MCP-Client-Konnektivität:

• Behalten Sie MCP_BIND_IP=127.0.0.1 für Clients auf demselben Host oder einen Reverse-Proxy auf demselben Host bei.

• Setzen Sie MCP_BIND_IP=0.0.0.0 für vertrauenswürdige LAN-Clients, fügen Sie die LAN-IP/DNS-Namen des Servers zu MCP_ALLOWED_HOSTS hinzu und beschränken Sie den Port mit Host-Firewall-Regeln.

• Dieser Server beendet kein TLS. Verwenden Sie einen vertrauenswürdigen Reverse-Proxy für Datenverkehr, der ein nicht vertrauenswürdiges Netzwerk überquert, bewahren Sie den Authorization-Header und konfigurieren Sie erlaubte Ursprungs-Hostnamen, wenn ein Browser-Client Origin sendet.

Erlaubte Hosts und Ursprungs-Hostnamen mildern DNS-Rebinding/Cross-Origin-Zugriff; sie ersetzen keine Bearer-Authentifizierung oder Netzwerkkontrollen. Die Sicherheitsrichtlinie für MCPs Streamable HTTP finden Sie in der Transport-Spezifikation.

Unraid

Unraid stellt Benutzerfreigaben unter /mnt/user bereit; siehe die offizielle Freigabe-Dokumentation. Ein typisches Layout ist /mnt/user/appdata/hac-mcp für dieses Checkout/Geheimnisse und das eigentliche Home-Assistant-Appdata-Verzeichnis für HA_CONFIG_PATH.

1. Legen Sie das Projekt und die Geheimnisdateien in einem privaten Appdata-Speicherort ab. Halten Sie Geheimnisdateien im Modus 0600 und das Verzeichnis im Modus 0700, wo praktikabel.

2. Setzen Sie HA_CONFIG_PATH auf das exakte Home-Assistant-Konfigurationsverzeichnis, z. B. /mnt/user/appdata/home-assistant. Mounten Sie nicht das gesamte /mnt/user.

3. Setzen Sie PUID=99 und PGID=100 nur, wenn die Home-Assistant-Dateien für Unraids übliches nobody:users-Konto gehören; andernfalls verwenden Sie den tatsächlichen Nicht-Root-Eigentümer. Bestätigen Sie, dass diese Identität /ha-config/.ha-mcp/backups erstellen und erlaubte YAML-Dateien atomar ersetzen kann.

4. Wenn das Docker-Compose-Manager-Community-Plugin oder eine Compose-v2-CLI installiert ist, führen Sie die obige Compose-Einrichtung aus dem Projektverzeichnis aus. Compose-Geheimnisse erscheinen als Dateien unter /run/secrets; Docker dokumentiert dieses Verhalten hier.

5. Ohne Compose bauen Sie home-assistant-admin-mcp:local und erstellen den Container in Unraids Docker-UI mit Erweiterte Ansicht. Spiegeln Sie die Umgebungs-, Port- und Pfadeinstellungen aus docker-compose.yml. Binden Sie die beiden Token-Dateien schreibgeschützt an /run/secrets/home_assistant_token und /run/secrets/mcp_auth_token; diese UI-Bind-Mounts bieten die von der App erwartete Dateischnittstelle, sind aber keine Compose-Secret-Objekte.

6. Verwenden Sie standardmäßig Bridge-Netzwerke. Wenn Home Assistant Host-Netzwerke verwendet, richten Sie HOME_ASSISTANT_URL auf die Unraid-LAN-IP und den Home-Assistant-Port oder fügen Sie host.docker.internal:host-gateway hinzu. Wenn Home Assistant eine eigene br0-LAN-IP hat, verwenden Sie diese IP. Wenn beide Container ein benutzerdefiniertes Docker-Netzwerk teilen, verwenden Sie den Netzwerk-Alias von Home Assistant.

7. Für LAN-MCP-Zugriff veröffentlichen Sie Container-Port 3000, binden Sie ihn absichtlich und nehmen Sie die Unraid-IP/DNS-Namen in MCP_ALLOWED_HOSTS auf. Behalten Sie das Bearer-Token und die Firewall-Beschränkung auch in einem vertrauenswürdigen LAN bei.

8. Fügen Sie keinen Docker-Socket-Pfad hinzu. Supervisor-/Container-Administration ist nicht erforderlich oder unterstützt.

Unraids Mover- oder Freigabeeinstellungen können ändern, wo eine Benutzerfreigabedatei physisch gespeichert wird, ohne /mnt/user/... zu ändern; verwenden Sie einen stabilen Benutzerfreigabepfad und mischen Sie keine äquivalenten /mnt/user- und /mnt/diskX-Pfade.

MCP-Clients

Streamable HTTP

Die folgenden Beispiele gehen davon aus, dass der MCP-Client auf demselben Host wie Docker läuft und die Compose-Standardwerte unverändert sind. Richten Sie den Client auf:

http://127.0.0.1:3000/mcp

Jede Anfrage an /mcp muss das separate MCP-Token tragen:

Authorization: Bearer <contents of secrets/mcp_auth_token>

Laden Sie das MCP-Token in die Prozessumgebung des Clients, ohne es in eine Client-Konfigurationsdatei zu setzen. Dieses Token authentifiziert nur den MCP-Client; verwenden Sie hier niemals das Home-Assistant-Token.

export HAC_MCP_TOKEN="$(tr -d '\r\n' < /absolute/path/to/secrets/mcp_auth_token)"

Für einen Client auf einem anderen Host ersetzen Sie 127.0.0.1 durch die Adresse des MCP-Hosts, konfigurieren Sie MCP_BIND_IP, MCP_ALLOWED_HOSTS, Firewall-Regeln und TLS wie unter Netzwerkplatzierung beschrieben. Von einem anderen Container bedeutet 127.0.0.1 diesen Client-Container; verwenden Sie stattdessen einen Alias im gemeinsamen Netzwerk oder eine Host-Adresse.

Codex

Fügen Sie dies zu benutzerbezogenem ~/.codex/config.toml oder zu .codex/config.toml eines vertrauenswürdigen Projekts hinzu:

[mcp_servers.home-assistant-admin]
url = "http://127.0.0.1:3000/mcp"
bearer_token_env_var = "HAC_MCP_TOKEN"
enabled = true
default_tools_approval_mode = "writes"
tool_timeout_sec = 150

Starten Sie Codex nach dem Setzen von HAC_MCP_TOKEN neu und überprüfen Sie dann die Verbindung mit codex mcp list oder /mcp in der Codex-TUI. Der writes-Genehmigungsmodus fügt eine clientseitige Eingabeaufforderung für Werkzeuge hinzu, die nicht als schreibgeschützt markiert sind; serverseitiger Modus, Risiko und Bestätigungsrichtlinie gelten weiterhin unabhängig. Siehe die Codex-MCP-Dokumentation.

OpenCode

Fügen Sie dies in projektbezogenes opencode.json oder Ihre globale OpenCode-Konfiguration ein:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "home-assistant-admin": {
      "type": "remote",
      "url": "http://127.0.0.1:3000/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:HAC_MCP_TOKEN}"
      },
      "timeout": 150000
    }
  }
}

Starten Sie OpenCode nach dem Setzen von HAC_MCP_TOKEN neu. Führen Sie opencode mcp list aus, um den Status zu überprüfen, oder opencode mcp debug home-assistant-admin, um die Verbindung zu diagnostizieren. Beziehen Sie sich in Eingabeaufforderungen bei Bedarf namentlich auf den Server, z. B. Verwenden Sie home-assistant-admin, um nicht verfügbare Entitäten aufzulisten. Siehe die OpenCode-MCP-Dokumentation.

Claude Code

Erstellen oder führen Sie diese .mcp.json in dem Projekt zusammen, in dem Sie Claude Code ausführen:

{
  "mcpServers": {
    "home-assistant-admin": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${HAC_MCP_TOKEN}"
      },
      "timeout": 150000
    }
  }
}

Die Umgebungsvariablenreferenz ist sicher zu teilen; ersetzen Sie sie nicht durch ein literales Token in einer eingecheckten Datei. Nach dem Setzen von HAC_MCP_TOKEN führen Sie claude mcp list aus, starten Sie claude, genehmigen Sie den projektspezifischen Server, wenn Sie dazu aufgefordert werden, und verwenden Sie /mcp, um seinen Status zu überprüfen. Siehe die Claude-Code-MCP-Dokumentation.

Verifizieren und Verwenden

Eine Low-Level-Initialisierungsprobe ist nützlich, um Endpunkt-, Proxy- und Authentifizierungsfehler unabhängig von einem Client zu diagnostizieren:

curl --fail-with-body http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer ${HAC_MCP_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-probe","version":"1.0.0"}}}'

Verwenden Sie für den normalen Betrieb einen echten MCP-Client; er führt Initialisierung, Protokollversionsaushandlung, Benachrichtigungen und Werkzeugaufrufe korrekt durch. Der Server akzeptiert JSON- oder SSE-Antworten im auto-Antwortmodus und verwendet einen zustandslosen HTTP-Handler. Nützliche erste Eingabeaufforderungen sind:

• Verwenden Sie home-assistant-admin, um die Home-Assistant-Instanz zusammenzufassen und nicht verfügbare Entitäten aufzulisten. Nehmen Sie keine Änderungen vor.

• Verwenden Sie home-assistant-admin, um zu diagnostizieren, warum <Entität> nicht verfügbar ist. Lesen Sie nur Konfiguration und aktuelle Protokolle.

• Im control-Modus: Schalten Sie <explizite entity_id> ein. Zielen Sie nicht auf einen Bereich oder ein Gerät.

• Im admin-Modus: Führen Sie einen Trockenlauf der angeforderten Konfigurationsänderung durch, zeigen Sie die Diff- und Validierungsergebnisse an und warten Sie auf Bestätigung, bevor Sie sie anwenden.

Der Client kann den konfigurierten Modus des Servers nicht anheben. Starte im Modus read_only; ändere MCP_MODE in .env und erstelle den Compose-Dienst erst neu, nachdem du die Berechtigungen und die Bereitstellungsexposition geprüft hast.

stdio

Baue zuerst mit pnpm build, dann konfiguriere einen lokalen MCP-Client, um den Server zu starten. Bei stdio wird keine HTTP-Authentifizierung verwendet, da der MCP-Client den Subprozess und die Pipe besitzt.

{
  "mcpServers": {
    "home-assistant-admin": {
      "command": "node",
      "args": ["/workspaces/hac-mcp/dist/index.js"],
      "env": {
        "MCP_CONFIG_FILE": "/workspaces/hac-mcp/config.example.yaml",
        "MCP_TRANSPORT": "stdio",
        "MCP_MODE": "read_only",
        "HOME_ASSISTANT_URL": "http://homeassistant.local:8123",
        "HOME_ASSISTANT_TOKEN_FILE": "/absolute/private/path/home_assistant_token",
        "HA_CONFIG_PATH": "/absolute/path/to/home-assistant/config"
      }
    }
  }
}

Der Server schreibt Protokolle im stdio-Modus nur nach stderr. Der Docker-Healthcheck ist HTTP-spezifisch, verwende daher nicht den Standard-Docker-Healthcheck, wenn das Image absichtlich als stdio-Subprozess ausgeführt wird.

Authentifizierung und Konfiguration

Es gibt zwei unabhängige Anmeldeinformationen:

Für beide Token hat eine *_FILE-Variable Vorrang vor der direkten Umgebungsvariable, und umgebende Leerzeichen werden entfernt:

• HOME_ASSISTANT_TOKEN_FILE überschreibt HOME_ASSISTANT_TOKEN.

• MCP_AUTH_TOKEN_FILE überschreibt MCP_AUTH_TOKEN.

MCP_AUTH_TOKEN oder dessen Datei ist für HTTP obligatorisch und für stdio nicht erforderlich. Der Bearer-Vergleich verwendet SHA-256-Digests und einen timing-sicheren Vergleich. TLS ist weiterhin erforderlich, wenn das Netzwerk nicht vertrauenswürdig ist, da Bearer-Tokens wiederverwendbar sind.

Die Konfiguration wird aus MCP_CONFIG_FILE geladen, dann überschreiben Umgebungsvariablen die Datei. Unterstützte Umgebungsüberschreibungen sind:

Kommagetrennte Variablen werden getrimmt. Nur vorhandene Umgebungsvariablen überschreiben YAML-Werte. Limits, Berechtigungen, Cache-TTLs, Metadatenrichtlinie für Geheimnisse, Sicherungsverzeichnis und Git-Autorenidentität stammen ansonsten aus YAML-Standardwerten oder der Konfigurationsdatei.

Modi, Risiko und Bestätigung

Jedes Tool ist mit einer Risikostufe registriert und bleibt für Clients sichtbar. Die Richtlinie wird bei jedem Aufruf erneut durchgesetzt.

call_service hat eine CONTROL-Basislinie, stuft aber bekannte administrative Argumente vor der Autorisierung hoch: Neustart/Stopp, Sicherung und Recorder-Bereinigungsaktionen werden zu HIGH_IMPACT; Neuladen, Logger- und Konfigurationsaktionen werden zu CONFIG. Das effektive Risiko wird in jedem Ergebnis zurückgegeben, und benutzerdefinierte MCP-Metadaten kennzeichnen das Tool als dynamisch klassifiziert.

permissions.requireConfirmationFor ist standardmäßig HIGH_IMPACT. Ein passendes Tool muss confirm: true erhalten; andernfalls gibt es CONFIRMATION_REQUIRED mit Wiederholungsmetadaten zurück. Füge CONTROL und/oder CONFIG hinzu, um eine Bestätigung umfassender zu verlangen.

Die Richtlinie für sensible Domänen ist unabhängig vom Modus:

• allow: normale Modus-/Risikorichtlinie gilt.

• confirm: explizites confirm: true ist erforderlich.

• deny: der Vorgang wird auch im Modus admin abgelehnt.

Standardmäßig ist eine Bestätigung für lock, alarm_control_panel und siren erforderlich. Explizite Entitäts-IDs, die garage oder gate enthalten, erfordern ebenfalls eine Bestätigung. Die Richtlinie wertet jede explizite Entität in einem Multi-Entitäts-Ziel aus. Bereichs-/Geräteziele können zur Autorisierungszeit nicht sicher erweitert werden, daher verweigere oder verlange eine Bestätigung für die gesamte Servicedomäne, wenn diese Unterscheidung von Bedeutung ist.

Trockenläufe

dry_run: true ist bei Tools für dauerhafte Ressourcen, Helfer, Registry, Bereich, Gerät, Entität, Konfigurationseintrag, YAML-Patch, administrativen Lebenszyklus, Rollback und generische Serviceaufrufe implementiert. Praktische Tools zur physischen Steuerung simulieren keine Aktionen.

• YAML-Patches parsen und validieren das resultierende YAML und geben ein redigiertes strukturiertes Diff zurück, ohne zu schreiben, einen Prüfpunkt zu erstellen, neu zu laden, die vollständige Home-Assistant-Konfiguration zu prüfen oder zu committen.

• Das lokale YAML-Parsing lehnt Syntaxfehler, doppelte Mapping-Schlüssel, unaufgelöste Aliase und übermäßige Aliasexpansion ab. Ein nicht-trockener Apply führt anschließend die vollständige Konfigurationsprüfung von Home Assistant aus und versucht bei Ablehnung ein Rollback; die lokale Validierung ersetzt nicht die Domänenvalidierung von Home Assistant.

• Trockenläufe für Automatisierung/Skript/Szene lesen die aktuelle Editor-Ressource, erstellen ein JSON-Diff und rufen die implementierte Fragmentvalidierung auf, wo verfügbar, schreiben aber nicht und erstellen keinen Prüfpunkt.

• Trockenläufe für Helfer, Registry, Bereich, Gerät, Entität und Konfigurationseintrag lesen aktuelle Daten und erstellen eine Vorschau. Sie rufen den internen Mutationsendpunkt nicht auf und führen keine serverseitige Mutationsvalidierung von Home Assistant durch.

• Der Trockenlauf zum Neuladen eines Konfigurationseintrags meldet das vorgeschlagene Neuladen, kann aber Laufzeiteffekte nicht vorhersagen.

• Trockenläufe für Neuladen, Neustart, Prüfpunkt-Rollback und diensteigenes Git-Rollback validieren verfügbare IDs/aktuelle Metadaten und beschreiben die vorgeschlagene Aktion mit hoher Auswirkung, ohne sie anzuwenden.

• Generisches call_service unterstützt die Trockenlauf-Validierung gegen die Live-Servicedefinition; der Dienst wird nicht aufgerufen. Praktische Tools zur physischen Steuerung simulieren absichtlich keine Aktionen.

• Ein erfolgreicher Trockenlauf beweist nur die in seinem Ergebnis beschriebenen Validierungen. Er garantiert nicht, dass Zustand, Berechtigungen, interne APIs, Dateien oder das Integrationsverhalten zum Zeitpunkt des Anwendens unverändert bleiben.

Dateisystemsicherheit

Der Dateisystemzugriff wird als Einheit mit HA_FILESYSTEM_ENABLED=false deaktiviert. Wenn aktiviert, werden Anfragen unter filesystem.root kanonisiert, jedes Pfadsegment wird geprüft und Symlinks werden abgelehnt.

Zulässige Pfade:

• Jede .yaml- oder .yml-Datei direkt unter dem Konfigurationsstammverzeichnis.

• YAML unterhalb der konfigurierten allowedDirectories, standardmäßig packages und themes, rekursiv bis zur Scan-Tiefe 32.

• Ausgewählte .json, .py, .pyi, .yaml und .yml unter custom_components/<integration>/... nur, wenn die Richtlinie für benutzerdefinierte Komponenten aktiviert ist. Dedizierte Tools bieten begrenzte Quellcode-Lesezugriffe; es ist kein Quellcode-Schreibwerkzeug oder Python-Ausführungs-/Validierungspfad verfügbar.

Immer geschützt oder verweigert:

• .storage, .git, Home-Assistant-Datenbankformate, private Schlüsselformate/-namen und Pfadnamen, die den implementierten Mustern für Auth, Anmeldeinformationen, Token oder Sicherungsschlüssel entsprechen.

• Pfade außerhalb des Stammverzeichnisses, ungültige Pfadsegmente, fehlende Schreib-Elternverzeichnisse, nicht reguläre Dateien und alle Symlinks.

• Werte von secrets.yaml und secrets.yml standardmäßig. Mit allowSecretsMetadata: true können Tools sortierte Top-Level-Geheimnisschlüsselnamen, Byteanzahl und Zeitstempel ohne Werte zurückgeben.

Mit allowSecretValues: false werden sensible snake_case-, camelCase- und mit Bindestrich versehene Schlüssel wie password, clientSecret, token, apiKey, private-key, credential, authorization und cookie normalisiert und rekursiv redigiert. !secret/!env_var-Werte und passende Diff-Zeilen werden ebenfalls redigiert.

Diese Prüfungen sind musterbasiert, kein Inhalts-Scanner, daher passen ungewöhnliche Geheimnisnamen möglicherweise nicht auf jede Wächterregel. Bewahre tatsächliche Werte in der geschützten Stammdatei secrets.yaml auf, speichere keine Anmeldeinformationen in anderen zulässigen YAML-Dateien und prüfe redigierte Ausgaben, bevor du sie einem nicht vertrauenswürdigen Modell gibst. Das Setzen von HA_ALLOW_SECRET_VALUES=true erlaubt explizit das Lesen und Patchen von geheimnishaltigem YAML, einschließlich der Stammdatei secrets.yaml; verwende diese außergewöhnliche Wiederherstellungsoption nur mit vollständig vertrauenswürdigen Clients.

Schreibvorgänge verwenden temporäre Dateien, O_NOFOLLOW, fsync, atomares Umbenennen, beibehaltene Modi, SHA-256-Optimismus-Prüfungen auf Nebenläufigkeit und Synchronisierung des Elternverzeichnisses, wo unterstützt.

Prüfpunkte, Transaktionen und Rollback

Nicht-Trockenlauf-Workflow von patch_yaml_file:

1. Zulässige Pfade auflösen, aktuelle Hashes lesen, strukturelle YAML-Operationen anwenden und Syntax validieren.

2. Einen moduserhaltenden Prüfpunkt unter /ha-config/.ha-mcp/backups standardmäßig erstellen.

3. Hashes erneut prüfen und jede Datei atomar schreiben. Pro Serverprozess läuft nur eine Konfigurationstransaktion.

4. Home Assistant bitten, seine vollständige Konfiguration zu prüfen.

5. Die betroffene Automatisierungs-/Skript-/Szenen-Domäne neu laden oder homeassistant.reload_all für andere/mehrere Pfade aufrufen, sofern nicht reload: false.

6. Home-Assistant-Konfiguration als Gesundheitsprüfung lesen.

7. Bei einem Fehler nach Beginn der Schreibvorgänge nur die geänderten Dateien wiederherstellen, wenn ihre Hashes noch mit der Transaktionsausgabe übereinstimmen, dann Neuladen und Gesundheitsprüfungen versuchen.

8. Optional nur die geänderten Pfade an Git committen. Ein Git-Fehler wird nach einer erfolgreichen Home-Assistant-Änderung zu einer Warnung; er macht die Änderung nicht rückgängig.

Editorverwaltete Automatisierungs-/Skript-/Szenen-Mutationen erstellen einen Dateisystem-Prüfpunkt, bevor sie den internen Editor-Endpunkt aufrufen, erfordern das Konfigurations-Mount für Nicht-Trockenlauf-Änderungen, verifizieren Editor-Konfiguration und Laufzeit-Präsenz/Abwesenheit mit begrenzten Wiederholungen, führen die Home-Assistant-Konfigurationsvalidierung aus und versuchen ein Editor-Ebenen-Rollback, wenn Apply oder Verifikation fehlschlägt.

rollback_change erstellt zuerst einen Sicherheitsprüfpunkt der aktuellen Dateien, stellt den ausgewählten Prüfpunkt mit Konfliktprüfungen auf aktuelle Hashes wieder her, validiert die Home-Assistant-Konfiguration und lädt neu. Wenn Validierung/Neuladen fehlschlägt, versucht es, den Sicherheitsprüfpunkt wiederherzustellen und meldet jeden Wiederherstellungsfehler. Prüfpunkte sind lokale Dateischnappschüsse, keine Home-Assistant-Supervisor-Sicherungen, und die Aufbewahrungsbereinigung erfolgt nicht automatisch.

Git-Verhalten und Grenzen

Git ist optional und funktioniert nur, wenn /ha-config sich in einem erkannten Repository befindet. Das Image enthält die Git-CLI.

Werkzeuge

Die Namen unten stammen aus src/mcp/tools. Von Clients sichtbare Schemata, Beschreibungen, Anmerkungen, Risiko, Quelle und Stabilitätsmetadaten werden von der MCP-Erkennung zurückgegeben.

Erkennung

• Instanz: get_home_assistant_info, get_system_health, get_config.

• Integrationen: list_integrations, get_integration.

• Bereiche: list_areas, get_area.

• Geräte: list_devices, get_device, search_devices.

• Entitäten: list_entities, get_entity, search_entities.

• Bereichsübergreifende Suche: search_home_assistant_registry.

Laufzeit und Verlauf

• Dienste/Ereignisse: list_services, list_event_types, get_events, subscribe_events.

• Zustände: get_state, get_states, get_states_by_area, get_states_by_device.

• Aufzeichnungsdaten: get_history, get_logbook, get_statistics, get_recorder_statistics.

Steuerung

• Allgemeine/Standardsteuerung: call_service, turn_on, turn_off, toggle, set_value, set_temperature.

• Ausführung: activate_scene, run_script.

Automatisierungen, Skripte, Szenen und Ablaufverfolgungen

• Automatisierungen: list_automations, get_automation, create_automation, update_automation, delete_automation, enable_automation, disable_automation, trigger_automation, reload_automations, validate_automation.

• Skripte: list_scripts, get_script, create_script, update_script, delete_script, run_script_by_id, reload_scripts, validate_script.

• Szenen: list_scenes, get_scene, create_scene, update_scene, delete_scene, activate_scene_resource, reload_scenes.

• Automatisierungs-Ablaufverfolgungen: get_automation_traces, get_automation_trace, explain_automation_failure, get_last_automation_run.

• Allgemeine Ablaufverfolgungen: get_trace, list_traces, explain_trace, get_last_trace.

Helfer und Register

• Helfer: list_helpers, get_helper, create_helper, update_helper, delete_helper.

• Entitätsregister: update_entity_registry, disable_entity, enable_entity, rename_entity, move_entity_to_area.

• Geräteregister: update_device, rename_device, move_device_to_area, disable_device, enable_device.

• Bereichsregister: create_area, update_area, delete_area, assign_device_to_area, assign_entity_to_area.

• Konfigurationseinträge: get_config_entries, get_config_entry, reload_config_entry, update_integration, enable_integration, disable_integration.

Konfiguration und Wiederherstellung

• Lesen/Auflisten: read_configuration, list_configuration_files, read_yaml_file, list_custom_component_files, read_custom_component_source.

• Patchen/Validieren: patch_yaml_file, validate_configuration, validate_home_assistant_configuration.

• Neu laden/Neustart: reload_configuration, reload_yaml_configuration, restart_home_assistant.

• Verlauf/Unterschiede: get_config_history, get_config_diff, get_recent_changes.

• Zurücksetzen: rollback_change, rollback_to_commit.

Protokolle, Diagnosen, Abhängigkeiten und Suche

• Protokolle: get_home_assistant_logs, search_logs, get_errors, get_warnings, get_recent_errors, get_integration_errors.

• Entitäts-/Gerätebefunde: find_unavailable_entities, find_disabled_entities, find_orphaned_entities, find_orphaned_devices, find_duplicate_entities, find_entities_without_area, find_devices_without_area, find_stale_sensors.

• Automatisierungs-/Helferbefunde: find_unused_helpers, find_broken_automations, find_automation_errors, find_automations_referencing_missing_entities.

• Abhängigkeiten/Suche: get_entity_dependencies, get_automation_dependencies, search_home_assistant.

Beispielhafte Benutzeranfragen

• „Liste nicht verfügbare Entitäten in der Küche auf und schließe ihre Geräte- und Integrationsbeziehungen ein."

• „Zeige FEHLER- und KRITISCH-Protokolleinträge für die zha-Integration aus der letzten Stunde."

• „Erkläre den letzten fehlgeschlagenen Lauf der Automatisierung garage_arrival."

• „Finde Automatisierungen, die auf fehlende Entitäten verweisen, und zeige dann die Abhängigkeiten jeder Automatisierung."

• „Führe einen Probelauf eines strukturellen YAML-Patches durch, der packages/lighting.yaml ändert; zeige nur die geschwärzte Diff-Ausgabe."

• „Schalte light.office aus, aber ziele nicht auf andere Entitäten."

• „Erstelle einen input_boolean-Helfer für den Gastmodus als Probelauf und melde die Validierungseinschränkungen."

• „Lösche die Szene old_evening mit ausdrücklicher Bestätigung und melde dann Prüfpunkt, Konfigurationsvalidierung, Verifizierung, Rollback und Git-Ergebnisse."

Das Modell/der Client muss eine Anfrage in das exakte Werkzeugschema übersetzen. Eine Anfrage in natürlicher Sprache umgeht keine Modus-, Bestätigungs-, Pfad- oder Home-Assistant-Autorisierungsprüfungen.

Leistung und Grenzen

Standardwerte und harte Obergrenzen sollen verhindern, dass ein MCP-Aufruf zu einer unbegrenzten Home-Assistant- oder Dateisystemabfrage wird.

Lange Verlaufs-/Protokollbuchfenster und vollständige Diagnosen können im Home-Assistant-Recorder dennoch teuer sein. Filtere wann immer möglich nach Entität, Gerät, Integration, Zeitraum und Seite.

Entwicklung

Node.js 22.23.1 und pnpm 11.21.0 sind erforderlich.

corepack enable
pnpm --version
pnpm install --frozen-lockfile
pnpm build

Abhängigkeits-Lieferkette

• Direkte Abhängigkeiten verwenden exakte Versionen; die Sperrdatei pinnt den vollständigen Graphen mit Registry-Integritäts-Hashes.

• pnpm lehnt Veröffentlichungen ab, die jünger als 10.080 Minuten (sieben Tage) sind, Pakete ohne Veröffentlichungszeitpunkt, Herabstufungen des Herausgeber-Vertrauens, exotische transitive Quellen und nicht genehmigte Build-Skripte von Abhängigkeiten ab. Es validiert außerdem bei jeder Installation die Auflösungsdaten der Sperrdatei gegen die gepinnte npm-Registry neu.

• Installationen verwenden standardmäßig eine eingefrorene Sperrdatei. Abhängigkeitsänderungen erfordern ein explizites, überprüftes pnpm install --no-frozen-lockfile, gefolgt von pnpm supply-chain:check, der normalen Validierungssuite und einer committeten Sperrdatei-Diff.

• Transitive Overrides pinnen förderfähige content-type- und hono-Veröffentlichungen, während neuere Versionen innerhalb des Quarantänefensters bleiben, und pinnen undici-types auf eine beglaubigte Veröffentlichung, die das Herausgeber-Vertrauen nicht herabsetzt. Bewerte diese Overrides während eines überprüften Abhängigkeitsupdates neu, entferne sie aber nicht automatisch.

• CI-Aktionen und Container-Basisimages verwenden unveränderliche Commit- oder Inhalts-Digests. Laufzeit-Debian-Pakete stammen aus einem datierten Schnappschuss, sodass ein Neubuild sie nicht stillschweigend aktualisiert.

• Füge keine minimumReleaseAgeExclude-Ausnahme hinzu. Für ein dringendes Sicherheits-Release warte, bis es sieben Tage alt ist, oder hole eine ausdrückliche Genehmigung ein, diese Richtlinie in einer überprüften Änderung zu ändern.

Veröffentlichen von Releases

Das Veröffentlichen eines GitHub-Releases mit einem SemVer-Tag wie v0.1.0 führt .github/workflows/release-docker.yml aus. Es baut linux/amd64- und linux/arm64-Images, pusht das Versionstag nach docker.io/lemanjo/hac-mcp und hängt SBOM- und Herkunftsnachweise an. Stabile Releases aktualisieren auch latest; Vorabversionen nicht.

Das Repository benötigt diese GitHub-Actions-Geheimnisse:

• DOCKERHUB_USERNAME: Docker-Hub-Kontoname, derzeit lemanjo.

• DOCKERHUB_TOKEN: ein Docker-Hub-Personenzugriffstoken mit Lese-/Schreibberechtigung für lemanjo/hac-mcp. Verwende nicht das Kontopasswort.

Füge sie unter GitHub-Repository > Einstellungen > Geheimnisse und Variablen > Aktionen > Neues Repository-Geheimnis hinzu, oder mit der GitHub-CLI:

gh secret set DOCKERHUB_USERNAME --repo lemanjo/hac-mcp --body lemanjo
gh secret set DOCKERHUB_TOKEN --repo lemanjo/hac-mcp

Der zweite Befehl fragt sicher nach dem Tokenwert. Speichere das Token nicht in .env, Workflow-YAML, Shell-Verlauf oder im Repository.

Jeder Push auf main, einschließlich eines gemergten Pull Requests, führt .github/workflows/nightly-docker.yml aus. Es verwendet das separate Geheimnis DOCKERHUB_NIGHTLY_TOKEN und veröffentlicht nightly sowie ein unveränderliches nightly-<full-commit-sha>-Tag. Der Workflow kann auch manuell über GitHub Actions gestartet werden. Verwenden Sie das Full-SHA-Tag, wenn Reproduzierbarkeit wichtig ist.

gh secret set DOCKERHUB_NIGHTLY_TOKEN --repo lemanjo/hac-mcp

HTTP-Entwicklung:

HOME_ASSISTANT_URL=http://homeassistant.local:8123 \
HOME_ASSISTANT_TOKEN_FILE=/absolute/private/path/home_assistant_token \
MCP_AUTH_TOKEN_FILE=/absolute/private/path/mcp_auth_token \
MCP_CONFIG_FILE=./config.example.yaml \
MCP_TRANSPORT=http \
MCP_HOST=127.0.0.1 \
MCP_ALLOWED_HOSTS=localhost,127.0.0.1 \
HA_CONFIG_PATH=/absolute/path/to/home-assistant/config \
pnpm dev

Für reine API-Entwicklung setzen Sie HA_FILESYSTEM_ENABLED=false und HA_GIT_ENABLED=false; Editor-Ressourcenmutationen, die Checkpoints erfordern, sind dann bewusst nicht verfügbar.

Tests und Validierung

Führen Sie die Repository-Prüfungen aus:

pnpm supply-chain:check
pnpm audit --prod --audit-level high
pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm build

Validieren Sie Bereitstellungsdateien, wo Docker verfügbar ist:

docker compose config
docker build --check -t home-assistant-admin-mcp:check .
docker build -t home-assistant-admin-mcp:local .

Testen Sie dann /livez, /readyz, eine MCP-Initialize-Anfrage und repräsentative schreibgeschützte Tools gegen eine Nicht-Produktions-Home-Assistant-Instanz. Bevor Sie admin aktivieren, testen Sie interne API-Lesezugriffe, Trockenläufe, eine Wegwerf-Mutation, Checkpoint-Rollback und Git-Verhalten gegen die exakte Home-Assistant-Version und das Dateisystem, die in der Produktion verwendet werden.

Fehlerbehebung

Server startet nicht

• INVALID_CONFIGURATION: Parsen Sie config.yaml, prüfen Sie exakte camelCase-Schlüssel, Zahlenbereiche, URLs, E-Mail-Format und die abgeflachten Validierungsdetails in stderr.

• MCP_AUTH_REQUIRED: HTTP erfordert MCP_AUTH_TOKEN oder MCP_AUTH_TOKEN_FILE, mit mindestens 16 Zeichen nach dem Trimmen.

• ENOENT für ein Geheimnis: Compose-Secret-Quellpfade sind Host-Pfade relativ zum Compose-Projekt. Bestätigen Sie .env und Dateiberechtigungen.

• Docker-Healthcheck schlägt im Stdio-Modus fehl: /livez existiert nur im HTTP-Modus; entfernen/überschreiben Sie den Healthcheck für absichtliche Stdio-Container.

MCP HTTP 401, 403 oder 413

• 401: Das MCP-Bearer-Token fehlt, ist fehlerhaft oder falsch. Das Authentifizierungsschema ist case-insensitiv und muss Bearer sein.

• 403 vor einem Tool-Aufruf: Fügen Sie den tatsächlichen Hostnamen der Anfrage zu MCP_ALLOWED_HOSTS hinzu und für Browser-Clients den Ursprungs-Hostnamen ohne Schema oder Port zu MCP_ALLOWED_ORIGINS. Fügen Sie keine beliebigen Wildcards hinzu.

• 413 oder JSON-Parse-Ablehnung: Reduzieren Sie die Anfrage oder erhöhen Sie mcp.maxRequestBytes innerhalb der 10-MiB-Grenze.

• Reverse-Proxy-Fehler: Bewahren Sie Authorization, Host, Origin, Accept, Content-Type, MCP-Protocol-Version, HTTP-Streaming und SSE-Verhalten.

/readyz ist 503 oder Home-Assistant-Aufrufe schlagen fehl

• Von innerhalb eines Bridge-Containers ist localhost der MCP-Container, nicht Home Assistant. Verwenden Sie host.docker.internal, eine LAN-Adresse oder einen Alias im gemeinsamen Netzwerk.

• HA_AUTH_FAILED/HA_WS_AUTH_FAILED: Ersetzen oder erstellen Sie das langlebige Home-Assistant-Token neu.

• HA_PERMISSION_DENIED: Dem Benutzer des Tokens fehlt die Berechtigung oder der Administratorstatus für den angeforderten internen Befehl.

• HA_TLS_ERROR/HA_WS_TLS_ERROR: Installieren Sie eine vertrauenswürdige Zertifikatskette oder setzen Sie nur in einem kontrollierten privaten Netzwerk HA_VERIFY_TLS=false mit dem vollen Bewusstsein, dass die Serveridentität nicht mehr verifiziert wird.

• Fehler bei Verlauf, Logbuch oder Statistiken: Überprüfen Sie, ob die Recorder-/Logbuch-Integration geladen ist und die angeforderten IDs/Zeitbereiche existieren.

Dateisystem oder Git schlägt fehl

• CONFIG_ROOT_UNAVAILABLE/Zugriff verweigert: Machen Sie HA_CONFIG_PATH korrekt und beschreibbar durch PUID:PGID; der Container läuft absichtlich nicht als root.

• CONFIG_PATH_NOT_ALLOWED: Verwenden Sie Root-YAML oder ein erlaubtes Verzeichnis; geschützte Pfade, Symlinks, beliebige Erweiterungen und fehlende Elternverzeichnisse werden abgelehnt.

• CONFIG_CONCURRENT_MODIFICATION/ROLLBACK_CONFLICT: Ein anderer Prozess hat die Datei geändert. Lesen Sie erneut, überprüfen Sie und versuchen Sie es erneut, anstatt ein Überschreiben zu erzwingen.

• Git is enabled but no repository was detected: Initialisieren/verwalten Sie das Repository außerhalb von MCP oder setzen Sie HA_GIT_ENABLED=false.

• Git meldet zweifelhafte Eigentümerschaft: Gleichen Sie die Container-UID/GID mit der Repository-Eigentümerschaft ab. Lösen Sie es nicht, indem Sie den Container als root ausführen.

• Checkpoints verbrauchen Speicherplatz: Überprüfen und wenden Sie eine vom Betreiber definierte Aufbewahrungsrichtlinie auf .ha-mcp/backups an; es gibt kein automatisches Löschwerkzeug.

Interne Tools schlagen nach einem Home-Assistant-Upgrade fehl

• Bestätigen Sie, dass der Befehl weiterhin in der verknüpften aktuellen Core-Quelle existiert, und vergleichen Sie Anfrage-/Antwortfelder.

• Wiederholen Sie zuerst einen schreibgeschützten Vorgang. Wiederholen Sie eine Mutation nicht wiederholt, wenn der Verifizierungs- oder Rollback-Status ungewiss ist.

• Verwenden Sie die Home-Assistant-Benutzeroberfläche für Helfer, Integrationen oder Ressourcen, deren interner Endpunkt sich geändert hat.

• Behalten Sie MCP_MODE=read_only bei, bis die Kompatibilität getestet und überprüft wurde.

Lizenz

MIT