하스-MCP

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

개요

Hass-MCP를 사용하면 Claude와 같은 AI 어시스턴트가 Home Assistant 인스턴스와 직접 상호 작용하여 다음을 수행할 수 있습니다.

• 장치 및 센서 상태 쿼리
• 조명, 스위치 및 기타 엔터티 제어
• 스마트 홈 요약을 받으세요
• 자동화 및 엔터티 문제 해결
• 특정 엔터티 검색
• 일반적인 작업에 대한 안내 대화 만들기

스크린샷

특징

• 엔티티 관리 : 상태 가져오기, 장치 제어 및 엔티티 검색
• 도메인 요약 : 엔터티 유형에 대한 고급 정보 얻기
• 자동화 지원 : 자동화 목록 및 제어
• 가이드 대화 : 자동화 생성과 같은 일반적인 작업에 대한 프롬프트를 사용합니다.
• 스마트 검색 : 이름, 유형 또는 상태로 엔터티 찾기
• 토큰 효율성 : 토큰 사용량을 최소화하기 위한 JSON 응답 간소화

설치

필수 조건

• 장기 액세스 토큰이 있는 Home Assistant 인스턴스
• 다음 중 하나:
  • Docker(권장)
  • Python 3.13+ 및 uv

Claude Desktop 설정

Docker 설치(권장)

1. Docker 이미지를 가져옵니다.지엑스피1
2. Claude Desktop에 MCP 서버를 추가합니다.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 장기 액세스 토큰으로 바꾸세요. 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 주소를 사용할 수도 있습니다.

다른 MCP 클라이언트

커서

1. 커서 설정 > 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 토큰으로 바꾸세요.
   • Home Assistant 인스턴스 주소와 일치하도록 HA_URL을 업데이트하세요.
3. "추가"를 클릭하여 저장하세요

클로드 코드(CLI)

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

Docker 사용(권장):

YOUR_LONG_LIVED_TOKEN 실제 Home Assistant 토큰으로 바꾸고 HA_URL을 업데이트하여 Home Assistant 인스턴스 주소와 일치시킵니다.

사용 예

Hass-MCP가 설정되면 Claude와 함께 사용할 수 있는 프롬프트의 몇 가지 예는 다음과 같습니다.

• "현재 우리집 거실 조명은 어떤 상태인가요?"
• "주방의 모든 불을 꺼주세요"
• "온도 데이터가 포함된 모든 센서 나열"
• "내 기후 개체에 대한 요약을 알려주세요"
• "일몰 시 조명을 켜는 자동화를 만들어 보세요"
• "침실 모션 센서 자동화가 작동하지 않는 이유를 해결해 주세요"
• "내 거실과 관련된 엔터티를 검색하세요"

사용 가능한 도구

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 : 홈 어시스턴트 재시작
• get_history : 엔티티의 상태 기록을 가져옵니다.
• get_error_log : Home Assistant 오류 로그를 가져옵니다.

가이드 대화를 위한 프롬프트

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} : 사용자 정의 결과 제한을 사용하여 쿼리와 일치하는 엔터티를 검색합니다.

개발

테스트 실행

특허

MIT 라이센스