Esphome Mcp — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited Esphome Mcp (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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 fromkdkavanagh/esphome-mcpand rewrites the transport for the new protocol. SeeDECISIONS.mdfor the details.
| Tool | What it does |
|---|---|
list_devices / list_device_names | Inventory configured devices |
check_device_update | Is a firmware update available? |
get_device_status | Online/offline + address |
get_device_version | Deployed vs current version |
get_device_configuration | Read a device's YAML |
edit_device_configuration | Save YAML (then auto-validate) |
validate_device_configuration | Full ESPHome validation, no save |
get_device_logs | Stream recent device logs |
get_esphome_schema | Component schema for a version |
install_device_configuration | Compile + OTA flash (destructive) |
update_device | Recompile + OTA flash to latest (destructive) |
Config is via environment variables (12-factor). Copy .env.example to .env:
| Variable | Required | Description |
|---|---|---|
ESPHOME_DASHBOARD_URL | yes | Dashboard base URL, e.g. https://esphome.example.com or http://host:6052. REST and WebSocket URLs are derived from it. |
ESPHOME_DASHBOARD_USERNAME | no | Basic Auth user (only if the dashboard reports requires_auth=true). |
ESPHOME_DASHBOARD_PASSWORD | no | Basic Auth password. |
LOG_LEVEL | no | DEBUG/INFO/WARNING/ERROR (default INFO). |
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:latestPoint 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.
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 liveThis project stands on the work of others (all MIT-licensed):
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.
image and surfacing the healthcheck / config-tool breakage that motivated this work.
— 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.
MIT.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.