ESPHome MCP

An MCP server for the ESPHome 2026.6+ "Device Builder" dashboard. It lets an MCP client (Claude, etc.) list devices, read/edit/validate device YAML, stream logs, and compile/flash firmware — speaking the dashboard's new WebSocket command protocol.

Why this fork exists. ESPHome 2026.6 replaced the dashboard's legacy HTTP API with a single WebSocket command protocol. The existing MCP servers (kdkavanagh/esphome-mcp, b2un0/esphome-mcp, jrigling/esphome-mcp-integration) all speak the old protocol, so config read/edit/validate return garbage against a 2026.6 server. This project keeps the clean tool layer from kdkavanagh/esphome-mcp and rewrites the transport for the new protocol. See DECISIONS.md for the details.

Dashboard versions. The Device Builder ships from esphome/device-builder on its own release cadence, so its server_version is independent of the ESPHome version — 2026.9.0 ships Device Builder 1.14.9, 2026.8.0 ships 1.12.x, 2026.7.3 ships 1.7.0. (The pin is in ESPHome's own docker/Dockerfile, which is the only place it is written down.) This server is written against the 1.14.x protocol and falls back to the pre-1.5.0 device shape where they differ. Its protocol reference is that repo's docs/API.md and models/devices.py.

⚠ Sunset notice. Device Builder 1.15+ ships its own MCP server at POST /api/mcp (~22 tools), and ESPHome's dev branch already pins Device Builder 1.17.0 — so it arrives with ESPHome 2026.10. On a dashboard that has it, most of this server is redundant and this project will probably be archived. Until then (2026.9.0 bundles 1.14.9) it is still the way to drive the dashboard over MCP. Five tools here have no upstream equivalent as of 1.17.0 — get_device_logs, troubleshoot_device, decode_device_backtrace, migrate_device_configuration, search_device_configurations — and the intent is to offer those upstream rather than keep a fork alive. Full comparison in DECISIONS.md.

Upgrading from 2026.06.0? On ESPHome 2026.7 or newer it reported every device as unknown with no deployed version, and could report a successful install for firmware it never flashed. Both are fixed in 2026.08.0 — see the changelog.

Tools

Offline devices. If a device is offline, the dashboard compiles the firmware and arms it to flash on the device's next check-in. install_device_configuration and update_device report that as COMPILED, FLASH DEFERRED — not success.

Related MCP server: Home Assistant MCP Control

Configuration

Config is via environment variables (12-factor). Copy .env.example to .env:

Run with Docker

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

The server listens on :8080 and serves MCP over Streamable HTTP at http://<host>:8080/mcp. The container HEALTHCHECK performs a full MCP handshake and calls list_device_names, so it only reports healthy when the dashboard is actually reachable.

Once the registry image is published, pin it in compose.yaml:

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

Connect an MCP client

Point your client at the Streamable HTTP endpoint:

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

For a stdio client, run esphome-mcp (instead of the web entrypoint) with the same env.

Develop

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

Credits

This project stands on the work of others (all MIT-licensed):

• kdkavanagh/esphome-mcp — the original ESPHome MCP server. This fork keeps its FastMCP tool layer, schema handling, packaging and CI almost verbatim; the transport rewrite is the main change here.

• b2un0/esphome-mcp — for publishing a prebuilt image and surfacing the healthcheck / config-tool breakage that motivated this work.

• jrigling/esphome-mcp-integration — a Home Assistant integration referenced while mapping the ESPHome dashboard protocol.

The new 2026.6 WebSocket protocol was reverse-engineered from the ESPHome Device Builder front-end and verified against a live 2026.6 dashboard.

License

MIT.