ESPHome MCP

ESPHome 2026.6+ "Device Builder" ダッシュボード向けの MCP サーバーです。MCP クライアント（Claude など）から、デバイスの一覧表示、デバイス YAML の読み取り・編集・検証、ログのストリーミング、ファームウェアのコンパイル/フラッシュが行えます。ダッシュボードの新しい WebSocket コマンドプロトコルに対応しています。

このフォークが存在する理由。 ESPHome 2026.6 は、ダッシュボードの従来の HTTP API を単一の WebSocket コマンドプロトコルに置き換えました。既存の 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: Home Assistant MCP Control

設定

設定は環境変数（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 で待ち受け、http://<host>:8080/mcp で Streamable HTTP 経由の MCP を提供します。コンテナの HEALTHCHECK は完全な MCP ハンドシェイクを実行して list_device_names を呼び出すため、ダッシュボードに実際に到達できる場合にのみ healthy と報告します。

レジストリイメージが公開されたら、compose.yaml で固定してください:

image: ghcr.io/loryanstrant/esphome-mcp:latest

MCP クライアントを接続する

クライアントを Streamable HTTP エンドポイントに向けてください:

{
  "mcpServers": {
    "esphome": { "type": "http", "url": "http://<host>:8080/mcp" }
  }
}

stdio クライアントの場合は、同じ環境変数で（Web エントリポイントの代わりに）esphome-mcp を実行します。

開発

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 ツール層、スキーマ処理、パッケージング、CI をほぼそのまま維持しています。主な変更点はトランスポートの書き直しです。

• b2un0/esphome-mcp — プリビルドイメージを公開し、この作業の動機となったヘルスチェック/設定ツールの不具合を明らかにしてくれたことに対して。

• jrigling/esphome-mcp-integration — ESPHome ダッシュボードプロトコルのマッピング中に参照した Home Assistant インテグレーション。

新しい 2026.6 WebSocket プロトコルは、ESPHome Device Builder のフロントエンドからリバースエンジニアリングされ、実際の 2026.6 ダッシュボードに対して検証されました。

ライセンス

MIT。