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: websocat-mcp

구성

구성은 환경 변수(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를 호출하므로 대시보드에 실제로 연결할 수 있을 때만 정상으로 보고합니다.

레지스트리 이미지가 게시되면 compose.yaml에서 고정하세요:

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

MCP 클라이언트 연결

클라이언트를 Streamable HTTP 엔드포인트로 지정하세요:

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

stdio 클라이언트의 경우 동일한 환경 변수로 (웹 엔트리포인트 대신) 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.