ESPHome MCP

MCP-сервер для панели управления ESPHome 2026.6+ «Device Builder». Он позволяет MCP-клиенту (Claude и др.) просматривать список устройств, читать/редактировать/проверять YAML устройств, транслировать логи и компилировать/прошивать прошивку — используя новый протокол WebSocket-команд панели управления.

Почему существует этот форк. ESPHome 2026.6 заменил устаревший HTTP API панели управления единым протоколом WebSocket-команд. Существующие MCP-серверы (kdkavanagh/esphome-mcp, b2un0/esphome-mcp, jrigling/esphome-mcp-integration) все используют старый протокол, поэтому чтение/редактирование/проверка конфигурации возвращают мусор при работе с сервером 2026.6. Этот проект сохраняет чистый слой инструментов из kdkavanagh/esphome-mcp и переписывает транспорт для нового протокола. Подробности см. в DECISIONS.md.

Версии панели управления. Device Builder поставляется из esphome/device-builder по собственному графику выпуска, поэтому его server_version не зависит от версии ESPHome — 2026.8.0 поставляется с Device Builder 1.12.x, 2026.7.3 — с 1.7.0. Этот сервер написан для протокола 1.12.x и использует форму устройства до 1.5.0 в тех местах, где они различаются. В качестве справочника по протоколу используются docs/API.md и models/devices.py из этого репозитория.

Обновляетесь с 2026.06.0? На ESPHome 2026.7 или новее он показывал каждое устройство как unknown без развёрнутой версии и мог сообщить об успешной установке прошивки, которую на самом деле не прошивал. Обе проблемы исправлены в 2026.08.0 — см. журнал изменений.

Инструменты

Офлайн-устройства. Если устройство офлайн, панель управления компилирует прошивку и подготавливает её к прошивке при следующем обращении устройства. install_device_configuration и update_device сообщают об этом как COMPILED, FLASH DEFERRED — а не об успехе.

Related MCP server: websocat-mcp

Конфигурация

Конфигурация задаётся через переменные окружения (12-factor). Скопируйте .env.example в .env:

Запуск с Docker

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

Сервер слушает порт :8080 и предоставляет MCP через Streamable HTTP по адресу http://<host>:8080/mcp. Контейнерный HEALTHCHECK выполняет полное MCP-рукопожатие и вызывает list_device_names, поэтому он сообщает о здоровом состоянии только тогда, когда панель управления действительно доступна.

Когда образ реестра будет опубликован, зафиксируйте его в compose.yaml:

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

Подключение MCP-клиента

Направьте вашего клиента на конечную точку Streamable HTTP:

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

Для stdio-клиента запустите esphome-mcp (вместо веб-точки входа) с теми же переменными окружения.

Разработка

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

Благодарности

Этот проект опирается на работы других авторов (все под лицензией MIT):

• kdkavanagh/esphome-mcp — оригинальный MCP-сервер ESPHome. Этот форк сохраняет его слой инструментов FastMCP, обработку схем, упаковку и CI почти без изменений; основное изменение здесь — переписанный транспорт.

• b2un0/esphome-mcp — за публикацию готового образа и выявление поломки healthcheck / инструментов конфигурации, которая мотивировала эту работу.

• jrigling/esphome-mcp-integration — интеграция Home Assistant, использованная как справочник при изучении протокола панели управления ESPHome.

Новый протокол WebSocket 2026.6 был восстановлен из фронтенда ESPHome Device Builder и проверен на живой панели управления 2026.6.

Лицензия

MIT.