MCP – Home Assistant Bridge¶

Stand 08.09.2026: produktiv installiert und geprüft. Der zentrale MCP unter mcp.diebrocks.com bindet den separat betriebenen Home Assistant MCP Server als internen Upstream ein. Externe KI-Clients benötigen damit nur noch einen MCP-Zugang.

Architektur¶

flowchart TD
    CLIENT["Claude / ChatGPT / anderer MCP-Client"]
    CF["Cloudflare Access<br/>mcp.diebrocks.com"]
    MCP["mcp-shell auf CT 108<br/>10.10.10.33:3000"]
    SEARCH["ha_search_tools"]
    READ["ha_call_read_tool"]
    WRITE["ha_call_write_tool"]
    DELETE["ha_call_delete_tool"]
    GUIDE["ha_get_skill_guide"]
    HAMCP["Home Assistant MCP Server<br/>10.10.10.20:9583"]
    HA["Home Assistant"]

    CLIENT -->|HTTPS| CF
    CF --> MCP
    MCP --> SEARCH
    MCP --> READ
    MCP --> WRITE
    MCP --> DELETE
    MCP --> GUIDE
    SEARCH --> HAMCP
    READ --> HAMCP
    WRITE --> HAMCP
    DELETE --> HAMCP
    GUIDE --> HAMCP
    HAMCP --> HA

Der Home Assistant MCP Server bleibt ein eigenständiges Home-Assistant-Add-on und wird weiterhin unabhängig aktualisiert. Der zentrale MCP übernimmt nur die Weiterleitung. Cloudflare und der externe Zugriffspfad zum bestehenden MCP wurden dafür nicht verändert.

Sichtbare Bridge-Tools¶

Zusätzlich zu den 29 bisherigen Infrastruktur-Tools stellt der zentrale MCP fünf HA-Bridge-Tools bereit:

Tool	Zweck
`ha_search_tools`	HA-MCP-Toolkatalog durchsuchen
`ha_call_read_tool`	gefundenes Nur-Lese-Tool ausführen
`ha_call_write_tool`	gefundenes Schreib-Tool ausführen
`ha_call_delete_tool`	gefundenes Lösch-Tool ausführen
`ha_get_skill_guide`	HA-MCP-Best-Practice-Skills lesen

Damit umfasst der äußere MCP derzeit 34 sichtbare Tools.

Der vollständige Home-Assistant-Werkzeugkatalog wird absichtlich nicht im äußeren MCP gespiegelt. HA-MCP läuft mit enable_tool_search: true; über ha_search_tools werden die aktuell verfügbaren HA-Werkzeuge dynamisch gefunden und anschließend über den passenden Proxy ausgeführt. Dadurch können neue HA-MCP-Tools nach einem Add-on-Update genutzt werden, ohne mehr als 70 Tool-Schemas im zentralen MCP fest einzubauen.

Technische Umsetzung auf CT 108¶

Die produktive Bridge verändert /opt/mcp-shell/lib/core.js nicht.

Verwendete Dateien:

/opt/mcp-shell/lib/ha-upstream.js
/opt/mcp-shell/lib/ha-preload.js
/etc/mcp-shell/ha-upstream.env
/etc/systemd/system/mcp-shell.service.d/30-ha-upstream.conf

ha-upstream.js verwaltet die interne Streamable-HTTP-Verbindung zu HA-MCP und registriert die fünf Bridge-Tools. ha-preload.js erweitert beim Node-Prozessstart die bestehende McpServer-Klasse, sodass die Bridge beim ersten normalen Tool-Registervorgang an denselben Server angehängt wird. Damit mussten die bestehenden 29 Tool-Registrierungen und der gehärtete core.js nicht geändert werden.

Der systemd-Drop-in lädt:

[Service]
EnvironmentFile=/etc/mcp-shell/ha-upstream.env
Environment="NODE_OPTIONS=--import=/opt/mcp-shell/lib/ha-preload.js"

Die interne HA-MCP-Adresse einschließlich Secret-Pfad liegt ausschließlich in /etc/mcp-shell/ha-upstream.env. Die Datei ist root-geschützt mit Modus 0600. Der Secret-Pfad wird nicht im Wiki dokumentiert.

Home Assistant MCP Server¶

Produktiver Stand bei Einrichtung der Bridge:

Eigenschaft	Wert
Add-on	Home Assistant MCP Server
Slug	`81f33d0f_ha_mcp`
Version	`8.4.3`
Port	`9583/tcp` → `9583`
Host-Netzwerk	aktiv
Autostart	aktiv
Auto-Update	aktiv
Watchdog	aktiv
Tool-Suche	aktiv
Max. Suchergebnisse	5
Read-only-Modus	aus
Auto-Backup von Bearbeitungen	aktiv
Snapshot-Löschung	deaktiviert

Der zentrale MCP verbindet sich direkt über das interne LAN mit HA-MCP. Ein Umweg über Cloudflare oder Nabu Casa ist für diese Verbindung nicht erforderlich.

Audit¶

Home Assistant und der zentrale MCP haben getrennte Aufgaben im Audit:

HA-MCP-Audit: protokolliert die eigentliche Home-Assistant-Aktion.
CT-108-Audit: protokolliert nur den Aufruf des äußeren Bridge-Tools.

flowchart LR
    CLIENT["Externer MCP-Client"] --> GATEWAY["HA-Bridge-Tool auf CT 108"]
    GATEWAY -->|minimiertes Audit-v2| WRITER["mcp-audit-writer"]
    WRITER --> OUTER["Gateway-Audit<br/>Caller · Client · Status · Laufzeit"]
    GATEWAY --> HAMCP["HA-MCP"]
    HAMCP --> HA["Home Assistant"]
    HAMCP --> INNER["HA-MCP-Audit<br/>eigentliche HA-Aktion"]

Die fünf Bridge-Toolnamen wurden in die zentrale Audit-v2-Allowlist des root-eigenen Writers unter /opt/mcp-audit-writer/audit-writer.js aufgenommen.

Für Bridge-Aufrufe schreibt der äußere MCP ausschließlich minimierte Metadaten:

Toolname;
ok oder error;
Laufzeit;
Caller-Kategorie (Enrico beziehungsweise andere Identität);
Client-Kategorie (OpenAI MCP, Claude MCP oder anderer Client);
Cloudflare-Quell-IP und cf_ray, sofern im Request vorhanden;
keine HA-Argumente;
keine HA-Antworten;
keine interne HA-MCP-URL oder Secrets.

Die Caller-Zuordnung erfolgt im Preload aus den bereits vorhandenen Request-Metadaten. Das von Cloudflare übergebene Access-JWT wird dabei ausschließlich zur Audit-Zuordnung dekodiert; die eigentliche Authentifizierung bleibt unverändert im bestehenden MCP-Zugriffspfad. CF-Connecting-IP, CF-Ray und der User-Agent werden für dieselbe Audit-Kategorisierung verwendet wie bei den normalen MCP-Aufrufen.

Die Ereignisse laufen wie alle gehärteten Audit-v2-Einträge über /run/mcp-audit-writer/audit.sock zum root-eigenen mcp-audit-writer. Der Benutzer mcp erhält dadurch weiterhin keine direkten Schreibrechte auf /var/log/mcp-audit/.

Produktiver Caller-Nachweis nach R5¶

Nach Installation von R5 wurde ein echter HA-Aufruf aus einem frisch verbundenen Chat ausgeführt. Die folgenden Bridge-Einträge wurden im produktiven Audit gefunden:

ha_call_read_tool  → caller=Enrico, client=OpenAI MCP, IP vorhanden, cf_ray vorhanden
ha_search_tools    → caller=Enrico, client=OpenAI MCP, IP vorhanden, cf_ray vorhanden

Damit ist die Bridge-Audit-Zuordnung jetzt konsistent zu den 29 normalen MCP-Tools. Die vorherigen andere Identitaet-/ip: null-Einträge stammen vom Stand vor R5.

Prüfungen nach dem Deployment¶

Folgende Prüfungen wurden erfolgreich durchgeführt:

mcp-shell bleibt nach Aktivierung der Bridge aktiv.
mcp-audit-writer bleibt aktiv.
Der laufende mcp-shell besitzt NODE_OPTIONS für den Preload und die interne HA-MCP-Verbindungsvariable.
Ein direkter MCP-Client auf CT 108 konnte über dieselbe interne Verbindung ha_search_tools bei HA-MCP aufrufen.
Ein echter lokaler MCP-Testtransport durchlief den installierten Preload, sah ha_search_tools und führte einen erfolgreichen HA-MCP-Aufruf aus.
Der dazugehörige äußere Audit-v2-Eintrag wurde anschließend unter ha_search_tools gefunden; args blieb leer und result enthielt keinen Antwortinhalt.
Claude wurde als Praxistest nur mit mcp.diebrocks.com verbunden und konnte darüber Home-Assistant-Daten auslesen, unter anderem die vorhandenen Automationen.
In einem neuen Chat wurden ha_search_tools, mehrere ha_call_read_tool-Aufrufe sowie die Read/Write/Delete-Proxy-Trennung erfolgreich getestet. Fehlgeleitete Proxy-Aufrufe wurden erwartungsgemäß abgewiesen, ohne etwas zu schreiben oder zu löschen.
Nach R5 wurden echte Bridge-Aufrufe im CT-108-Audit korrekt als Enrico / OpenAI MCP einschließlich IP und cf_ray protokolliert.

Einige MCP-Clients cachen ihre Tool-Liste. Nach Änderungen an der Bridge kann deshalb ein Aktualisieren oder Neuverbinden des MCP-Connectors erforderlich sein. Ein Server-Neustart allein zwingt den Client nicht dazu, seine lokale Tool-Liste neu zu laden.

Dashboard-Zählung 9 vs. 8¶

Bei der Funktionsprüfung fiel auf, dass ha_get_system_health für Lovelace 9 Dashboards meldet, während ha_config_get_dashboard(list_only=true) 8 konfigurierte Storage-Dashboards zurückgibt.

Das ist kein Fehler. Home Assistant führt intern zusätzlich einen anonymen Default-Dashboard-Slot mit Schlüssel None. Die System-Health-Funktion zählt die komplette interne Dashboard-Map und kommt deshalb auf:

8 konfigurierte Storage-Dashboards
+ 1 interner Default-Slot
= 9 Dashboards in System Health

Für die tatsächlich konfigurierten Dashboards ist deshalb die Liste von ha_config_get_dashboard(list_only=true) maßgeblich.

Fehlerverhalten¶

Ist HA-MCP nicht erreichbar, bleiben die normalen Infrastruktur-Tools des zentralen MCP verfügbar. Nur der konkrete HA-Bridge-Aufruf schlägt fehl. Die Bridge versucht bei einem Upstream-Fehler einmal, die HA-MCP-Verbindung neu aufzubauen.

Ein Auditfehler darf einen bereits ausgeführten HA-Aufruf weder wiederholen noch rückgängig machen. Das äußere Audit ist deshalb bewusst Best-Effort; die eigentliche Home-Assistant-Aktion wird zusätzlich durch HA-MCP selbst protokolliert.

Rollback und Sicherungen¶

Bei der produktiven Einführung wurden root-geschützte Sicherungen angelegt.

Aktuelle relevante Sicherungen:

/root/mcp-ha-bridge-r3-backup-20260908-112029
/root/mcp-ha-audit-backup-20260908-113811
/root/mcp-ha-audit-r5-backup-20260908-115145

Der erste Core-Patch-Versuch wurde nach einem Startfehler zurückgerollt. Die endgültige R3-Bridge verwendet deshalb den Preload-Ansatz ohne Änderung an core.js. R5 erweitert ausschließlich den Preload um die korrekte Caller-Zuordnung für das äußere Audit.

Für einen vollständigen manuellen Rückbau sind mindestens zu entfernen beziehungsweise aus der Sicherung wiederherzustellen:

/opt/mcp-shell/lib/ha-upstream.js
/opt/mcp-shell/lib/ha-preload.js
/etc/mcp-shell/ha-upstream.env
/etc/systemd/system/mcp-shell.service.d/30-ha-upstream.conf

Zusätzlich muss die Audit-Writer-Allowlist auf den Stand vor den fünf ha_*-Toolnamen zurückgesetzt werden. Danach systemctl daemon-reload, mcp-audit-writer und mcp-shell neu starten.

Wartung¶

HA-MCP wird weiterhin über Home Assistant aktualisiert. Solange die fünf Gateway-Tools ha_search_tools, ha_call_read_tool, ha_call_write_tool, ha_call_delete_tool und ha_get_skill_guide kompatibel bleiben, ist für neue interne HA-Tools keine Änderung am zentralen MCP erforderlich.

Nach einem HA-MCP-Update empfiehlt sich ein kurzer Funktionstest über mcp.diebrocks.com: Tool suchen, ein harmloses Nur-Lese-Tool ausführen und anschließend den äußeren Audit-Eintrag prüfen.

Siehe auch: MCP-Server, Audit-Inhalte begrenzen und Audit-Integrität.