ESPHome MCP Server — Home Assistant Add-on

MCP (Model Context Protocol) server that exposes ESPHome operations as tools for . Runs as a Home Assistant add-on with direct filesystem access — no SSH required.
Power your agent
Install from the publisher. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
No packaged release in the registry yet. Follow the repository README.
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchAdd this repository as a custom add-on repository in Home Assistant:
Settings > Add-ons > Add-on Store > ... (menu) > Repositories
https://github.com/bberrevoets/ha-addon-esphome-mcp
Install and start the ESPHome MCP Server add-on.
Copy the auto-generated auth token from the add-on's Configuration tab.
Set ESPHOME_MCP_TOKEN in your shell environment.
Add to .mcp.json in your ESPHome project:
{
"mcpServers": {
"esphome": {
"type": "http",
"url": "http://<your-ha-host>:8099/mcp",
"headers": {
"Authorization": "Bearer ${ESPHOME_MCP_TOKEN}"
}
}
}
}
Restart Claude Code and verify with /mcp.
The add-on compiles with the ESPHome version of its base image
(ghcr.io/esphome/esphome:<tag> in esphome-mcp/build.yaml), bumped with
every add-on release. A daily GitHub Action opens a bump PR as soon as a new
stable ESPHome release is published. esphome_list_devices prints that version, and
esphome_flash first queries the device's running firmware: if it is
newer than the add-on, the flash is refused (it would downgrade the
device) unless allow_downgrade=true is passed.
Flashing and logs always go over the network (--device OTA), resolved
from the device config (use_address, static IP or <name>.local);
serial upload is not supported.
Claude Code (desktop) --HTTP--> HA Add-on (MCP Server) --local--> ESPHome CLI
|
/config/esphome/ (direct filesystem access)
See esphome-mcp/DOCS.md for full documentation.
Test a change on a real Home Assistant host without releasing it:
bash scripts/deploy-dev.sh copies the working tree to /addons/esphome-mcp
on the HA host over SSH and installs/rebuilds it as ESPHome MCP Server
(dev) on port 8098, next to the store version. --sync-only, --logs and
--remove are available; HA_SSH_HOST / HA_DEV_PORT override the defaults.https://github.com/bberrevoets/ha-addon-esphome-mcp#<branch> (change the
host port under Network before starting).Unit tests (path confinement, pull arguments, YAML parsing, auth) run locally:
python -m venv .venv && .venv/bin/pip install -r esphome-mcp/requirements-dev.txt
cd esphome-mcp && ../.venv/bin/python -m pytest
The icon and logo are rendered from esphome-mcp/*.svg with
python scripts/render-icons.py. See CLAUDE.md for the release
checklist.
MIT — Berrevoets Systems
Home Assistant add-on: ESPHome MCP server for Claude Code
Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
Ha Addon Esphome runs locally over stdio.
Last checked 2026-10-28. Home Assistant add-on: ESPHome MCP server for Claude Code