ESPHome MCP Server — Home Assistant Add-on

MCP (Model Context Protocol) server that exposes ESPHome operations as tools for Claude Code. Runs as a Home Assistant add-on with direct filesystem access — no SSH required.

Quick Start

1. Add 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
   

2. Install and start the ESPHome MCP Server add-on.

3. Copy the auto-generated auth token from the add-on’s Configuration tab.

4. Set ESPHOME_MCP_TOKEN in your shell environment.

5. Add to .mcp.json in your ESPHome project:

   {
     "mcpServers": {
       "esphome": {
         "type": "http",
         "url": "http://:8099/mcp",
         "headers": {
           "Authorization": "Bearer ${ESPHOME_MCP_TOKEN}"
         }
       }
     }
   }
   

6. Restart Claude Code and verify with /mcp.

Tools

ESPHome version

The add-on compiles with the ESPHome version of its base image (ghcr.io/esphome/esphome: 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 .local); serial upload is not supported.

Architecture

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.

Development

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.
• Or add a branch as a second add-on repository in HA: https://github.com/bberrevoets/ha-addon-esphome-mcp# (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.

License

MIT — Berrevoets Systems