스마트홈의 발전과 함께 AI 기술의 활용이 더욱 중요해지고 있습니다. 이번 포스트에서는 Home Assistant에 MCP(Model Context Protocol) 서버를 구성하여 Claude Desktop과 연동하는 방법을 상세히 알아보겠습니다. 이를 통해 자연어로 스마트홈 기기를 제어하고, 더욱 지능적인 자동화를 구현할 수 있습니다.
Home Assistant MCP Server 구성 방법
1. 사전 요구사항
연동을 시작하기 전에 다음 사항들이 준비되어야 합니다:
- LLM 애플리케이션: Claude Desktop 또는 Cursor 설치
- Home Assistant: 정상 작동 중인 Home Assistant 인스턴스
- mcp-proxy: 로컬 MCP 프록시 서버 (대부분의 클라이언트가 원격 MCP 서버 직접 연결을 지원하지 않아 필요, SSE -> STDIO)
2. Home Assistant에 MCP Server 통합 추가
Home Assistant에서 MCP 서버 기능을 활성화해야 합니다.
UI를 통한 설정 (권장)
- Home Assistant 관리자 화면에서 Settings > Devices & Services 접속
- 우측 하단의 Add Integration 버튼 클릭
- 목록에서 Model Context Protocol Server 선택
- Assist, Stateless Assist 중에 선택 (각각 어떤것을 선택해도 동작에는 무관, 분리된 이유에 대해서는 확인중)
- 화면 안내에 따라 설정 완료
3. 노출할 엔티티 설정
보안을 위해 Claude가 접근할 수 있는 기기와 엔티티를 명시적으로 설정해야 합니다:
- Settings > Voice Assistants > Exposed Entities 접속
- Claude나 다른 MCP 클라이언트가 제어할 수 있는 기기들을 선택
- 조명 (lights)
- 스위치 (switches)
- 센서 (sensors)
- 할 일 목록 (todo lists)
- 스크립트 (scripts) 등
Home Assistant 장기 액세스 토큰 발행 방법
MCP 클라이언트가 Home Assistant에 안전하게 접근하기 위해서는 인증이 필요합니다. 두 가지 방법이 있습니다.
OAuth 인증 (권장)
Home Assistant는 IndieAuth 기반의 OAuth를 지원합니다:
- Client ID: 리다이렉트 URI의 base URL (예:
https://www.example.com/mcp/redirect→ Client ID:https://www.example.com) - Client Secret: Home Assistant에서는 사용하지 않음
장기 액세스 토큰 (Long-Lived Access Token)
OAuth를 지원하지 않는 클라이언트를 위한 대안입니다:
- Home Assistant 우측 상단의 사용자 아이콘 클릭
- Security 탭 선택
- Long-lived access tokens 섹션에서 Create Token 클릭
- 토큰 이름 입력 (예: “Claude MCP”)
- 생성된 토큰을 안전한 곳에 복사 및 보관
⚠️ 중요: 생성된 토큰은 한 번만 표시되므로 반드시 안전한 곳에 보관하세요.
mcp_proxy 설치 및 실행
대부분의 MCP 클라이언트는 stdio 프로토콜만 지원하고, Home Assistant MCP Server는 SSE(Server-Sent Events) 프로토콜을 사용하므로 중간에 프록시가 필요합니다.
mcp-proxy 설치
uv tool install git+https://github.com/sparfenyuk/mcp-proxy
설치 확인
which mcp-proxy
mcp-proxy --help
Claude Desktop Configuration 설정
1. Claude Desktop 다운로드 및 설치
Claude Desktop 공식 사이트에서 운영체제에 맞는 버전을 다운로드합니다.
2. 설정 파일 편집
Claude Desktop에서 MCP 서버 설정을 추가해야 합니다:
- Claude Desktop 실행
- Settings > Developer 탭 선택
- Edit Config 클릭하여
claude_desktop_config.json파일 편집
3. 설정 파일 구성
다음 JSON 설정을 추가합니다:
{
"mcpServers": {
"Home Assistant": {
"command": "mcp-proxy",
"env": {
"SSE_URL": "http://localhost:8123/mcp_server/sse",
"API_ACCESS_TOKEN": "여기에_생성한_장기_액세스_토큰_입력"
}
}
}
}
설정 항목 설명:
SSE_URL: Home Assistant MCP 서버의 SSE 엔드포인트 URLAPI_ACCESS_TOKEN: 앞서 생성한 장기 액세스 토큰
💡 팁: Home Assistant가 다른 포트나 호스트에서 실행 중이라면 URL을 적절히 수정하세요 (예:
https://your-domain.com:8123/mcp_server/sse)💡 팁: mcp-proxy의 실행이 되지 않으면, path경로에 mcp-proxy실행이 되도록 설정되었는지 확인하거나, which mcp-proxy로 실행 경로를 확인 후, 그 경로를 그대로 “command”: “실행경로/mcp-proxy”로 설정을 해주세요.
연동 사용 방법
1. Claude Desktop 재시작
설정을 완료한 후 Claude Desktop을 완전히 종료하고 다시 시작합니다.
2. 연결 확인
정상적으로 설정되었다면 Claude Desktop 인터페이스에서 연결 아이콘(🔗)이 표시됩니다. 아이콘을 클릭하면 활성화된 MCP 서버 목록에서 “Home Assistant”를 확인할 수 있습니다.
3. 실제 사용 예시
조명 제어
"거실 조명을 켜줘"
"침실 조명을 50% 밝기로 조절해줘"
"모든 조명을 꺼줘"
기기 상태 확인
"현재 거실 온도가 어떻게 돼?"
"에어컨이 켜져 있나?"
할 일 목록 관리
"할 일 목록에 '세탁기 돌리기' 추가해줘"
"오늘 할 일 목록 보여줘"
스크립트 실행
"좋은 아침 시나리오 실행해줘"
"외출 모드 켜줘"
4. 권한 관리
Claude가 Home Assistant 기능을 사용할 때마다 권한 확인 창이 나타납니다. 신뢰할 수 있는 작업의 경우 “항상 허용”을 선택할 수 있습니다.
연동으로 활용할 수 있는 기능
지원되는 MCP 기능
| 기능 | 지원 여부 |
|---|---|
| Tools | ✅ 지원 |
| Prompts | ✅ 지원 |
| Resources | ❌ 미지원 |
| Sampling | ❌ 미지원 |
| Notifications | ❌ 미지원 |
주요 활용 사례
1. 음성 제어의 진화
기존 음성 비서보다 훨씬 자연스러운 대화로 기기를 제어할 수 있습니다:
- “잠자리에 들 준비를 해줘” → 조명 낮추기, 에어컨 온도 조절, 보안 시스템 활성화
- “영화 모드로 설정해줘” → 거실 조명 조절, TV 켜기, 블라인드 내리기
2. 상황별 자동화
Claude의 학습 능력을 통해 더욱 지능적인 반응이 가능합니다:
- 날씨 정보를 고려한 에어컨 자동 조절
- 일정에 따른 조명 및 음악 자동 설정
- 외출/귀가 패턴 학습 후 맞춤형 환경 조성
3. 복합적 시나리오 실행
여러 기기를 동시에 제어하는 복잡한 시나리오도 자연어로 간단히 실행:
- “파티 준비해줘” → 조명 밝게, 음악 재생, 에어컨 온도 낮추기
- “절약 모드 켜줘” → 불필요한 기기 끄기, 대기전력 차단
시스템 서비스로 mcp-proxy 띄우기
지속적인 연동을 위해 mcp-proxy를 시스템 서비스로 등록할 수 있습니다.
1. 실행 스크립트 작성
sudo mkdir -p /opt/mcp-proxy
sudo tee /opt/mcp-proxy/start.sh << EOF
#!/bin/bash
export SSE_URL="http://localhost:8123/mcp_server/sse"
export API_ACCESS_TOKEN="여기에_토큰_입력"
exec /usr/local/bin/mcp-proxy
EOF
sudo chmod +x /opt/mcp-proxy/start.sh
2. systemd 서비스 파일 생성
sudo tee /etc/systemd/system/mcp-proxy.service << EOF [Unit] Description=MCP Proxy for Home Assistant After=network.target [Service] ExecStart=/opt/mcp-proxy/start.sh Restart=always User=homeassistant Environment=SSE_URL=http://localhost:8123/mcp_server/sse Environment=API_ACCESS_TOKEN=여기에_토큰_입력 [Install] WantedBy=multi-user.target EOF
3. 서비스 활성화 및 실행
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-proxy.service
sudo systemctl status mcp-proxy.service
문제 해결 가이드
1. “Failed to start MCP server” 에러
원인: claude_desktop_config.json 설정 오류 또는 mcp-proxy 실행 불가
해결 방법:
- mcp-proxy 설치 확인:
which mcp-proxy - 설정 파일 JSON 문법 검증
- 직접 명령어 실행 테스트:
mcp-proxy
2. “401 Unauthorized” 에러
원인: 잘못되거나 만료된 액세스 토큰
해결 방법:
- Home Assistant에서 새 장기 액세스 토큰 생성
- 설정 파일의 토큰 정보 업데이트
- Claude Desktop 재시작
3. “404 Not Found” 에러
원인: Home Assistant에 MCP Server 통합이 설정되지 않음
해결 방법:
- Home Assistant에서 Model Context Protocol Server 통합 추가 확인
- Home Assistant 재시작
디버깅 방법
Claude Desktop 로그 확인
- Claude Desktop에서 Settings > Developer 선택
- Home Assistant MCP 서버 선택
- Open Logs Folder 클릭
mcp-server-Home Assistant.log파일 확인
보안 고려사항
1. 액세스 토큰 관리
- 토큰을 안전한 곳에 보관
- 정기적인 토큰 교체 권장
- 불필요한 권한 최소화
2. 노출 엔티티 제한
- 꼭 필요한 기기만 노출
- 중요한 보안 시스템은 제외 고려
- 정기적인 권한 검토
3. 네트워크 보안
- HTTPS 사용 권장 (외부 접속 시)
- 방화벽 설정으로 접근 제한
- VPN 사용 고려 (원격 접속 시)
미래 전망과 활용 가능성
음성 인터페이스의 진화
구글이 2025년 하반기부터 기존 구글 어시스턴트를 Gemini로 전면 교체할 계획을 발표한 만큼, AI 기반 음성 비서의 발전이 가속화될 것으로 예상됩니다. Home Assistant와 MCP 연동은 이러한 변화에 대비한 미래지향적 접근법입니다.
확장 가능한 생태계
MCP 프로토콜을 통해 다양한 AI 모델과 애플리케이션이 Home Assistant와 연동될 수 있어, 단순한 기기 제어를 넘어 진정한 스마트홈 생태계 구축이 가능합니다.
결론
Home Assistant MCP 연동을 통해 Claude와 스마트홈을 연결하면, 기존의 단순한 음성 명령을 넘어서는 지능적이고 유연한 홈 자동화가 가능해집니다. 초기 설정이 다소 복잡할 수 있지만, 한 번 구성하면 자연어를 통한 직관적인 기기 제어와 상황 맞춤형 자동화를 경험할 수 있습니다.
지속적인 홈어시스턴트/AI 발전과 함께 더욱 다양한 기능과 개선된 사용성이 제공될 것으로 기대되며, Home Assistant의 제어 가능한 센서의 범위가 늘어난다면 활용성도 함께 늘어날 것으로 기대됩니다. 다만, 현재 연결된 기능으로는 “조명제어”,”냉난방기 제어”,”미디어 제어”, “스위치, 콘센트 제어”, “ToDoList”,”타이머관리”로 제한적으로 적용할수 있습니다.
보안 향상으로 인해 좀더 많은 센서에 대한 컨트롤이 가능하도록 MCP의 기능 개선이 기대 됩니다.
답글 남기기