mcp-ha: Home Assistant용 MCP 서버, 애드온으로

이 Home Assistant 애드온은 MCP(Model Context Protocol) 서버를 노출합니다. 실제로는 Claude, Gemini 또는 다른 MCP 클라이언트를 인스턴스에 연결하여 집과 대화할 수 있습니다.

"어떤 조명이 켜져 있었지?", "어젯밤 난방 자동화가 왜 실행되지 않았지?", "이번 주 에너지 사용량을 그래프로 그려줘."

문서: devitek.github.io/mcp-ha (영어 및 프랑스어)

제공 기능

총 16개의 도구로, LLM 컨텍스트 창을 절약하도록 설계되었습니다: 간결하고 페이지네이션되며 제한된 응답, 그리고 어시스턴트를 더 정확한 쿼리로 유도하는 메모가 포함됩니다.

Related MCP server: hass-mcp

공식 HA MCP 통합을 사용하지 않는 이유?

그것은 존재하고 작동하지만, Assist API를 통해 진행됩니다: Assist에 노출된 엔티티만, 기록 없음, 레지스트리 없음, 애드온 없음, 자동화 구성 없음. 이 애드온은 직접적이고 세분화된 접근을 제공합니다. 둘 다 공존할 수 있습니다.

설치

요구 사항: Home Assistant OS 또는 Supervised(애드온은 Supervisor가 필요합니다).

1. 이 저장소를 애드온 저장소에 추가하세요:

   

   또는 수동으로: 설정, 애드온, 애드온 스토어, 점 3개 메뉴, 저장소에서 https://github.com/Devitek/mcp-ha를 붙여넣으세요.

2. "MCP Home Assistant"를 설치하고 시작하세요.

3. 애드온 구성 탭을 여세요: 첫 시작 시 API 토큰이 생성되어 저장됩니다(애드온 로그에도 출력됩니다).

클라이언트 연결

Claude Code:

claude mcp add --transport http home-assistant \
  http://HA_IP:9583/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop 및 Gemini CLI: 문서 사이트의 클라이언트 가이드를 참조하세요.

보안 요약

• 기본적으로 읽기 전용. allow_write를 활성화하지 않으면 서비스 호출 도구는 클라이언트에 존재하지 않습니다.

• 심층 방어 쓰기가 활성화된 경우: 위험한 서비스 차단 목록(HA 종료, shell_command...), 엔티티에 대한 glob 허용/차단 목록, dry_run 모드, 로그의 모든 시도에 대한 JSON 감사 추적.

• LAN 전용. TLS 없음, OAuth 없음: 포트 9583을 인터넷에 노출하지 마세요.

전체 위협 모델은 SECURITY.md에 있습니다.

문서

• 문서 사이트: 설치, 구성, 클라이언트, 도구 참조, 아키텍처(영어 및 프랑스어)

• 애드온 문서: HA 인터페이스에 표시되는 페이지

• 기여 가이드: 개발 설정, 규칙, 릴리스

• 저장소 이슈: 프로젝트 지식 베이스, 모든 설계 결정과 함정은 décision 및 écueil 라벨로 추적됩니다(프랑스어).

라이선스

MIT