Claude와 Home Assistant를 MCP로 연결하는 방법
Home Assistant 2025.2 버전부터 지원하는 MCP 서버를 사용하여 Claude에서 스마트홈 기기를 제어하는 방법을 설명합니다. 보안을 위해 읽기 전용 계정을 설정하고 공용 HTTPS 주소를 안전하게 구성하는 단계별 가이드를 확인하십시오.
MCP를 사용하여 Claude를 Home Assistant에 연결하는 방법
MCP를 사용하여 Claude를 Home Assistant에 연결하려면, Home Assistant의 내장 Model Context Protocol 통합을 활성화하고 해당 주소를 Claude에 사용자 지정 커넥터로 추가하십시오. 그러면 Claude는 Home Assistant 자체의 OAuth 로그인을 통해 인증합니다. OAuth는 비밀번호를 공유하지 않고도 앱에 접근 권한을 부여하기 위한 개방형 표준입니다. 먼저 Home Assistant에 공개 HTTPS 주소가 필요합니다. Claude Desktop을 사용하더라도 Claude는 Anthropic의 클라우드에서 사용자의 가정으로 접근하므로, 이 주소를 설정하는 것이 작업의 대부분을 차지합니다.
MCP(Model Context Protocol)는 AI 클라이언트가 다른 서버의 도구를 호출할 수 있게 해주는 개방형 표준입니다. Home Assistant는 2025.2 릴리스부터 MCP 서버 통합을 제공하고 있습니다. 이 도구들은 가정의 상태를 읽을 수 있으며, 적절한 옵션을 설정하면 제어까지 가능합니다. 따라서 가장 중요한 결정 사항은 보안입니다. 사용자가 개방한 주소에 누가 접근할 수 있는지, 그리고 그 뒤에 있는 계정에 어떤 권한이 허용되는지를 고려해야 합니다. Claude를 확장하는 다른 방법들 중에서 MCP가 적합한지 고민 중이라면, MCP와 에이전트 기술 및 규칙 파일 비교를 먼저 확인하십시오.
이 가이드는 2026년 11월 22일 기준으로 Home Assistant, Anthropic, Tailscale, Caddy 및 Nabu Casa 문서를 검토하여 작성되었습니다. 해당 일자의 최신 Home Assistant 릴리스는 2026.11.2였습니다. 아래의 몇 가지 옵션은 도입된 지 얼마 되지 않았으므로, 시작하기 전에 Home Assistant를 업데이트하십시오.
Claude에서 Home Assistant를 공용 인터넷에 연결해야 하는 이유
Anthropic의 custom connectors 도움말에는 다음과 같이 명시되어 있다. "Claude는 로컬 장치가 아니라 Anthropic의 클라우드 인프라에서 원격 MCP 서버에 연결한다." Home Assistant 문서도 desktop app에 대해 같은 내용을 설명한다. "Claude Desktop을 사용할 때도 Claude는 클라우드에서 MCP 서버에 연결한다."
이로부터 2가지 요구 사항이 따른다. 서버는 Anthropic의 IP 범위에서 공용 인터넷을 통해 접근할 수 있어야 한다. 또한 표준 HTTPS 포트인 443에서 응답해야 한다. 따라서 http://homeassistant.local:8123는 connector URL로 사용할 수 없다. Anthropic의 서버는 홈 네트워크에만 존재하는 이름을 확인할 수 없으며, 포트 8123은 443이 아니다.
Claude Desktop에는 두 번째 방식도 있다. claude_desktop_config.json에 나열된 로컬 MCP 서버는 로컬 네트워크를 사용한다. 이 서버는 connector와 별개이며, claude.ai 또는 클라우드에서 실행되는 Cowork 세션에서는 사용할 수 없다. Home Assistant 문서는 Claude Desktop에 대해 connector 경로만 설명하므로, 이 가이드에서도 해당 경로를 사용한다.
Claude Code는 다르다. Claude Code는 사용자의 컴퓨터 또는 서버에서 실행되며 MCP 연결도 직접 연다. 따라서 URL은 해당 컴퓨터에서 접근할 수 있기만 하면 된다. Home Assistant는 "Claude Code는 HTTPS를 통해서만 MCP 서버에 연결한다"고 설명한다. 따라서 자체 네트워크 내부의 비공개 HTTPS 주소도 사용할 수 있다. Tailscale Serve와 Tailscale Funnel의 차이는 바로 이 선택에 해당한다. Serve는 tailnet에서 사용하는 비공개 HTTPS 주소를 제공하고, Funnel은 공용 주소를 제공한다.
Custom connectors는 Free, Pro, Max, Ultra, Team 및 Enterprise 요금제에서 사용할 수 있다. Free 사용자는 custom connector를 1개만 사용할 수 있다. 이는 Claude Free 요금제에 포함된 기능에서 설명하는 제한 사항 중 하나다.
MCP Server 통합 활성화
- Home Assistant에서 Settings > Devices & services로 이동한 다음 Add Integration을 선택합니다.
- 목록에서 Model Context Protocol을 선택하고 화면에 표시되는 단계를 따릅니다.
- Settings > System > AI로 이동합니다. Model Context Protocol 카드에 Enable 버튼이 표시되면 선택합니다.
- Main URL을 복사합니다. 경로는
/api/mcp입니다.
전체 커넥터 URL은 공개 호스트 이름과 해당 경로를 결합한 값입니다. 예를 들면 https://ha.example.com/api/mcp과 같습니다. 호스트 이름은 아래에서 선택하는 액세스 경로에 따라 달라집니다.
메인 URL이 기본적으로 노출하는 항목
메인 URL에는 세 가지 옵션이 있으며, 이는 /api/mcp에만 적용됩니다. 무언가를 연결하기 전에 이 내용을 읽어 보십시오.
- 모든 AI 도구 노출(Expose all AI tools)은 기본적으로 켜져 있습니다. 이 상태에서 메인 URL은 통합 구성 요소가 나중에 추가하는 도구 세트를 포함하여 모든 도구 세트를 노출합니다. 그중 하나인 Home Assistant 세트는 모든 엔티티, 로그, 기록을 읽고 모든 작업을 수행할 수 있습니다.
- 관리자 계정 필요(Require an administrator account)는 기본적으로 켜져 있습니다. 메인 URL이 Home Assistant 세트를 노출할 때, 이 스위치 설정과 관계없이 항상 관리자 계정이 필요합니다.
- 읽기 전용(Read-only)은 기본적으로 꺼져 있습니다. 이 옵션을 켜면 메인 URL은 현재 가정 상태를 확인하는 것과 같이 아무것도 변경하지 않는 도구만 노출합니다.
- 이전 설정에서는 이 스위치 중 두 개가 꺼진 상태로 유지됩니다. '모든 AI 도구 노출'에 대해 문서에서는 "사용자가 선택한 AI 도구 세트를 클라이언트가 유지할 수 있도록 꺼진 상태로 유지된다"고 설명합니다. 관리자 스위치는 "클라이언트가 계속 작동할 수 있도록 꺼진 상태로 유지됩니다." 사용 중인 MCP Server 항목이 이 옵션들보다 오래된 경우, 해당 옵션을 열어 확인하십시오.
도구 세트를 하나씩 선택하려면 '모든 AI 도구 노출'을 끄십시오. 장치 제어(Device control) 세트는 음성 비서와 동일한 도구를 AI에 제공하며, "음성 비서에 노출한 엔티티에만 접근"합니다. Home Assistant 세트에는 이러한 제한이 없습니다.
단일 도구 세트를 위한 별도의 URL도 존재합니다. /api/mcp/assist는 장치 제어 기능만 노출합니다. 이 URL들은 위의 세 가지 옵션을 무시합니다. 이들은 결코 읽기 전용으로 작동하지 않습니다. 장치 제어 URL을 제외한 모든 URL은 관리자 계정을 요구합니다.
장치 제어 기능을 신뢰하기 전에 해당 기능이 어디까지 접근할 수 있는지 확인하십시오. Assist는 기본적으로 새로운 엔티티를 노출하며, 여기에는 커버(covers)가 포함됩니다. Home Assistant 문서에는 "커버에는 차고 문과 게이트가 포함되므로 Home Assistant도 이를 자동으로 노출한다"고 명시되어 있습니다. 잠금 장치, 경보 패널, 스크립트는 자동으로 노출되지 않습니다. Assist 노출 설정을 열고 채팅 창에서 열리기를 원하지 않는 엔티티를 제거하십시오.
소유자 계정이 아닌 전용 계정 사용
Claude에서 Connect를 선택하면 브라우저를 통해 Home Assistant에 로그인하게 됩니다. 이때 Claude가 부여받는 접근 권한은 로그인한 계정의 권한과 동일합니다. 소유자 계정으로 로그인하면 Claude는 소유자와 동일한 모든 권한을 가지고 동작하게 됩니다.
Home Assistant에 별도의 사용자를 생성하여 전용 로그인 정보를 부여하고, 이를 Claude 전용으로만 사용하십시오. 나중에 Claude의 접근 권한을 취소해야 할 경우 해당 계정만 삭제하면 되며, 본인의 계정은 영향을 받지 않습니다. 이후 다음 두 가지 설정 중 하나를 선택하십시오.
제한적 설정: Claude가 일부 기기만 제어하는 경우. 해당 계정을 관리자가 아닌 일반 사용자로 유지하십시오. 기본 URL 옵션에서 Expose all AI tools를 끄고, Device control만 선택한 뒤 Require an administrator account를 비활성화하십시오. 이렇게 하면 Claude는 음성 제어가 허용된 엔티티에만 접근할 수 있습니다. Claude가 상태 보고만 수행해야 한다면 Read-only 옵션도 함께 켜십시오. 관리자 권한이 필요 없는 /api/mcp/assist를 사용할 수도 있습니다. 단, 해당 URL은 Read-only 스위치를 무시합니다.
광범위한 설정: Claude가 로그와 기록을 읽는 경우. Home Assistant 도구 세트는 항상 관리자 계정을 필요로 합니다. 전용 계정을 관리자로 설정하되 소유자 계정과 분리하여 유지하고, Read-only를 켜십시오. 이렇게 하면 Claude는 엔티티, 로그, 기록을 읽을 수 있습니다. 상태를 변경하는 도구는 노출되지 않습니다.
Connect 단계에서는 어떤 계정으로 로그인하는지 확인하십시오. 개인 정보 보호 브라우저 창에서 이 단계를 진행하면 실수로 소유자 세션이 재사용되는 것을 방지할 수 있습니다.
클라이언트의 승인 프롬프트에만 의존하여 보안을 확보하지 마십시오. Home Assistant 문서에 따르면, 항상 허용하도록 설정하지 않는 한 Claude는 도구를 호출하기 전에 권한을 요청합니다. Claude Code는 이와 다릅니다. v2.1.283 버전부터 대화형 터미널 및 VS Code 세션의 기본 권한 모드는 auto 모드이며, auto 모드에서는 모든 동작마다 승인을 요청하지 않습니다. 클라이언트의 설정과 관계없이 Home Assistant 자체적으로 해당 계정의 권한과 Read-only 스위치를 강제 적용합니다.
Claude의 클라우드는 어떻게 Home Assistant에 도달해야 합니까?
이 섹션의 나머지 부분은 각 서비스의 문서를 바탕으로 작성한 이 가이드만의 위협 모델입니다. 아래의 보안 비교는 벤더의 주장이 아닌 논리적 추론으로 간주하십시오.
아래의 모든 경로에는 공통점이 있습니다. URL에 도달할 수 있는 사람은 누구나 Home Assistant 로그인 페이지에 접근할 수 있다는 점입니다. 따라서 가장 먼저 로그인 보호를 설정하십시오. Settings > System > Network의 HTTP server 섹션에서 Enable IP banning을 켭니다. 그런 다음 Login attempts before ban을 설정하십시오. 이 값은 1에서 1000까지 설정할 수 있으며, Unlimited login attempts가 꺼져 있을 때만 나타납니다. 프록시나 터널을 사용하는 경우 Trust X-Forwarded-For를 켜고 프록시의 주소를 Trusted proxies에 추가하십시오. Home Assistant 문서는 "이 옵션들을 설정하지 않으면 리버스 프록시로부터의 요청이 차단된다"고 경고합니다. Home Assistant 2026.8 이전 버전에서는 이 설정들이 configuration.yaml의 http: 블록에 있었습니다.
아래 예시들은 Home Assistant 포트 8123을 사용합니다. Home Assistant 2026.8부터는 Home Assistant Operating System의 기본 포트가 80이고 Container는 8123이므로, 나타나는 모든 곳에서 8123을 사용자가 설정한 포트로 바꾸십시오.
Nabu Casa 원격 UI (Home Assistant Link)
Nabu Casa의 서비스는 이제 Home Assistant Link(이전 명칭 Home Assistant Cloud)로 불립니다. 2026년 11월 15일 기준 가격 페이지에는 세금을 제외하고 월 6.50 USD 또는 연 65.00 USD로 기재되어 있습니다. 또한 카드 정보가 필요 없는 31일 무료 체험도 제공합니다. 원격 접속은 나열된 혜택 중 하나입니다.
노출 범위: 공개 HTTPS 주소에서 전체 Home Assistant 웹 인터페이스와 로그인 페이지가 노출됩니다. 보장하지 않는 범위: Claude가 사용하는 계정의 취약한 비밀번호나 다른 곳에서 유출된 토큰은 보호하지 않습니다. Nabu Casa의 지원 문서에 따르면 원격 접속은 종단간 암호화(end-to-end encryption)를 사용하며, 개인 키는 사용자의 Home Assistant 시스템에만 저장되므로 릴레이 서버는 데이터를 읽을 수 없습니다.
Tailscale Funnel
Funnel은 공용 인터넷에서 로컬 서비스로 트래픽을 라우팅하며, Tailscale은 모든 플랜에서 이를 지원한다고 밝히고 있습니다. 이를 위해서는 Tailscale v1.38.3 이상, MagicDNS, 테일넷(tailnet)을 위한 유효한 HTTPS 인증서, 그리고 테일넷 정책 파일의 funnel 노드 속성이 필요합니다. 포트는 443, 8443, 10000번만 수신할 수 있습니다. Claude가 필요로 하는 포트는 443번입니다. 이러한 요구 사항이 생소하다면 Tailscale이란 무엇이며 테일넷이 어떻게 작동하는지를 참조하십시오. Home Assistant를 실행하는 머신에서 다음 명령을 실행하십시오.
sudo tailscale funnel 8123Tailscale은 http://127.0.0.1:8123로 프록시되는 공용 https://<machine>.<tailnet>.ts.net 주소를 출력합니다. 커넥터 URL에 해당 호스트 이름을 사용하십시오. 모든 요청이 로컬 Tailscale 프록시로부터 오게 되므로 127.0.0.1을 Home Assistant의 Trusted proxies에 추가하십시오. 이 명령은 Ctrl+C를 누를 때까지 포그라운드에서 실행됩니다.
노출 범위: 인터넷상의 누구에게나 전체 Home Assistant 포트가 노출됩니다. Funnel 방문자는 Tailscale이 필요 없으므로, 사용자의 사설 테일넷은 그들에게 추가적인 장벽이 되지 않습니다. 또한 Funnel 트래픽에는 설정할 수 없는 대역폭 제한이 있습니다.
Cloudflare Tunnel
Cloudflare Tunnel은 아웃바운드 전용 연결을 사용합니다. 네트워크 내부의 cloudflared 데몬이 Cloudflare로 연결을 시도하므로, 인바운드 포트를 열 필요가 없으며 가정 내 공인 IP도 필요하지 않습니다.
노출 범위: 규칙을 추가하지 않는 한, 게시한 호스트 이름이 전체 인터넷에 노출됩니다. 사용자가 Cloudflare에서 먼저 로그인하도록 만드는 규칙을 적용할 경우, Anthropic의 게시된 IP 대역을 통과시켜야 합니다. Claude의 클라우드는 로그인 페이지를 입력할 수 없으므로, MCP 요청이 Cloudflare에서 멈추게 됩니다. cloudflared가 Home Assistant에 도달하기 위해 사용하는 주소를 Trusted proxies에 추가하십시오.
VPS를 이용한 리버스 프록시
이 경로를 사용하면 인터넷에 노출되는 서버를 직접 제어할 수 있습니다. 공인 IP를 가진 소형 VPS(가상 사설 서버)에서 리버스 프록시를 실행하고, 테일넷과 같은 사설 링크를 통해 가정 내 Home Assistant에 도달합니다. 가정 내의 어떤 포트도 인터넷에 열리지 않습니다. 또한 프록시에 접근할 수 있는 대상을 제한할 수도 있습니다.
Anthropic은 "외부 서버에 MCP 도구 호출을 할 때"와 같이 아웃바운드 요청에 사용하는 IP 주소를 공개합니다. 2026년 11월 15일 기준 해당 페이지에는 CIDR 형식의 두 가지 아웃바운드 IPv4 대역이 나열되어 있으며, 아웃바운드 IPv6 대역은 없습니다. 설정하는 날 Anthropic의 IP 주소 페이지에서 현재 대역을 복사하십시오. 해당 페이지에는 더 이상 사용되지 않는 이전 주소들도 나열되어 있으므로, 현재 사용 중인 아웃바운드 주소만 가져와야 합니다.
VPS에 Caddy가 설치된 상태에서, /etc/caddy/Caddyfile은 해당 대역에서 오지 않는 모든 연결을 차단할 수 있습니다.
ha.example.com {
@blocked not remote_ip <anthropic-range-1> <anthropic-range-2> 203.0.113.25
abort @blocked
reverse_proxy 100.101.102.103:8123
}<anthropic-range-1>와 <anthropic-range-2>를 Anthropic 페이지의 아웃바운드 IPv4 대역으로, 203.0.113.25을 사용자의 공인 IP로, 100.101.102.103을 테일넷상의 Home Assistant 주소로 바꾸십시오. 사용자의 IP가 목록에 포함된 이유는 Connect 단계에서 브라우저를 통해 Home Assistant 로그인 페이지를 열기 때문입니다. 해당 요청은 Anthropic이 아닌 사용자로부터 옵니다. Connect가 로딩되지 않고 멈춘다면 목록에 사용자의 주소가 빠진 것입니다. Caddy는 기본적으로 X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host 헤더를 설정하며 WebSocket 연결을 프록시합니다. 또한 호스트 이름의 DNS 레코드가 VPS를 가리키고 Caddy가 인증 기관의 검증 챌린지를 완료할 수 있다면, 해당 호스트 이름에 대한 TLS(전송 계층 보안) 인증서를 획득합니다.
caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddycaddy validate은 오류 없이 완료되어야 합니다. 목록에 없는 주소에서 curl -I https://ha.example.com/를 시도하면 abort이 연결을 종료하므로 어떠한 HTTP 응답도 받을 수 없습니다. 마지막으로, VPS의 테일넷 주소를 Home Assistant의 Trusted proxies에 추가하십시오.
보호되지 않는 범위: 모든 Claude 사용자는 Anthropic의 IP 대역을 공유합니다. 허용 목록(allowlist)은 무작위 스캐너를 차단할 뿐입니다. URL을 알아내어 자신의 커넥터로 추가한 사람은 여전히 로그인 페이지에 도달할 수 있으므로, 계정 비밀번호와 IP 차단 설정은 여전히 중요합니다. 또한 이제는 VPS의 보안 패치를 직접 관리해야 합니다.
어떤 경로를 선택해야 하는가
Nabu Casa는 설정이 가장 간편하며 별도의 서버가 필요하지 않습니다. Funnel과 Cloudflare Tunnel은 가정 내 포트를 열지 않아도 되지만, 둘 다 로그인 페이지 전체를 공개 인터넷에 노출합니다. VPS 프록시는 작업량이 가장 많지만, Anthropic의 대역과 사용자의 주소만 연결을 열 수 있으므로 노출 범위가 가장 작습니다. 어떤 경로를 선택하든, 전용 계정과 Read-only 스위치를 사용하는 것이 경로 선택보다 더 큰 보호 효과를 제공합니다.
Claude에 커넥터 추가하기
- claude.ai에서 Customize > Connectors를 열고 + Add > Add custom connector를 선택합니다. Claude Desktop의 경우 Home Assistant 문서에 따라 Settings > Connectors로 이동한 뒤 Add > Add custom connector를 선택합니다.
- 이름을
Home Assistant로 지정하고 전체 URL(예:https://ha.example.com/api/mcp)을 붙여넣습니다. URL을 제출하면 Claude가 서버를 확인하고 인증 설정을 표시합니다. - Authentication을 Sign in now로, OAuth client를 Use Claude's published identity로 설정한 뒤 Add를 선택합니다.
- 새 커넥터 페이지에서 Connect를 선택하고 전용 계정으로 Home Assistant에 로그인합니다.
Team 또는 Enterprise 플랜을 사용하는 경우, 소유자(Owner)가 Organization settings > Connectors에서 커넥터를 추가합니다. 이후 각 구성원은 Customize > Connectors에서 해당 커넥터를 찾아 Connect를 선택하며, 각자 Home Assistant 로그인 과정을 거치게 됩니다.
Home Assistant의 OAuth 처리 방식 때문에 게시된 ID(published identity)를 선택해야 합니다. Home Assistant는 PKCE(Proof Key for Code Exchange)를 사용하는 OAuth 2.0을 구현합니다. 이 방식은 OAuth Client ID Metadata Documents를 지원하므로 클라이언트 ID와 콜백 URL이 자동으로 설정됩니다. Home Assistant는 클라이언트 시크릿(client secret)을 사용하지 않습니다. 또한 RFC 7591 동적 클라이언트 등록(Dynamic Client Registration)을 지원하지 않으며, 문서에 따르면 이를 엄격하게 요구하는 클라이언트는 "자동으로 등록할 수 없습니다." 다른 MCP 클라이언트의 경우, 문서에서는 클라이언트 ID가 클라이언트 애플리케이션의 기본 URL이어야 하며, "절대로 Home Assistant 인스턴스 URL이 되어서는 안 된다"고 명시하고 있습니다.
Claude Code에 Home Assistant 추가
claude mcp add --transport http home-assistant https://ha.example.com/api/mcp
claude mcp login home-assistantclaude mcp login은 셸에서 서버의 OAuth 흐름을 실행합니다. 원격 서버의 SSH 세션에서는 --no-browser도 사용할 수 있습니다. 기본적으로 claude mcp add은 로컬 범위를 사용하므로, 이 서버는 이 컴퓨터의 현재 프로젝트에서만 사용할 수 있습니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user을 추가합니다. Claude Code 내부에서 /mcp로 서버 연결 여부를 확인할 수 있습니다. Claude Code가 Linux에서 실행되고 아직 설정하지 않았다면 Linux 데스크톱과 CLI에서 Claude 실행에서 설치 방법을 설명합니다.
장기 토큰인가 OAuth인가: 이전 가이드가 의미하는 것은 무엇인가?
이전 가이드에서는 장기 액세스 토큰(Long-lived access token)을 생성하라고 안내합니다. 해당 가이드가 작성되었을 당시에는 그것이 올바른 방법이었습니다. Home Assistant의 특정 릴리스 하나가 토큰 방식에서 OAuth 방식으로 한 번에 전환된 것은 아닙니다. 이 변화는 단계적으로 이루어졌습니다.
- 2025.2 버전을 대상으로 작성된 초기 MCP Server 문서에는 "현재로서는 API 접근 제어를 위해 장기 액세스 토큰을 사용할 수 있습니다."라고 명시되어 있습니다.
- S256 방식을 사용하는 PKCE는 Home Assistant 소스 코드의 2026.10.0 태그에서 처음 등장합니다. 2026.9.0 버전의 소스 코드에는 포함되어 있지 않습니다.
- 현재의 MCP Server 페이지에는 장기 토큰에 대한 언급이 없습니다.
요청 헤더에 토큰을 직접 붙여넣는 방식의 가이드는 이전 설정을 설명하는 것입니다. 대신 위에 제시된 최신 OAuth 단계를 사용하십시오.
커뮤니티 ha-mcp 서버를 선택하는 것이 더 나은 경우는 언제입니까?
ha-mcp는 MIT 라이선스를 따르는 별도의 프로젝트입니다. v9.2.0 태그의 README에는 87개의 도구가 나열되어 있습니다. 기본 브랜치의 README에도 87개로 명시되어 있으나, 이전 v9.3.0.dev3663 README에서는 86개였으므로 빌드마다 개수가 달라집니다. 내장 도구 세트보다 더 많고 목적에 특화된 도구 목록이 필요하고, 다른 자격 증명 모델을 수용할 수 있다면 ha-mcp를 선택하십시오.
v9.2.0에서 권장하는 설치 방법은 HA-MCP 통합 구성 요소입니다. 이는 Home Assistant 내부에서 실행되며 Home Assistant 2026.8.0 이상 버전이 필요합니다. 2026.8에서 2026.10 버전까지는 HACS(Home Assistant Community Store)를 통해 설치합니다. 2026.11 버전부터는 Settings > Marketplace에서 설치할 수 있습니다. 재시작 후 Settings > Devices & services > Add Integration에서 HA-MCP Server를 추가하십시오. 이 통합 구성 요소는 관리자 권한으로 동작하며, 프로젝트 문서에서는 전용 HA-MCP 계정 사용을 권장합니다. 이 프로젝트는 Docker 이미지, PyPI 패키지, Home Assistant 앱(애드온)을 제공하며, README에는 테스트 전용인 로컬 stdio 모드에 대한 설명이 포함되어 있습니다.
안정적인 릴리스 고정
2026년 11월 22일 기준 최신 안정 릴리스는 11월 11일에 게시된 v9.2.0입니다. 개발 빌드(.devN)는 master 브랜치에 푸시될 때마다 게시됩니다. 프로젝트 측의 권고는 명확합니다. "개발 릴리스(.devN)에는 버그가 포함될 수 있습니다. 운영 환경에서는 안정적인 릴리스를 사용하십시오." .devN 빌드가 아닌 v9.2.0 릴리스를 설치하십시오. Docker 이미지의 :latest 및 :stable 태그는 안정적인 릴리스를 추적하며 개발 빌드를 포함하지 않습니다. uvx로 실행할 경우 README의 명령은 @latest로 끝납니다. 이를 @9.2.0으로 교체하십시오. uv의 @ 구문은 정확한 버전을 요구하기 때문입니다. PyPI 패키지는 Python 3.13 또는 3.14가 필요합니다.
private_ URL이 곧 비밀번호입니다
내장 서버는 Claude가 로그인하도록 요구하지만, ha-mcp의 비밀 URL 모드에서는 그렇지 않습니다. 네트워크 내부에서 주소는 http://<ha-ip>:9584/private_<random>와 같은 형태입니다. 원격에서는 https://<your-ha-domain>/api/webhook/<webhook-id>과 같은 웹훅 URL을 사용합니다. 프로젝트 문서에서는 "경로 자체가 자격 증명"이라고 명시하며, "URL을 비밀번호처럼 취급하십시오. 공유하거나 로그에 남을 수 있는 곳에 붙여넣지 마십시오"라고 경고합니다. 전체 URL을 가진 사람은 누구나 MCP 서버에 접근할 수 있으며, 중간에 로그인 페이지가 존재하지 않습니다.
이는 위협 모델을 변화시킵니다. 공유 채팅에 붙여넣거나 프록시 로그에 남겨진 URL은 전체 접근 권한을 제공합니다. URL이 유출되면 새로운 웹훅 ID를 생성하여 교체하십시오. 엔드포인트 끝에 /readonly을 추가하면 쓰기 도구를 숨기고 쓰기 호출을 차단하는 연결을 얻을 수 있습니다. 동일한 자격 증명이 일반 엔드포인트에서도 작동하므로, 이 접미사가 URL을 가진 사람의 접근 권한을 제한하지는 않습니다. 원격 접근은 Nabu Casa 원격 UI 또는 이미 운영 중인 리버스 프록시를 통해 가능합니다. Cloudflare Tunnel의 경우 README에서 설정 마법사를 참조하도록 안내합니다.
ha-mcp에는 베타로 표시된 OAuth 모드도 있습니다. 이 모드는 여전히 각 사용자에게 Home Assistant 장기 액세스 토큰을 동의 양식에 붙여넣도록 요구합니다. 이는 내장 서버의 로그인 방식과는 다른 메커니즘입니다. 또한 이 통합 구성 요소는 Home Assistant의 자체 로그인을 사용하고 관리자 계정만 허용하는 ha_auth 기능을 제공합니다.
커넥터가 로그인하지 못하는 이유는 무엇입니까?
로그인 페이지가 표시되지 않거나 Claude에서 서버에 연결할 수 없다고 합니다. Anthropic의 클라우드에서 해당 URL에 연결할 수 없습니다. 홈 네트워크 외부의 네트워크에서 port 443으로 테스트하고, allowlist를 사용하는 경우 해당 목록을 확인합니다.
프록시 뒤에서 OAuth 오류와 함께 로그인이 실패합니다. Home Assistant 문서에서는 원인을 명시합니다. 리버스 프록시 헤더(X-Forwarded-Host, X-Forwarded-Proto)가 없거나 값이 일치하지 않습니다. 문서에는 "규격을 준수하는 OAuth 클라이언트는 이 메타데이터를 거부합니다."라고도 설명되어 있습니다. Home Assistant가 생성하는 URL은 Claude가 사용한 정확한 hostname과 scheme과 일치해야 합니다. 프록시 헤더와 Trusted proxies 설정을 수정합니다.
/register에 대한 요청이 404를 반환합니다. 클라이언트가 Dynamic Client Registration을 시도했지만 Home Assistant는 이를 지원하지 않습니다. Claude에서 OAuth client를 Use Claude's published identity로 설정합니다.
알려진 미해결 문제입니다. 2026년 11월 15일, issue #183050에서는 Core 2026.11.0에서 /api/mcp에 연결할 때 claude.ai connector가 실패한다고 보고했습니다. 이 문제는 아직 열려 있고 추가 정보가 필요하다고 표시되어 있으며, 확인된 해결 방법은 없습니다. connector에 의존하기 전에 테스트합니다.
FAQ
Claude Desktop은 내 컴퓨터에서 Home Assistant에 연결합니까?
사용자 지정 커넥터에서는 그렇지 않습니다. Anthropic과 Home Assistant 모두 Claude가 Claude Desktop에서도 Anthropic의 클라우드에서 연결한다고 설명합니다. 따라서 Home Assistant에는 포트 443에서 연결할 수 있는 공용 HTTPS 주소가 필요합니다. 예외는 claude_desktop_config.json의 로컬 서버와 Claude Code입니다. 이 경우에는 사용자의 컴퓨터에서 연결합니다.
Claude가 Home Assistant MCP를 통해 차고 문을 열 수 있습니까?
계정과 도구 세트가 허용하면 가능합니다. Assist는 기본적으로 새 cover를 노출하며, cover에는 차고 문과 게이트가 포함되므로 Device control 도구 세트에서 보통 해당 장치에 접근할 수 있습니다. Home Assistant 도구 세트는 모든 작업을 수행할 수 있습니다. Claude가 해당 장치를 움직이지 못하게 하려면 Assist 노출에서 해당 엔터티를 제거하거나 기본 URL에서 Read-only를 활성화하십시오.
Home Assistant MCP 서버에 long-lived access token이 여전히 필요합니까?
내장 서버에는 필요하지 않습니다. 현재 문서는 PKCE를 사용하는 OAuth 2.0을 사용하며 long-lived token을 언급하지 않습니다. 토큰은 최초 2025.2 문서에서 사용한 방식입니다. 커뮤니티의 ha-mcp 서버는 다릅니다. 이 서버의 beta OAuth 모드에서는 여전히 long-lived token을 붙여 넣어야 합니다.
커넥터가 여러 번 실패한 뒤 Home Assistant에 로그인할 수 없게 되었습니다. 어떻게 된 것입니까?
로그인에 실패한 주소가 IP 차단으로 차단된 것입니다. Home Assistant 문서에 따르면 가장 가능성 높은 원인은 client ID 또는 Home Assistant URL과 같은 OAuth 설정이 잘못된 경우입니다. Home Assistant 구성 디렉터리에서 ip_bans.yaml을 열고 차단된 주소의 항목을 제거한 다음 Home Assistant를 다시 시작하십시오. 다시 시도하기 전에 커넥터 설정을 수정하십시오.