Home Assistant MCP 서버란 무엇인가요?

MCP 서버 (Model Context Protocol)는 Claude, ChatGPT 또는 Gemini와 같은 AI가 사용자의 Home Assistant와 직접 대화할 수 있게 해주는 인터페이스입니다. 직접 YAML을 작성하는 대신, AI에게 엔티티 (entities), 자동화 (automations), 대시보드 (dashboards)에 대한 접근 권한을 부여하면 AI가 코드를 처리합니다. Home Assistant OS에서 무료 앱/애드온 (add-on)으로 실행되며, 커뮤니티 프로젝트 (homeassistant-ai/ha-mcp)입니다.

목차

• 필요한 사항
• 공식 vs 비공식 MCP 서버
• 1단계: 앱/애드온으로 MCP 서버 설치하기
• 2단계: 원격 접속 설정하기
• 3단계: MCP 서버를 AI에 연결하기
• AI를 위한 모범 사례 가이드
• 보안: 강화된 Cloudflare 설정과 함께 사용하는 MCP 액세스
• 선택 사항이자 잠재적으로 위험한 요소: AI가 YAML 설정을 편집하도록 허용하기
• 이것으로 실제로 무엇을 만들 수 있는가
• 문제 해결 (Troubleshooting)

Home Assistant는 거의 모든 것을 할 수 있습니다. 바로 그 점 때문에 많은 초보자가 자신만의 자동화를 구축하거나, 대시보드를 설계하거나, 오류를 디버깅하는 데 어려움을 겪습니다. 지금까지는 YAML을 배우고, 템플릿 (templates)을 이해하고, 포럼을 뒤지며 완전히 스스로 해결해야 했습니다. 대신 Home Assistant MCP 서버를 설정하려는 사람은 그 작업을 AI에게 넘겨줄 수 있습니다.

MCP 서버는 이를 근본적으로 변화시킵니다. Home Assistant를 사용자가 선택한 AI인 Claude, ChatGPT 또는 Gemini에 직접 연결하고, 필요한 내용을 일상 언어로 간단히 설명하기만 하면 됩니다: "오늘의 강수량을 보여주는 센서를 만들어줘" 또는 "아이들 방의 자동화가 제대로 작동하지 않아. 조명이 더 이상 제대로 어두워지지 않아, 수정해줘." AI는 스스로 적절한 엔티티를 찾아 코드를 작성하고 Home Assistant에 설정합니다.

이 글에서는 Raspberry Pi에 MCP 서버를 설정하고, 데스크톱 및 스마트폰 접속을 포함하여 Claude, ChatGPT, Gemini에 연결하는 방법과, Home Assistant가 이미 클라이언트 인증서가 있는 Cloudflare Access 뒤에서 실행 중이더라도 전체 시스템을 적절하게 보안 처리하는 방법을 보여드리겠습니다.

필요한 사항

• Raspberry Pi에서 실행되는 Home Assistant OS 또는 Supervised (앱/애드온은 Supervisor가 필요합니다. Home Assistant Container/Core 설치 방식에서는 작동하지 않습니다.)
• App Store 접근 권한 (Settings → Apps - Home Assistant 2026.2 버전부터 기존의 "Add-ons"가 이 이름으로 변경되었습니다. 이전 버전에서는 여전히 Settings → Add-ons → Add-on Store입니다.)
• 클라우드 AI (Claude, ChatGPT)로부터의 접근을 위한 인터넷 연결 방식 - Nabu Casa, 기존의 리버스 프록시 (reverse proxy), 또는 자체 Cloudflare Tunnel
• Claude, ChatGPT 또는 Google Gemini 계정 최소 하나

아직 원격 접속을 설정하지 않았다면, 제 기사인 Set Up Cloudflare Tunnel on the Raspberry Pi에서 mTLS 강화(hardening)를 포함하여 포트 포워딩(port forwarding) 없이 단계별로 다루고 있습니다.

공식(Official) vs 비공식(Unofficial) MCP 서버

Home Assistant는 2025.2 버전부터 자체적인 공식 MCP 서버를 제공해 왔습니다. 설정은 빠르지만, 이 글의 주제인 커뮤니티 솔루션인 ha-mcp보다 기능이 훨씬 제한적입니다. 무엇인가를 설치하기 전에 그 차이점을 알아두어야 합니다:

기능	공식 MCP 서버	비공식 (ha-mcp)
엔티티 (Entity) 접근	Assist에 노출된 엔티티만 가능	시스템 내의 모든 엔티티
...	...	...

단순히 AI를 조금 더 나은 음성 비서(

1. **설정(Settings) → 앱(Apps) → 앱 스토어(App Store)**로 이동합니다 (구 버전 HA의 경우 애드온(Add-ons) → 애드온 스토어(Add-on Store)).
2. 오른쪽 상단의 세 점(...)을 통해 **리포지토리(Repositories)**에 접속하여 URL https://github.com/homeassistant-ai/ha-mcp를 추가합니다.
3. 페이지를 새로고침하고, "Home Assistant MCP Server"를 설치한 다음 실행합니다.

• 
• 
• 

그런 다음 앱의 로그(Logs) 탭을 엽니다. 여기에 사용 준비가 된 MCP 서버 URL이 표시되며, 이미 128비트 무작위 경로로 보호되어 있습니다. 예를 들면 다음과 같습니다:

🔐 MCP Server URL: http://<ha-ip>:9583/private_zctpwlX7ZkIAr7oqdfLPxw

이 URL은 3단계에서 필요합니다. 토큰이나 비밀번호를 직접 생성할 필요는 없습니다. 이 앱은 Home Assistant Supervisor를 통해 자동으로 인증하며, URL의 무작위 경로는 실제 보안 조치입니다.

앱 설정(config 탭 또는 "Open Web UI"를 통한 자체 Tool Settings 웹 UI)에서는 다음을 권장합니다:

• 도구 검색 (enable_tool_search): 기본적으로 비활성화(Disabled)되어 있으며, 그대로 두는 것을 권장합니다. Claude의 Sonnet 또는 Opus 모드를 사용하는 경우, 반드시 비활성화 상태로 두어야 합니다. 그렇지 않으면 Claude의 내장 도구 검색 기능이 ha-mcp의 기능과 충돌하기 때문입니다. 이 기능은 자체 도구 검색 기능이 없는 Claude Haiku 또는 다른 모델을 사용하거나, 클라이언트가 도구의 개수를 제한하는 경우(예: 100개)에만 활성화할 가치가 있습니다.
• 도구 보안 정책 (enable_tool_security_policies): 중요한 작업(잠금 장치, 알람 시스템, 자동화 작성 등)에 대해 앱의 웹 UI를 통한 수동 승인을 원한다면 선택적으로 이 기능을 활성화(enable) 하십시오.
• 읽기 전용 모드 (read_only_mode): 첫 테스트 실행이나 공유 설치 환경에서 유용합니다. 쓰기 권한이 있는 모든 도구를 완전히 차단합니다.
• 백업 힌트 (backup_hint): normal로 설정해 두십시오. 그러면 AI가 되돌릴 수 없는 변경을 수행하기 전에 자동으로 백업을 제안할 것입니다.
• 웹 UI에서 개별 도구가 필요하지 않거나 너무 위험하다고 판단되면 해당 도구를 비활성화하거나 고정(pin)할 수 있습니다.

파트 1이 완료되었습니다. 이제 홈 네트워크 내에서 로컬 URL을 통해 앱과 직접 대화할 수 있습니다 (예: VS Code, Cursor 또는 기타 HTTP 지원 MCP 클라이언트 사용).

2단계: 원격 액세스 설정

Claude 또는 ChatGPT와 같은 클라우드 AI가 귀하의 MCP 서버에 접속하려면, 공개적으로 접근 가능하고 HTTPS로 보안된 URL이 필요합니다. 이를 달성하는 방법에는 두 가지가 있습니다:

옵션 A: Webhook Proxy 앱 (이미 Nabu Casa 또는 리버스 프록시를 사용 중인 경우 가장 쉬운 방법)

"Webhook Proxy for HA MCP" 앱(동일한 리포지토리)은 MCP 트래픽을 귀하가 기존에 사용 중인 Home Assistant 접속 방식(Nabu Casa, Cloudflare Tunnel, DuckDNS 또는 이미 8123 포트를 가리키고 있는 기타 리버스 프록시)을 통해 라우팅합니다. 이를 위해 추가적인 호스트 이름이나 두 번째 터널이 필요하지 않습니다:

1. 1단계에서 수행한 MCP Server 앱이 이미 실행 중이어야 합니다.
2. 동일한 앱 스토어에서 "Webhook Proxy for HA MCP"를 설치하고 시작하십시오.

1. Nabu Casa를 사용하지 않는 경우 (예: 자체 Cloudflare Tunnel 사용), Webhook Proxy 앱의 설정에 공개 Home Assistant URL을 명시적으로 입력해야 합니다. Nabu Casa를 사용하는 경우, 앱이 이를 자동으로 감지합니다.

1. Home Assistant를 재시작합니다 (설정의 오른쪽 상단에서 전체 재시작을 수행하세요)
2. Webhook Proxy 앱의 Logs 탭에서 완성된 원격 URL을 복사합니다. 예:

MCP Server URL (remote): https://<your-external-url>/api/webhook/mcp_7eacf143b0f5d31269417ae3304ee534

앱은 MCP Server 앱을 자동으로 찾아냅니다. Nabu Casa를 사용하면 외부 URL도 자동으로 감지되지만, Nabu Casa를 사용하지 않으면 3단계에 표시된 대로 수동으로 입력해야 합니다. 어떤 방식이든, ID가 로컬에 저장되기 때문에 웹훅 경로 (/api/webhook/mcp_...)는 재시작 후에도 안정적으로 유지됩니다.

옵션 B: 자체 Cloudflared 터널 (원격 접속이 아직 설정되지 않은 경우)

대안으로, 당사의 Cloudflare Tunnel 기사 (Part A)에 설명된 대로 MCP 서버 전용 터널을 사용할 수 있습니다. Cloudflared 앱 설정에서 다음과 같이 구성합니다:

additional_hosts:
  - hostname: ha-mcp.yourdomain.com
    service: http://localhost:9583

만약 Cloudflared 컨테이너(자체 Docker 컨테이너) 내부에서 localhost가 작동하지 않는다면, 대신 MCP Server 앱의 컨테이너 호스트 이름(Info 페이지에서 확인 가능, 예: b37de126-ha-mcp)을 사용하세요.

⚠️ 중요한 Cloudflare 함정: Cloudflare의 "Block AI Training Bots" (AI 학습 봇 차단) 기능은 기본적으로 AI 클라이언트의 접속을 차단합니다. 이는 동일한 URL에 브라우저로 접속했을 때 정상적으로 작동하더라도 마찬가지입니다. Security (보안) → Bots (봇) 메뉴에서 "Block AI training bots" 옵션을 "do not block" (차단하지 않음)으로 설정하지 않으면, 어떤 AI와도 연결할 수 없습니다.

Cloudflare Tunnel 관련 문서에서 설정한 국가 제한(DE/AT/CH)을 설정하셨나요? 동일한 규칙이 Claude와 ChatGPT의 접속도 차단합니다. 두 서비스 모두 미국에서 접속하기 때문입니다. Anthropic의 안정적인 IP 범위인 160.79.104.0/21을 규칙의 예외 사항으로 추가하거나, 국가 규칙의 범위를 메인 호스트 이름으로만 한정하고 MCP 호스트 이름은 그대로 두세요.

Step 3: MCP 서버를 AI에 연결하기

이제 실제 연결 단계입니다. 이 과정이 얼마나 쉬운지, 그리고 어디까지 구현 가능한지는 Claude, ChatGPT, Gemini 간에 상당한 차이가 있습니다:

AI	최소 플랜	설정 위치	데스크톱/모바일
Claude	Free (커넥터 1개), 그 외 Pro/Max	claude.ai (웹), Custom Connector (사용자 정의 커넥터)	데스크톱 앱 및 iOS/Android 앱으로 자동 동기화
...

Claude Desktop 연결하기

Route 1 - 웹 커넥터 (권장, 웹 + 데스크톱 + 스마트폰을 한 번에 설정):

1. claude.ai에 로그인한 후, **Customize (사용자 정의) → Connectors (커넥터)**로 이동합니다. (Customize - Claude)
2. **플러스 아이콘 (+)**을 사용하여 사용자 정의 커넥터를 추가하고, 예를 들어 "Home Assistant"라고 이름을 지정합니다.

1. 2단계에서 확인한 원격 URL을 입력하고 저장합니다.
2. 읽기 전용 (read-only) 도구의 경우 "always allow" (항상 허용)로 설정할 수 있으며, 쓰기/삭제 (write/delete) 도구의 경우 확인 프롬프트를 켜두는 것을 권장합니다.

편리한 점은 claude.ai에서 커넥터를 설정하면 별도의 추가 구성 없이도 Claude Desktop 앱과 iOS 및 Android용 Claude 앱에서 자동으로 사용할 수 있다는 것입니다.

주의사항: 만약 Cloudflare에서 차단 규칙(예: 저는 많은 국가를 차단해 두었습니다)을 설정했다면, 당연히 Claude의 IP 주소들을 허용해 주어야 합니다. 저는 Claude를 위한 건너뛰기(skip) 규칙을 1번 위치에 배치하여, 다른 모든 차단 규칙이 무시되도록 설정했습니다: