MCP Proxy를 Claude 연동 AI와 함께하는 스마트 홈 생활 자동화 (Home Assistant)

Home Assistant에서 Model Context Protocol Server(MCP 서버)를 구성하여 AI(예: Claude, Cursor 등)와 연계하는 방법입니다.

🧠 Model Context Protocol(MCP)이란?

Model Context Protocol은 LLM(Large Language Model)이 외부 애플리케이션의 컨텍스트를 받아 활용할 수 있도록 표준화된 인터페이스를 제공하는 오픈 프로토콜입니다.

예: Claude 데스크탑 앱이 Home Assistant의 할 일 목록(Google Tasks)을 도구로 사용하여 제어할 수 있음.

🏡 Home Assistant에 MCP Server 구성하기

1. ✅ 요구 조건 (Prerequisites)

• LLM 애플리케이션 (예: Claude Desktop, Cursor) 설치
• 로컬 MCP 프록시 서버 설치 필요
• Home Assistant 설치 및 접근 가능

대부분의 LLM 애플리케이션은 원격 MCP 서버 직접 연결 미지원 → mcp-proxy 필요

2. 🛠 Home Assistant 설정

A. MCP Server 통합 추가

• Home Assistant에서 “Model Context Protocol Server” 통합을 추가
  • 설정 > Devices & Services > Add Integration > Model Context Protocol Server

B. 노출할 엔티티 설정

• Home Assistant > Settings > Voice Assistants > Exposed Entities
  • Claude나 Cursor 등 LLM 클라이언트가 접근할 수 있는 엔티티(조명, 센서, 할 일 목록 등) 설정

3. 🔐 인증 설정

A. OAuth 인증 (권장)

• Home Assistant는 IndieAuth 기반 OAuth 지원
• Client ID는 리다이렉트 URI의 base URL
  • 예: https://www.example.com/mcp/redirect → Client ID: https://www.example.com
• Client Secret은 필요 없음

B. 장기 Access Token (Long-Lived Token)

• Home Assistant > 프로필 > Security > Long-lived access token 생성
• Claude 등에서 OAuth 미지원 시 사용 가능

💻 Claude for Desktop 연동하기

1. Claude 설치 및 mcp-proxy 구성

uv tool install git+https://github.com/sparfenyuk/mcp-proxy

2. claude_desktop_config.json 수정

{
  "mcpServers": {
    "Home Assistant": {
      "command": "mcp-proxy",
      "env": {
        "SSE_URL": "http://localhost:8123/mcp_server/sse",
        "API_ACCESS_TOKEN": "<your_access_token_here>"
      }
    }
  }
}

SSE_URL은 Home Assistant MCP 서버 SSE 주소이며, 포트 및 호스트 정보는 실제 구성에 맞춰 조정 필요

3. Claude 재시작 및 MCP 연결 확인

• 설정 > Developer > Home Assistant MCP 서버 > 로그 확인
• 연결에 성공하면 Claude의 도구 창에서 Home Assistant가 도구로 노출됨

🖥 Cursor 연동하기

1. Cursor 설치 및 MCP 설정

{
  "mcpServers": {
    "Home Assistant": {
      "command": "mcp-proxy",
      "args": [
        "http://localhost:8123/mcp_server/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<your_access_token_here>"
      }
    }
  }
}

• 파일 위치: $HOME/.cursor/mcp.json
• Cursor 재시작 후 Ctrl+I를 눌러 에이전트 모드 진입 → Home Assistant 도구 사용 가능

⚙️ 구조 및 동작 방식 요약

구성 요소	역할
MCP Server (Home Assistant)	SSE 프로토콜로 클라이언트 요청 수신
LLM 클라이언트 (Claude 등)	stdio 전용이므로 MCP Proxy 서버 통해 중계 필요
mcp-proxy	stdio ↔ SSE 중계 역할 수행
Access Token / OAuth	API 인증을 위한 인증 수단 제공

❗️주의 및 한계

기능	지원 여부
Prompts	✅
Tools	✅
Resources	❌
Sampling	❌
Notifications	❌

아직 디바이스 상태 조회 전용 도구 미지원
단방향 컨트롤 위주 지원 (양방향 상호작용에는 제약 있음)

🛠️ 문제 해결 (Troubleshooting)

문제: Claude에서 "Failed to start MCP server" 발생

• claude_desktop_config.json 설정 확인
• mcp-proxy 경로 문제 시 직접 커맨드 실행해보기

문제: “401 Unauthorized”

• Access Token 오류 → Home Assistant에서 새로 생성 후 반영

🎯 실전 사용 예시

• "방 거실 조명 꺼줘" → Claude가 Home Assistant 조명 엔티티에 명령 전달
• "할 일 목록에 '세탁기 돌리기' 추가해줘" → Home Assistant To-do List에 항목 추가

300x250

🛠 MCP Proxy를 시스템 서비스로 상시 운영하기

Claude 또는 Cursor 같은 LLM 클라이언트가 항상 Home Assistant에 연결할 수 있도록 mcp-proxy를 백그라운드 서비스(systemd)로 등록합니다.

• MCP Proxy (mcp-proxy) 설치 완료
• Home Assistant가 로컬 또는 원격에서 실행 중 (API 및 MCP Server 활성화 상태)
• Long-lived Access Token 생성 완료

1. MCP Proxy 실행 스크립트 작성

/opt/mcp-proxy/start.sh

#!/bin/bash
export SSE_URL="http://localhost:8123/mcp_server/sse"
export API_ACCESS_TOKEN="여기에_토큰_입력"

exec /usr/local/bin/mcp-proxy

경로는 mcp-proxy 설치 경로에 따라 조정하세요. uv tool로 설치한 경우 경로 확인 필요 (which mcp-proxy).

chmod +x /opt/mcp-proxy/start.sh

2. systemd 서비스 파일 생성

/etc/systemd/system/mcp-proxy.service

[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

User=는 해당 서비스를 실행할 계정입니다. 적절한 사용자 계정을 설정하세요.

3. 서비스 활성화 및 실행

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-proxy.service

서비스 상태 확인

sudo systemctl status mcp-proxy.service

🤖 LLM 연동 자동화 시나리오: “위치 + 모션 기반 생활 자동화”

💡 시나리오 목표

“사용자가 집에 도착하여 일정 시간 내 움직임이 감지되면, 자동으로 집 조명을 켜고 ‘오늘 일정’을 Claude가 요약해서 알려줍니다.”

🎯 핵심 구성 요소

항목	설명
📍 위치 기반 트리거	Home Assistant zone 기능으로 '집'에 들어왔는지 확인
👣 모션 센서	Zigbee/Z-Wave/ESPHome 연동된 PIR 센서
🧠 Claude + MCP	Claude를 통해 ‘오늘의 일정’을 요약하여 음성/텍스트 안내
🏠 조명	스마트 조명 또는 Zigbee 스위치 제어

🧩 Home Assistant 자동화 예시 (Automation YAML)

alias: Arrival Automation with Motion
trigger:
  - platform: zone
    entity_id: person.jinjong
    zone: zone.home
    event: enter
condition: []
action:
  - wait_for_trigger:
      - platform: state
        entity_id: binary_sensor.livingroom_motion
        to: "on"
    timeout: "00:03:00"
    continue_on_timeout: false
  - service: light.turn_on
    target:
      entity_id: light.living_room
  - service: notify.claude_mcp
    data:
      message: >
        "{{ now().strftime('%Y년 %m월 %d일') }} 일정 요약을 알려줘."

notify.claude_mcp는 LLM 클라이언트가 Home Assistant MCP 도구로 제공되었을 때 사용 가능하며, Claude가 Home Assistant에 요청을 보내 “도구 사용”하는 방식입니다.

🗣 Claude 응답 예시

Claude는 MCP 프롬프트에 따라 다음과 같은 답변을 제공할 수 있습니다.

오늘은 4개의 일정이 있습니다.
- 오전 9시: 팀 미팅 (Zoom)
- 오후 1시: 보안 점검 보고서 제출
- 오후 4시: 외부 업체 미팅
- 오후 6시: 마감 체크

🔐 보안 가이드 및 점검 포인트

항목	내용
API Access Token 권한	노출된 엔티티 외에는 접근 불가하도록 설정
네트워크 보안	mcp-proxy와 Home Assistant 간 연결은 로컬 또는 HTTPS로 구성
사용자 승인	Claude가 도구 사용 시 반드시 사용자에게 승인을 요구하도록 설정 가능
로그 모니터링	mcp-proxy, Claude, Home Assistant 로그 주기적 점검

🧪 추가 확장 아이디어

기능	설명
📅 일정 동기화	Google Calendar 또는 Nextcloud Calendar 연동
🗣 음성 피드백	Home Assistant TTS(Text-to-Speech)로 Claude 요약 내용 출력
🔐 외출 모드 전환	위치 기반 외출 시 조명 자동 OFF, 보안 시스템 ON
📷 CCTV 확인 요청	Claude에게 “현관문 카메라 보여줘” 요청 시 스트리밍 영상 제공