hass-mcp — HiTech Lab 에디션

HiTech Lab이 유지 관리 및 최적화 출처: https://github.com/voska/hass-mcp

Hass-MCP

Home Assistant를 Claude 및 기타 LLM과 통합하기 위한 MCP(Model Context Protocol) 서버입니다.

개요

Hass-MCP는 Claude와 같은 AI 어시스턴트가 Home Assistant 인스턴스와 직접 상호작용할 수 있게 해주며, 다음과 같은 작업을 수행할 수 있습니다:

• 기기 및 센서의 상태 조회

• 조명, 스위치 및 기타 엔티티 제어

• 스마트 홈 요약 가져오기

• 자동화 및 엔티티 문제 해결

• 특정 엔티티 검색

• 일반적인 작업을 위한 안내형 대화 생성

Related MCP server: Hass-MCP

스크린샷

기능

• 엔티티 관리: 상태 조회, 기기 제어, 엔티티 검색

• 도메인 요약: 엔티티 유형에 대한 상위 수준 정보 제공

• 자동화 지원: 자동화 목록 및 제어

• 안내형 대화: 자동화 생성과 같은 일반적인 작업을 위한 프롬프트 사용

• 스마트 검색: 이름, 유형 또는 상태로 엔티티 찾기

• 실시간 대시보드 편집: Home Assistant의 WebSocket API를 통해 Lovelace 대시보드(카드 및 뷰)를 읽고 편집 — 변경 사항이 열려 있는 브라우저에 즉시 반영되며, 자동 백업 및 dry-run 미리보기 지원

• 토큰 효율성: 토큰 사용량을 최소화하는 간결한 JSON 응답

설치

사전 요구 사항

• Long-Lived Access Token이 있는 Home Assistant 인스턴스

• 다음 중 하나:

  • Docker(권장)

  • Python 3.13+ 및 uv

Claude Desktop 설정

Docker 설치(권장)

1. Docker 이미지를 가져옵니다:

   docker pull voska/hass-mcp:latest

2. MCP 서버를 Claude Desktop에 추가합니다:

   a. Claude Desktop을 열고 설정으로 이동합니다 b. 개발자 > 구성 편집으로 이동합니다 c. claude_desktop_config.json 파일에 다음 구성을 추가합니다:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e",
           "HA_URL",
           "-e",
           "HA_TOKEN",
           "voska/hass-mcp"
         ],
         "env": {
           "HA_URL": "http://homeassistant.local:8123",
           "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
         }
       }
     }
   }

   d. YOUR_LONG_LIVED_TOKEN을 실제 Home Assistant long-lived access token으로 교체합니다 e. HA_URL을 업데이트합니다:

   • Home Assistant가 같은 머신에서 실행 중인 경우: http://host.docker.internal:8123 사용(Mac/Windows의 Docker Desktop)

   • Home Assistant가 다른 머신에서 실행 중인 경우: 실제 IP 또는 호스트 이름 사용

   f. 파일을 저장하고 Claude Desktop을 다시 시작합니다

3. "Hass-MCP" 도구가 이제 Claude Desktop 도구 메뉴에 표시됩니다

참고: 같은 머신의 Docker에서 Home Assistant를 실행 중인 경우, 컨테이너가 Home Assistant에 접근할 수 있도록 Docker 인수에 --network host를 추가해야 할 수 있습니다. 또는 host.docker.internal 대신 머신의 IP 주소를 사용하세요.

uv/uvx

1. 시스템에 uv를 설치합니다.

2. MCP 서버를 Claude Desktop에 추가합니다:

   a. Claude Desktop을 열고 설정으로 이동합니다 b. 개발자 > 구성 편집으로 이동합니다 c. claude_desktop_config.json 파일에 다음 구성을 추가합니다:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "uvx",
         "args": ["hass-mcp"],
         "env": {
           "HA_URL": "http://homeassistant.local:8123",
           "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
         }
       }
     }
   }

   d. YOUR_LONG_LIVED_TOKEN을 실제 Home Assistant long-lived access token으로 교체합니다 e. HA_URL을 업데이트합니다:

   • Home Assistant가 같은 머신에서 실행 중인 경우: http://host.docker.internal:8123 사용 (Mac/Windows의 Docker Desktop)

   • Home Assistant가 다른 머신에서 실행 중인 경우: 실제 IP 또는 호스트 이름 사용

   f. 파일을 저장하고 Claude Desktop을 다시 시작합니다

3. "Hass-MCP" 도구가 이제 Claude Desktop 도구 메뉴에 표시되어야 합니다

기타 MCP 클라이언트

Cursor

1. Cursor 설정 > MCP > 새 MCP 서버 추가로 이동합니다

2. 양식을 작성합니다:

   • 이름: Hass-MCP

   • 유형: command

   • 명령:

     docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp

   • YOUR_LONG_LIVED_TOKEN을 실제 Home Assistant 토큰으로 교체합니다

   • HA_URL을 Home Assistant 인스턴스 주소에 맞게 업데이트합니다

3. "추가"를 클릭하여 저장합니다

Claude Code (CLI)

Claude Code CLI에서 사용하려면 mcp add 명령을 사용하여 MCP 서버를 직접 추가할 수 있습니다:

Docker 사용(권장):

claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

YOUR_LONG_LIVED_TOKEN을 실제 Home Assistant 토큰으로 교체하고 HA_URL을 Home Assistant 인스턴스 주소에 맞게 업데이트합니다.

HTTP 전송(Streamable)

stdio를 사용할 수 없는 배포 환경 — MCP 게이트웨이 뒤에서 실행, Smithery에서 호스팅, 여러 클라이언트 간 서버 공유, 또는 LibreChat이나 OpenWebUI 같은 네트워크 기반 도구에서 연결 — 을 위해 Hass-MCP는 MCP streamable HTTP transport를 지원합니다. 서버는 무상태 모드(Mcp-Session-Id 없음, JSON 응답)로 실행되며, 수평 확장 호스트에 적합합니다.

[!CAUTION] HTTP 모드는 네트워크를 통해 Home Assistant의 전체 제어권을 노출합니다. 포트에 접근할 수 있는 사람은 누구나 모든 도구를 호출할 수 있습니다 — 조명 끄기, 문 잠금 해제, 자동화 트리거, HA 재시작 등. MCP 사양에는 아직 이 서버에 내장 인증 계층이 포함되어 있지 않습니다. 그때까지는 반드시 다음 중 하나 뒤에 배치해야 합니다:

• 기본 인증 또는 bearer-token 검증을 수행하는 리버스 프록시(nginx, Caddy, Traefik)

• VPN 또는 제로 트러스트 네트워크(Tailscale, WireGuard, Cloudflare Access)

• localhost 바인딩만 사용(기본값 — --host는 확실히 알 때만 변경)

인증 없이 :8000을 공개 인터넷에 노출하지 마세요.

로컬에서 실행

uvx 사용:

HA_URL=http://homeassistant.local:8123 \
HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
uvx hass-mcp --http --port 8000

서버는 기본적으로 127.0.0.1에 바인딩됩니다. 앞에 인증을 구성한 경우에만 --host 0.0.0.0으로 재정의하세요.

Docker에서 실행

docker run --rm -p 8000:8000 \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest --http --host 0.0.0.0 --port 8000

Docker 내부에서는 포트가 브리지를 통해 접근 가능하도록 --host 0.0.0.0이 필요합니다. 호스트에서만 접근 가능하게 하려면 게시(-p)를 127.0.0.1:8000:8000으로 바인딩하거나 앞에 리버스 프록시를 배치하세요.

엔드포인트

MCP 엔드포인트는 /mcp에 있습니다. 클라이언트를 http://<host>:<port>/mcp로 연결하세요.

Smithery / PaaS

서버는 MCP_PORT 외에도 PORT 환경 변수(Smithery의 규칙)를 인식합니다. Smithery 배포에는 --http 모드가 필요하며 PORT를 자동으로 읽습니다.

사용자 지정 / 개인 CA

Home Assistant 인스턴스가 자체 CA(step-ca, smallstep, homelab OpenSSL)가 서명한 인증서를 제공하는 경우, hass-mcp는 TLS를 비활성화하지 않고도 이를 검증할 수 있습니다:

• 로컬: OS 신뢰 저장소(macOS 키체인, Windows 인증서 저장소, Linux의 update-ca-certificates)에 CA 루트를 설치합니다. hass-mcp는 truststore를 통해 자동으로 인식합니다.

• Docker(또는 샌드박스 런타임): CA 파일을 바인드 마운트하고 SSL_CERT_FILE을 해당 파일로 지정합니다.

docker run --rm \
  -v /path/to/your-ca.crt:/etc/ssl/certs/your-ca.crt:ro \
  -e SSL_CERT_FILE=/etc/ssl/certs/your-ca.crt \
  -e HA_URL=https://homeassistant.example.internal:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest

SSL_CERT_FILE은 설정 시 OS 저장소보다 항상 우선합니다. verify=False는 의도적으로 지원되지 않습니다 — 암호화되지 않은 로컬 LAN 트래픽을 원한다면 HA_URL=http://...를 사용하세요.

사용 예시

Hass-MCP가 설정된 후 Claude와 함께 사용할 수 있는 프롬프트 예시입니다:

• "거실 조명의 현재 상태는 무엇인가요?"

• "주방의 모든 조명을 꺼주세요"

• "안방의 온도는 몇 도인가요?"

• "게스트 룸의 모든 것을 나열해주세요"

• "온도 데이터가 포함된 모든 센서를 나열해주세요"

• "기후 엔티티에 대한 요약을 제공해주세요"

• "일몰 시 조명이 켜지는 자동화를 만들어주세요"

• "침실 모션 센서 자동화가 작동하지 않는 문제를 해결하는 데 도움을 주세요"

• "거실과 관련된 엔티티를 검색해주세요"

• "Home Assistant 로그에서 마지막 50개의 ERROR 줄을 보여주세요"

• "오늘 mqtt 통합에서 실패한 것은 무엇인가요?"

• "지난 달의 일별 전력 사용량을 보여주세요"

• "지난 화요일에 현관문 센서에 무슨 일이 있었나요?"

사용 가능한 도구

Hass-MCP는 Home Assistant와 상호작용하기 위한 여러 도구를 제공합니다:

• get_version: Home Assistant 버전 가져오기

• get_entity: 선택적 필드 필터링으로 특정 엔티티의 상태 가져오기

• entity_action: 엔티티에 대한 작업 수행(켜기, 끄기, 토글)

• list_entities: 선택적 도메인 필터링 및 검색으로 엔티티 목록 가져오기

• search_entities_tool: 쿼리와 일치하는 엔티티 검색

• domain_summary_tool: 도메인의 엔티티 요약 가져오기

• list_automations: 모든 자동화 목록 가져오기

• call_service_tool: 모든 Home Assistant 서비스 호출

• restart_ha: Home Assistant 재시작

• get_history: 엔티티의 상태 기록 가져오기(지난 N시간)

• get_history_range: 명시적 날짜/시간 범위(start_time / end_time, ISO-8601)에 대한 엔티티의 상태 변경 기록 가져오기

• get_statistics: 지난 N시간 동안 엔티티의 장기 집계 통계(버킷당 평균 / 최소 / 최대) 가져오기 — 레코더의 단기 보존 기간보다 오래된 데이터에도 작동

• get_statistics_range: 명시적 날짜/시간 범위에 대한 동일한 통계 — 월간 / 연간 추세 쿼리에 유용

• get_error_log: Home Assistant 오류 로그 가져오기, 선택적 level / integration / search_term / lines 필터가 서버 측에서 적용되어 시끄러운 로그가 Claude의 컨텍스트를 소모하지 않음

• get_entities_by_area: 특정 영역 / 방의 엔티티 목록

대시보드(Lovelace) 편집

Home Assistant의 WebSocket API를 통해 대시보드를 읽고 실시간 편집합니다. 저장하면 변경 사항이 열려 있는 모든 브라우저에 즉시 푸시됩니다 — 재시작 불필요.

• list_dashboards: 대시보드 목록(기본값 및 사용자 대시보드), 각각의 url_path 및 mode(storage / yaml) 포함

• get_dashboard_config: 대시보드의 전체 구성 가져오기

• set_dashboard_config: 대시보드의 전체 구성 교체(저수준)

• add_card / update_card / remove_card / move_card: 뷰 내에서 카드 편집(뷰는 인덱스 또는 path / title로 선택)

• list_view_sections: "sections" 유형 뷰의 섹션 목록

• add_view / remove_view / update_view: 대시보드의 뷰 편집

• list_dashboard_backups / restore_dashboard: 자동 저장 전 백업 목록 및 롤백

섹션 뷰: Home Assistant의 최신 뷰 유형(type: sections)은 단일 최상위 목록이 아닌 섹션 내부에 카드를 저장합니다. 이러한 뷰의 경우 list_view_sections를 호출하고 카드 도구에 section 인수(인덱스, 제목 또는 헤딩)를 전달하세요. section 없이 섹션 뷰에서 카드를 편집하면 사용 가능한 섹션 목록과 함께 거부됩니다 — 렌더링되지 않을 카드를 조용히 저장하는 대신.

모든 편집 도구는 dry_run=true를 허용하여 저장하지 않고 결과 구성과 변경 요약을 미리 볼 수 있습니다.

중요 참고 사항:

• 관리자 토큰 필요. Lovelace 구성 저장에는 long-lived token이 관리자 사용자에 속해야 합니다.

• 저장소 모드만. UI 관리("storage") 대시보드만 편집할 수 있습니다. YAML 모드 대시보드는 감지되어 명확한 메시지와 함께 거부됩니다 — 대신 YAML 파일을 직접 편집하세요.

• 전체 구성 쓰기. Home Assistant에는 부분 편집 API가 없습니다. 모든 변경은 전체 대시보드의 읽기-수정-쓰기입니다. 고수준 카드/뷰 도구가 이를 처리합니다.

• 자동 백업. 각 쓰기 전에 현재 구성이 HASS_MCP_BACKUP_DIR(기본값 ~/.hass-mcp/dashboard-backups/)에 저장됩니다. Docker에서 실행할 때 이 경로에 볼륨을 마운트하지 않으면 컨테이너가 재생성될 때 백업이 손실됩니다.

안내형 대화를 위한 프롬프트

Hass-MCP에는 안내형 대화를 위한 여러 프롬프트가 포함되어 있습니다:

• create_automation: 트리거 유형에 따라 Home Assistant 자동화를 생성하기 위한 가이드

• debug_automation: 작동하지 않는 자동화에 대한 문제 해결 도움말

• troubleshoot_entity: 엔티티 문제 진단

• routine_optimizer: 사용 패턴을 분석하고 실제 동작에 기반한 최적화된 루틴 제안

• automation_health_check: 모든 자동화 검토, 충돌, 중복 또는 개선 기회 찾기

• entity_naming_consistency: 엔티티 이름 감사 및 표준화 개선 제안

• dashboard_layout_generator: 사용자 선호도와 사용 패턴에 기반한 최적화된 대시보드 생성

사용 가능한 리소스

Hass-MCP는 다음 리소스 엔드포인트를 제공합니다:

• hass://entities/{entity_id}: 특정 엔티티의 상태 가져오기

• hass://entities/{entity_id}/detailed: 모든 속성을 포함한 엔티티의 상세 정보 가져오기

• hass://entities: 모든 Home Assistant 엔티티를 도메인별로 그룹화하여 나열

• hass://entities/domain/{domain}: 특정 도메인의 엔티티 목록 가져오기

• hass://search/{query}/{limit}: 사용자 지정 결과 제한으로 쿼리와 일치하는 엔티티 검색

개발

테스트 실행

uv run pytest tests/

라이선스

MIT License