ESPHome MCP

Ein MCP-Server für das ESPHome 2026.6+ „Device Builder" Dashboard. Er ermöglicht einem MCP-Client (Claude usw.), Geräte aufzulisten, Geräte-YAML zu lesen/bearbeiten/validieren, Logs zu streamen und Firmware zu kompilieren/flashen – und spricht dabei das neue WebSocket-Kommandoprotokoll des Dashboards.

Warum dieser Fork existiert. ESPHome 2026.6 hat die alte HTTP-API des Dashboards durch ein einziges WebSocket-Kommandoprotokoll ersetzt. Die vorhandenen MCP-Server (kdkavanagh/esphome-mcp, b2un0/esphome-mcp, jrigling/esphome-mcp-integration) sprechen alle das alte Protokoll, daher liefern Konfig-Lesen/Bearbeiten/Validieren gegen einen 2026.6-Server Müll. Dieses Projekt behält die saubere Tool-Schicht von kdkavanagh/esphome-mcp bei und schreibt den Transport für das neue Protokoll neu. Details siehe DECISIONS.md.

Dashboard-Versionen. Der Device Builder wird aus esphome/device-builder in einem eigenen Release-Rhythmus ausgeliefert, daher ist seine server_version unabhängig von der ESPHome-Version – 2026.8.0 enthält Device Builder 1.12.x, 2026.7.3 enthält 1.7.0. Dieser Server ist gegen das 1.12.x-Protokoll geschrieben und fällt auf die Pre-1.5.0-Geräteform zurück, wo sie abweichen. Seine Protokollreferenz sind die docs/API.md und models/devices.py dieses Repos.

Upgrade von 2026.06.0? Auf ESPHome 2026.7 oder neuer meldete es jedes Gerät als unknown ohne installierte Version und konnte eine erfolgreiche Installation für Firmware melden, die es nie geflasht hat. Beides ist in 2026.08.0 behoben – siehe Changelog.

Werkzeuge

Offline-Geräte. Wenn ein Gerät offline ist, kompiliert das Dashboard die Firmware und rüstet sie so, dass sie beim nächsten Check-in des Geräts geflasht wird. install_device_configuration und update_device melden das als COMPILED, FLASH DEFERRED – nicht als Erfolg.

Related MCP server: websocat-mcp

Konfiguration

Die Konfiguration erfolgt über Umgebungsvariablen (12-Faktor). Kopieren Sie .env.example in .env:

Mit Docker ausführen

cp .env.example .env       # then edit ESPHOME_DASHBOARD_URL
docker compose up -d --build
docker compose ps          # STATUS should become "healthy"

Der Server lauscht auf :8080 und stellt MCP über Streamable HTTP unter http://<host>:8080/mcp bereit. Der Container-HEALTHCHECK führt einen vollständigen MCP-Handshake durch und ruft list_device_names auf, sodass er nur dann als gesund meldet, wenn das Dashboard tatsächlich erreichbar ist.

Sobald das Registry-Image veröffentlicht ist, pinnen Sie es in compose.yaml:

image: ghcr.io/loryanstrant/esphome-mcp:latest

MCP-Client verbinden

Richten Sie Ihren Client auf den Streamable-HTTP-Endpunkt:

{
  "mcpServers": {
    "esphome": { "type": "http", "url": "http://<host>:8080/mcp" }
  }
}

Für einen Stdio-Client führen Sie esphome-mcp (anstelle des Web-Einstiegspunkts) mit denselben Umgebungsvariablen aus.

Entwickeln

make install-dev   # venv + deps
make check         # lint + format-check + typecheck + test

# live tests against a real 2026.6 dashboard:
ESPHOME_DASHBOARD_URL=https://esphome.example.com .venv/bin/pytest -m live

Danksagungen

Dieses Projekt baut auf der Arbeit anderer auf (alle MIT-lizenziert):

• kdkavanagh/esphome-mcp — der ursprüngliche ESPHome-MCP-Server. Dieser Fork behält seine FastMCP-Tool-Schicht, Schema-Behandlung, Paketierung und CI fast wörtlich bei; die Transport-Neufassung ist die Hauptänderung hier.

• b2un0/esphome-mcp — für die Veröffentlichung eines vorgebauten Images und das Aufdecken der Healthcheck-/Konfig-Tool-Fehler, die diese Arbeit motiviert haben.

• jrigling/esphome-mcp-integration — eine Home-Assistant-Integration, die beim Abbilden des ESPHome-Dashboard-Protokolls herangezogen wurde.

Das neue 2026.6-WebSocket-Protokoll wurde aus dem Frontend des ESPHome Device Builders per Reverse Engineering gewonnen und gegen ein Live-2026.6-Dashboard verifiziert.

Lizenz

MIT.