ESPHome MCP

Un servidor MCP para el panel ESPHome 2026.6+ "Device Builder". Permite que un cliente MCP (Claude, etc.) liste dispositivos, lea/edite/valide el YAML de los dispositivos, transmita registros y compile/grabe firmware, usando el nuevo protocolo de comandos WebSocket del panel.

Por qué existe este fork. ESPHome 2026.6 reemplazó la API HTTP heredada del panel por un único protocolo de comandos WebSocket. Los servidores MCP existentes (kdkavanagh/esphome-mcp, b2un0/esphome-mcp, jrigling/esphome-mcp-integration) hablan todos el protocolo antiguo, por lo que leer/editar/validar la configuración devuelve basura contra un servidor 2026.6. Este proyecto conserva la capa de herramientas limpia de kdkavanagh/esphome-mcp y reescribe el transporte para el nuevo protocolo. Consulta DECISIONS.md para los detalles.

Versiones del panel. Device Builder se distribuye desde esphome/device-builder con su propio ritmo de lanzamiento, por lo que su server_version es independiente de la versión de ESPHome: 2026.8.0 incluye Device Builder 1.12.x, 2026.7.3 incluye 1.7.0. Este servidor está escrito para el protocolo 1.12.x y recurre a la forma de dispositivo anterior a la 1.5.0 cuando difieren. Su referencia de protocolo son docs/API.md y models/devices.py de ese repositorio.

¿Actualizando desde 2026.06.0? En ESPHome 2026.7 o superior informaba de todos los dispositivos como unknown sin versión desplegada, y podía informar de una instalación correcta para firmware que nunca grabó. Ambos están corregidos en 2026.08.0 — consulta el registro de cambios.

Herramientas

Dispositivos sin conexión. Si un dispositivo está sin conexión, el panel compila el firmware y lo prepara para grabarlo en la próxima conexión del dispositivo. install_device_configuration y update_device lo informan como COMPILED, FLASH DEFERRED, no como éxito.

Related MCP server: websocat-mcp

Configuración

La configuración se realiza mediante variables de entorno (12 factores). Copia .env.example a .env:

Ejecutar con Docker

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

El servidor escucha en :8080 y sirve MCP a través de Streamable HTTP en http://<host>:8080/mcp. El HEALTHCHECK del contenedor realiza un handshake MCP completo y llama a list_device_names, por lo que solo informa de estado saludable cuando el panel es realmente accesible.

Una vez publicada la imagen del registro, fíjala en compose.yaml:

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

Conectar un cliente MCP

Apunta tu cliente al endpoint de Streamable HTTP:

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

Para un cliente stdio, ejecuta esphome-mcp (en lugar del punto de entrada web) con el mismo entorno.

Desarrollo

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

Créditos

Este proyecto se apoya en el trabajo de otros (todos con licencia MIT):

• kdkavanagh/esphome-mcp — el servidor MCP original de ESPHome. Este fork conserva su capa de herramientas FastMCP, el manejo de esquemas, el empaquetado y la CI casi palabra por palabra; la reescritura del transporte es el cambio principal aquí.

• b2un0/esphome-mcp — por publicar una imagen precompilada y sacar a la luz la rotura del healthcheck / las herramientas de configuración que motivó este trabajo.

• jrigling/esphome-mcp-integration — una integración de Home Assistant consultada al mapear el protocolo del panel de ESPHome.

El nuevo protocolo WebSocket 2026.6 se obtuvo mediante ingeniería inversa del front-end de ESPHome Device Builder y se verificó contra un panel 2026.6 en directo.

Licencia

MIT.