Home Assistant MCP

왜 쓰나요

핵심 기능

수천 개 엔티티에 대한 퍼지 엔티티 검색과 심층 설정 검색
YAML로 자동화, 스크립트, 장면, 헬퍼 작성 및 편집
대시보드 편집기: 카드, 레이아웃, 뷰 생성
차트 출력 형식의 히스토리 + 통계 쿼리
에너지 대시보드, 카메라 스냅샷, 자동화 추적

라이브 데모

실제 사용 모습

ha-mcp.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "ha-mcp",
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "ha-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "ha-mcp"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add ha-mcp -- uvx ha-mcp

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Home Assistant MCP

entity ID를 외우지 않고 기기 제어

👤 Home Assistant를 운용 중인 모든 분 ⏱ ~5 min beginner

언제 쓸까: 원하는 것은 알지만('주방을 30%로 어둡게') 정확한 entity_id는 모를 때.

사전 조건

Home Assistant Long-Lived Access Token — Profile → Security → Create Token; HA_TOKEN 환경 변수로 저장
HA_URL 설정 — HA_URL=http://homeassistant.local:8123 설정 (또는 사용 중인 URL)

흐름

엔티티 찾기

Use ha-mcp. Find entities matching 'kitchen light'. Show entity_id, area, and current state.✓ 복사됨

→ 현재 상태가 포함된 1–3개 후보 엔티티
변경 적용

Set kitchen ceiling lights to 30% brightness, warm white.✓ 복사됨

→ 서비스 호출 성공; 상태 확인됨

결과: 암기가 아닌 의도로 기기 제어.

함정

여러 엔티티가 매칭돼 잘못된 것이 토글됨 — 대량 작업 전 항상 entity_id 목록 확인; area 필터 사용

일반 영어 명세로 복잡한 자동화 작성

👤 YAML을 피하는 HA 사용자 ⏱ ~15 min intermediate

언제 쓸까: "집을 나가고 일몰 이후에 고양이 먹이통이 비어 있으면 알림 전송"을 원하는데 YAML을 쓰기 싫을 때.

흐름

의도 기술

Use ha-mcp. List my person tracker, sun, and cat feeder entities so we can wire an automation.✓ 복사됨

→ 상태 스키마가 포함된 관련 엔티티
YAML 생성

Create automation 'cat-feeder-sundown-alert' with that logic. Don't deploy yet — show me the YAML.✓ 복사됨

→ 채팅에 유효한 HA 자동화 YAML
배포 + 추적

Deploy it. Then trigger it manually and show the trace so I can verify the conditions fired.✓ 복사됨

→ UI에 자동화 생성; 추적에 예상 분기 확인

결과: /config/automations.yaml을 직접 편집하지 않고 동작하는 자동화 완성.

함정

자동화 배포됐지만 트리거가 안 됨 — 엔티티 이름 오타 — trace 도구 사용; entity_id가 정확히 일치하는지 확인

히스토리 + 통계로 에너지 급증 원인 조사

👤 HA 에너지 대시보드를 사용하는 스마트홈 소유자 ⏱ ~25 min intermediate

언제 쓸까: 전기 요금이 뛰었고 무엇이 바뀌었는지 알고 싶을 때.

흐름

합계 조회

Use ha-mcp. Compare total kWh per circuit for last 30 days vs the prior 30. Flag deltas >20%.✓ 복사됨

→ 델타가 강조된 회로별 표
최악의 회로 상세 분석

For the worst-offending circuit, plot hourly usage for the last 7 days and identify the new pattern.✓ 복사됨

→ 시간별 프로파일 + 이상 패턴 설명
원인 기기 찾기

Which entity on that circuit changed behavior? Cross-reference automations that touch it.✓ 복사됨

→ 특정 기기 + 자동화 특정

결과: 막연한 의심이 아닌 구체적인 "EV 충전기가 새 스케줄로 실행됨" 같은 답변.

함정

통계는 센서 커버리지만큼만 정확함 — 공백을 인정하고 모니터링 추가 위치 제안

조명, 잠금장치, 블라인드, 알림을 아우르는 '휴가 모드' 설정

👤 여행을 떠나려는 분 ⏱ ~30 min intermediate

언제 쓸까: 한 시간 후 출발인데 재실 시뮬레이션과 외출 모드를 설정하고 싶을 때.

흐름

영향받는 엔티티 목록 작성

Use ha-mcp. List lights in living areas, all door locks, all blinds. Note which are HA-controllable.✓ 복사됨

→ 제어 가능 여부 플래그가 있는 엔티티 목록
스크립트 작성

Create a script 'vacation_mode_on' that arms locks, randomizes evening lights 18:30–22:30, sets blinds to 50%, and pauses cleaning automations.✓ 복사됨

→ HA에 스크립트 생성; 수동 실행 성공
트리거 추가

Bind it to an input_boolean 'vacation_mode' so I can toggle from the dashboard.✓ 복사됨

→ 대시보드에 토글; 켜면 스크립트 실행됨

결과: 원클릭 휴가 모드; 대시보드를 켜고 집을 나서면 됨.

함정

사람이 안에 있는데 잠금장치 자동 잠금 — 재실자 체크 추가; 누군가 있을 때는 절대 잠금 금지

조합

다른 MCP와 조합해 10배 효율

ha-mcp + filesystem

automations.yaml + scripts.yaml를 git에 백업

Export all automations and scripts via ha-mcp, write to ./ha-config/, commit.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
search_entities	query: str, area?, domain?	거의 모든 흐름의 첫 단계 — entity_id 찾기	1 HA API call
call_service	domain, service, target, data	기기 또는 장면 변경 적용	1 API call
create_automation	yaml_or_object	자동화를 프로그래밍 방식으로 작성	1 API call
get_history	entity_id, start, end	분석용 상태 히스토리 조회	1 API call
get_statistics	statistic_id, period (5min\|hour\|day\|month)	장기 집계 데이터 (에너지, 기후)	1 API call
trace_automation	automation_id, run_id?	자동화가 실행됐는지/안됐는지 디버그	1 API call

비용 및 제한

운영 비용

API 쿼터: 하드 할당량 없음 — REST API는 로컬
호출당 토큰: 가변적; 필터 없이 조회하면 엔티티 레지스트리가 방대할 수 있음
금액: 무료 (오픈 소스)
팁: 항상 필터와 함께 search_entities 사용 — 전체 레지스트리 덤프는 token 비용이 큼

보안

권한, 시크릿, 파급범위

최소 스코프: Long-Lived Access Token (full HA scope)

자격 증명 저장: HA_TOKEN 환경 변수

데이터 외부 송신: HA 인스턴스 URL로만 — 가급적 로컬 네트워크에서 유지

절대 부여 금지:

신뢰하지 않는 클라우드 LLM에 HA token 전달 금지 — 이 token은 물리적 접근(잠금장치, 차고)을 제어함

Long-lived token은 자동 갱신 안 됨 — 유출이 의심되면 수동으로 교체
자동화와 잠금장치를 테스트할 때 스스로 갇히지 않는 방법으로 (백업 수단 확보)

문제 해결

자주 발생하는 오류와 해결

HA에 연결 불가

MCP가 실행되는 위치에서 HA_URL에 접근 가능한지 확인; 리버스 프록시 뒤에 있다면 trusted_proxies 확인

확인: curl $HA_URL/api/ -H 'Authorization: Bearer $HA_TOKEN'

401 Unauthorized

token이 만료되거나 폐기됨 — 프로필에서 새 long-lived token 생성

서비스 호출이 400 반환

서비스 시그니처 불일치 — 개발자 도구 패널에서 스키마를 확인하고 재시도

자동화가 배포됐지만 트리거가 안 됨

trace_automation으로 어떤 조건이 실패했는지 확인; 흔한 원인: entity_id 오타 또는 sun 조건 시간대 오류

대안