Home Assistant (HA)에서 HACS로 MCP Server for Xiaozhi를 설치한 다음, 통합에서 MCP Server for Xiaozhi 플러그인을 추가합니다(2026년 4월 이후 출고된 당사 호스트는 이 단계 설정이 완료되어 있습니다).
1단계: 샤오즈의 MCP 접속 주소 가져오기
샤오즈 기기는 HA와 연결하려면 통신 주소가 필요하며, 이 주소는 샤오즈 클라우드 콘솔에서 가져옵니다.
- PC 또는 휴대폰 브라우저로 샤오즈 공식 콘솔을 열고 로그인합니다(보통 xiaozhi.me이며, 자체 구축한 경우 자신의 콘솔 주소를 엽니다).
- 기기 목록에서 현재 사용 중인 ESP 샤오즈 기기를 찾아 구성 (Configure)을 클릭합니다.
- 페이지를 아래로 스크롤해 MCP 설정 (MCP Setting) 영역을 찾습니다.
- MCP 접속 주소 가져오기 (Get MCP Endpoint)를 클릭하면 링크(보통 wss://로 시작)가 생성됩니다. 이 주소를 복사해 두세요.
2단계: HA에서 샤오즈 MCP 통합 구성하기
이제 방금 복사한 주소를 HA에 입력해 HA가 샤오즈 서버에 접속하도록 합니다.
- Home Assistant 패널을 열고 왼쪽 사이드바에서 설정 (Settings)을 클릭합니다.
- 기기 및 서비스 (Devices & Services)를 클릭합니다.
- 오른쪽 아래의 통합 추가 (Add Integration)를 클릭합니다.
- 검색창에 MCP 또는 Xiaozhi를 입력하고 MCP Server for Xiaozhi를 찾아 클릭합니다.
- 설정 항목 입력:
- 샤오즈 MCP 접속 주소: 1단계에서 복사한 링크를 붙여 넣습니다.
- 필요한 MCP 선택(llm_hass_api 체크박스가 나타나면): 반드시 체크하세요. 이것은 HA에 내장된 제어 기능이며, 체크해야 HA가 집 안 기기의 제어권을 샤오즈에 위임할 수 있습니다. HA에 다른 MCP가 있다면 함께 체크해도 됩니다.
제출 / 완료를 클릭합니다.
상태 확인: 약 1분 기다린 뒤 샤오즈 콘솔의 MCP 설정 페이지로 돌아가 새로고침을 클릭하고 상태가 연결됨으로 바뀌었는지 확인합니다.
3단계: HA 기기를 샤오즈에 공개하기 (핵심!)
샤오즈에게 바로 불 켜라고 외치면 기기를 찾을 수 없다고 할 수 있습니다. 보안상 HA는 기본적으로 모든 기기를 음성 비서에 노출하지 않기 때문입니다.
- HA 패널에서 설정 (Settings) -> 음성 비서 (Voice assistants)로 들어갑니다.
- 공개 (Expose) 탭을 찾습니다.
- 여기에서 집 안의 여러 기기 목록을 볼 수 있습니다. 샤오즈가 제어하기를 원하는 기기(예: 특정 조명, 스위치, 에어컨, 선풍기, 온습도 센서 등)를 체크합니다. 초보자는 처음에 조명 1-2개만 체크해 테스트하고, 성공한 뒤 나머지 기기를 체크하는 것을 권장합니다.
4단계: 음성 테스트와 디버깅
모든 설정이 끝났으니 이제 샤오즈에게 명령을 내릴 수 있습니다!
- 제어 테스트: 샤오즈 샤오즈, 서재 불 켜줘.
- 조회 테스트: 샤오즈 샤오즈, 지금 거실 온도가 몇 도야?
문제가 생겼을 때 확인하는 방법(함정 회피 가이드):
- 샤오즈가 반응하지 않거나 엉뚱한 답을 함: 샤오즈 클라우드 콘솔에서 채팅 기록을 확인합니다. 샤오즈가 말을 이해했는지, Home Assistant 도구 (Function Call)를 호출하려 했는지 확인합니다.
- 명령 충돌: 현재 샤오즈 쪽에서 내장 음악/화면 제어 로직이 켜져 있으면 HA의 조명 및 음악 제어와 충돌할 수 있습니다. 조명 제어가 자주 실패하면 명령을 더 구체적으로 말해 보세요. 예를 들어 스마트홈으로 거실 천장등을 켜줘처럼 말합니다.
- HA 로그: 샤오즈가 분명히 명령을 보냈는데 기기가 반응하지 않으면 HA의 설정 -> 시스템 -> 로그에서 MCP 플러그인에 오류가 있는지 확인합니다.
위 네 단계를 따르면 당신의 샤오즈 AI가 훌륭한 스마트 홈 집사로 거듭날 것입니다!
