内容
# ESPHome MCP
MCP 服务器，适用于 **ESPHome 2026.6+ "设备构建器"** 控制面板。它允许 MCP 客户端（例如 Claude）列出设备、读取/编辑/验证设备 YAML、流式传输日志以及编译/烧录固件 —— 使用控制面板的新 WebSocket 命令协议。
> **为何存在此分支。** ESPHome **2026.6** 用单一的 WebSocket 命令协议取代了控制面板的旧 HTTP API。现有的 MCP 服务器（[`kdkavanagh/esphome-mcp`](https://github.com/kdkavanagh/esphome-mcp)、[`b2un0/esphome-mcp`](https://github.com/b2un0/esphome-mcp)、[`jrigling/esphome-mcp-integration`](https://github.com/jrigling/esphome-mcp-integration)）都使用旧协议，因此针对 2026.6 服务器的配置读取/编辑/验证会返回错误数据。该项目保留了 `kdkavanagh/esphome-mcp` 的干净工具层，并重写了新协议的传输。有关详细信息，请参见 [`DECISIONS.md`](DECISIONS.md)。
## 工具
| 工具 | 功能 |
| --- | --- |
| `list_devices` / `list_device_names` | 清点已配置的设备 |
| `check_device_update` | 是否有固件更新可用？ |
| `get_device_status` | 在线/离线 + 地址 |
| `get_device_version` | 已部署 vs 当前版本 |
| `get_device_configuration` | 读取设备的 YAML |
| `edit_device_configuration` | 保存 YAML（然后自动验证） |
| `validate_device_configuration` | 完整的 ESPHome 验证，无需保存 |
| `get_device_logs` | 流式传输最近的设备日志 |
| `get_esphome_schema` | 指定版本的组件模式 |
| `install_device_configuration` | 编译 + OTA 烧录（破坏性） |
| `update_device` | 重新编译 + OTA 烧录到最新版本（破坏性） |
## 配置
通过环境变量（12 因子）进行配置。复制 [`.env.example`](.env.example) 到 `.env`：
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `ESPHOME_DASHBOARD_URL` | 是 | 控制面板基准 URL，例如 `https://esphome.example.com` 或 `http://host:6052`。REST 和 WebSocket URL 从中派生。 |
| `ESPHOME_DASHBOARD_USERNAME` | 否 | 基本身份验证用户（仅当控制面板报告 `requires_auth=true` 时）。 |
| `ESPHOME_DASHBOARD_PASSWORD` | 否 | 基本身份验证密码。 |
| `LOG_LEVEL` | 否 | `DEBUG`/`INFO`/`WARNING`/`ERROR`（默认为 `INFO`）。 |
## 使用 Docker 运行
```bash
cp .env.example .env # 然后编辑 ESPHOME_DASHBOARD_URL
docker compose up -d --build
docker compose ps # STATUS 应该变为 "healthy"
```
服务器监听 `:8080` 并在 `http://<host>:8080/mcp` 处提供 MCP 流式 HTTP 服务。容器的 `HEALTHCHECK` 执行完整的 MCP 握手并调用 `list_device_names`，因此只有在控制面板实际可达时才报告健康。
一旦注册表镜像发布，在 `compose.yaml` 中固定它：
```yaml
image: ghcr.io/loryanstrant/esphome-mcp:latest
```
## 连接 MCP 客户端
将您的客户端指向流式 HTTP 端点：
```json
{
"mcpServers": {
"esphome": { "type": "http", "url": "http://<host>:8080/mcp" }
}
}
```
对于 stdio 客户端，运行 `esphome-mcp`（而不是 Web 入口点）并使用相同的环境变量。
## 开发
```bash
make install-dev # 虚拟环境 + 依赖项
make check # 校验 + 格式检查 + 类型检查 + 测试
# 针对真实的 2026.6 控制面板进行实时测试：
ESPHOME_DASHBOARD_URL=https://esphome.example.com .venv/bin/pytest -m live
```
## 鸣谢
本项目建立在其他人的工作基础上（均为 MIT 许可）：
- **[kdkavanagh/esphome-mcp](https://github.com/kdkavanagh/esphome-mcp)** — 原始的 ESPHome MCP 服务器。此分支保留其 FastMCP 工具层、模式处理、打包和 CI，几乎逐字保留；传输重写是此处的主要更改。
- **[b2un0/esphome-mcp](https://github.com/b2un0/esphome-mcp)** — 发布预构建镜像并公开健康检查/配置工具中断导致了这项工作。
- **[jrigling/esphome-mcp-integration](https://github.com/jrigling/esphome-mcp-integration)** — 集成 Home Assistant 集成，在映射 ESPHome 控制面板协议时被引用。
新的 2026.6 WebSocket 协议是从 ESPHome 设备构建器前端逆向工程并针对实时 2026.6 控制面板验证的。
## 许可证
[MIT](LICENSE)。
