homeassistant-ai/ha-mcp

📚 ha‑mcp 는 무엇입니까?

ha‑mcp (Home Assistant Model Context Protocol 서버)는 대규모 언어 모델 어시스턴트(Claude, ChatGPT, Gemini 등)가 Home Assistant 인스턴스와 상호작용할 수 있도록 해주는 비공식이지만 완전한 기능의 서버입니다. Model Context Protocol (MCP)를 구현하여 AI 클라이언트가 다음을 수행할 수 있습니다:

모든 엔티티(조명, 센서, 카메라 등)의 상태를 조회합니다.
Home Assistant의 모든 서비스를 통해 장치를 제어합니다.
자동화, 스크립트, 대시보드, 헬퍼, 영역, 그룹, 블루프린트, HACS 애드온, 백업 등을 생성, 편집, 디버그합니다.
로그, 기록, 자동화 추적 정보를 읽어 AI가 문제를 진단하는 데 도움을 줍니다.
안전 기능(읽기 전용 모드, 도구별 권한, 자동 편집 백업)을 전환하여 AI가 변경할 수 있는 범위를 제어할 수 있습니다.

요약하면, 대화형 AI를 단순히 전등을 켜거나 끄는 것을 넘어서, **전체 스마트홈 설정을 구축하고 유지보수할 수 있는 완전한 Home Assistant 관리자**로 바꿉니다.

🚀 어떻게 실행하나요?

ha‑mcp는 4가지 방법으로 설치할 수 있으며, 모두 AI 클라이언트가 연결할 수 있는 단일 URL을 노출합니다.

방법	실행 위치	일반적인 사용 사례
HA‑MCP 커스텀 컴포넌트 (권장)	Home Assistant 내부에서 커스텀 통합(주로 HACS로 설치)	OS, Supervised, Container, Core 모든 Home Assistant 설치 유형에서 작동. 추가 토큰 필요 없음.
Home Assistant 앱 / 애드온	Home Assistant OS / Supervised에서 별도의 "앱"으로 실행	독립된 프로세스를 선호하지만, 원격 접근용 내장 웹훅을 유지하고 싶을 때 적합.
Docker / PyPI / uvx HTTP 서버	Home Assistant 외부(어떤 호스트든)	애드온을 실행할 수 없는 Container 또는 Core 설치, 또는 서버를 별도의 머신에 호스팅하고 싶을 때 유용.
로컬 stdio	직접 랩톱/데스크톱에서 실행(생산용으로는 권장하지 않음)	빠른 데모 또는 실험용. 알려진 전송 오류가 있음.

모든 방법에서 비밀 웹훅 URL(또는 직접 로컬 포트)이 생성되며, 이를 AI 클라이언트의 MCP 설정에 붙여넣어야 합니다.

🔧 빠른 시작 (커스텀 컴포넌트)

HACS를 통해 통합 추가 – README의 배지 사용 또는 https://github.com/homeassistant-ai/ha-mcp-integration 리포지터리를 커스텀 저장소로 추가.
Home Assistant 재시작.
설정 → 장치 및 서비스 → 통합 추가에서 HA‑MCP 커스텀 컴포넌트를 검색하고 HA‑MCP 서버 항목을 추가.
서버가 시작된 후 설정 화면을 열어 웹훅 URL(예: https://my‑ha.duckdns.org/api/webhook/abcd1234)을 확인. 로그에도 표시됨.
이 URL을 AI 클라이언트의 MCP 설정에 붙여넣기 – 이제 AI 어시스턴트가 Home Assistant와 통신할 수 있습니다.

이 통합은 도구, 기능 플래그, 백업, 테마를 관리할 수 있는 사이드바 패널도 추가하며, 선택적 웹훅 인증(ha_auth)도 활성화 가능합니다.

🛠️ AI는 실제로 무엇을 할 수 있나요?

ha‑mcp는 87개의 "도구" 를 제공하며, 기능별로 그룹화되어 있습니다. README에서 소개된 대표적인 작업은 다음과 같습니다:

카테고리	예시 도구
제어	`ha_call_service`, `ha_bulk_control` – 장치 전원 on/off, 기후 조절 등
자동화 및 스크립트	`ha_config_get_automation`, `ha_config_set_automation`, `ha_config_get_script`, `ha_config_set_script` – 자동화 및 스크립트 생성/편집
대시보드/UI	`ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_get_dashboard_screenshot` – 카드 추가, Lovelace 레이아웃 편집
파일 및 YAML (베타)	`ha_read_file`, `ha_write_file`, `ha_config_get_yaml`, `ha_config_set_yaml` – 원시 설정 파일 편집
시스템 및 유지보수	`ha_manage_backup`, `ha_manage_updates`, `ha_restart`, `ha_reload_core` – 백업/복원, Home Assistant 업데이트, 서비스 재시작
디버깅 및 모니터링	`ha_get_history`, `ha_get_logs`, `ha_get_automation_traces` – 로그 가져오기, 엔티티 기록 보기, 실패한 자동화 디버깅
보안	`ha_manage_security_policy`, `읽기 전용 모드 전환` – AI가 변경할 수 있는 범위 제한

예를 들어 "일몰 시 테라스 조명을 켜는 자동화를 만들어줘"라고 요청하면, AI는 뒤에서 적절한 ha_config_set_automation 도구를 호출하고 YAML을 작성한 후 설정을 다시 로드합니다.

🌐 원격 접근 옵션

내장 웹훅 (커스텀 컴포넌트에서 사용) – Nabu Casa, Cloudflare Tunnel 또는 어떤 리버스 프록시와도 작동.
웹훅 프록시 앱 – 애드온 방법용. 기존 Home Assistant 웹훅을 통해 MCP 트래픽을 전달.
OpenAI Tunnel – 커뮤니티 유지 관리 터널로, 로컬에 호스팅된 서버에 ChatGPT 스타일 연결을 가능하게 하며 공개 URL 노출 없이도 가능.
OIDC 인증 – 외부 ID 제공자(Keycloak, Auth0 등) 뒤에 웹훅을 보호하는 선택적 모드.

📦 데모 및 설정 워즈드

리포지터리는 macOS, Linux, Windows용 1명령어 데모 스크립트를 제공하며, 호스팅된 데모 Home Assistant에 연결된 일시적인 stdio 기반 서버를 빠르게 구동할 수 있습니다. 스크립트 실행 후 Claude, ChatGPT 또는 어떤 MCP 호환 클라이언트에게 "내 Home Assistant를 볼 수 있어요?"라고 물어보면 통합의 작동을 확인할 수 있습니다.

또한 웹 기반 설정 워즈드 (https://homeassistant-ai.github.io/ha-mcp/setup/)는 모든 지원되는 클라이언트(Claude Code, Gemini CLI, ChatGPT, VS Code, Cursor 등)에 맞는 정확한 클라이언트별 설정을 생성합니다.

🆚 Home Assistant의 내장 MCP 서버와의 차이점

기능	내장 MCP 서버	ha‑mcp
장치 제어 및 상태 쿼리	✅ (Assist에 노출된 엔티티만)	✅ (모든 엔티티)
자동화, 스크립트, 시나리오 편집	❌	✅
대시보드 / Lovelace UI 편집	❌	✅
로그, 기록, 자동화 추적 접근	❌	✅
헬퍼, 영역, 그룹, 라벨 관리	❌	✅
백업/복원, 앱 관리, HACS, 장치 레지스트리	❌	✅

간단한 음성 명령용은 내장 서버를 사용하고, ha‑mcp 는 AI가 전체 Home Assistant 설정을 구성하고 유지보수하고 싶을 때 사용하세요.

📚 더 배우고 싶으신가요?

문서 사이트 – https://homeassistant-ai.github.io/ha-mcp/
설정 워즈드 – https://homeassistant-ai.github.io/ha-mcp/setup/
FAQ 및 문제 해결 – https://homeassistant-ai.github.io/ha-mcp/faq/
GitHub 리포지터리 – https://github.com/homeassistant-ai/ha-mcp (이슈, 기여 가이드, 릴리스 노트)

TL;DR

ha‑mcp는 대규모 언어 모델 어시스턴트와 Home Assistant를 연결하는 실제로 프로덕션에 사용 가능한 서버이며, AI에게 Home Assistant 전체 설정에 대한 완전한 읽기/쓰기 접근 권한을 제공합니다. HA‑MCP 커스텀 컴포넌트(가장 쉬운 경로)로 설치하고 생성된 웹훅 URL을 가져와, 어떤 MCP 호환 AI 클라이언트든 연결하면 자연어로 자동화 생성, 대시보드 편집, 문제 디버깅 등을 가능하게 할 수 있습니다.