ESPHome MCP

一个面向 ESPHome 2026.6+ "Device Builder" 仪表盘的 MCP 服务器。它让 MCP 客户端（Claude 等）能够列出设备、读取/编辑/校验设备 YAML、流式查看日志，以及编译/烧录固件——使用仪表盘新的 WebSocket 命令协议。

为什么会有这个分支。 ESPHome 2026.6 用单一的 WebSocket 命令协议取代了仪表盘旧版 HTTP API。现有的 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 端口，并通过 Streamable HTTP 在 http://<host>:8080/mcp 提供 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（而不是 Web 入口点）。

开发

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 — 最初的 ESPHome MCP 服务器。本分支几乎原样保留了其 FastMCP 工具层、schema 处理、打包和 CI；传输层重写是这里的主要改动。

• b2un0/esphome-mcp — 感谢其发布预构建镜像，并暴露了健康检查/配置工具的故障，正是这些故障促成了本项目。

• jrigling/esphome-mcp-integration — 在梳理 ESPHome 仪表盘协议时参考的一个 Home Assistant 集成。

新的 2026.6 WebSocket 协议是从 ESPHome Device Builder 前端逆向工程而来，并在真实的 2026.6 仪表盘上进行了验证。

许可证

MIT。