Home Assistant MCP

OAuth로 보호되는 Model Context Protocol (MCP) 서버로, ChatGPT, Codex 및 기타 MCP 클라이언트를 Home Assistant에 안전하게 연결하기 위한 것입니다.

이 프로젝트는 검색, 대시보드, 일정, 기후, 에너지, 미디어, 청소, 관개, 자동화, 진단 및 신중하게 제한된 장치 제어를 위한 99개의 타입화된 도구를 제공합니다. Home Assistant의 API를 비공개로 유지하며, 일반적인 셸, 로그 리더, 네트워크 스캐너 또는 무제한 서비스 프록시가 되는 것을 의도적으로 피합니다.

[!IMPORTANT] 이는 자체 호스팅 Home Assistant 설치를 위한 보안에 민감한 참조 구현입니다. 보안 모델을 읽고, 모든 예제 값을 교체하고, 실제 집에 연결하기 전에 허용 목록을 검토하십시오.

주요 기능

• 타입화된 Home Assistant 접근: 엔티티, 장치, 영역, 기록, 날씨, 달력, 일정, 통계, 통합, 대시보드, 할 일 목록, 자동화, 백업 및 시스템 상태.

• 제한된 쓰기: 기후, 조명, 장면, 미디어 플레이어, 진공 청소기, 커버, 잠금 장치, 사이렌, 알림, 대시보드, 일정, 달력, 할 일 항목 및 자동화는 검증된 입력과 좁은 서비스 허용 목록을 사용합니다.

• 스프링클러 지원: 실시간 컨트롤러 상태, 구역 메타데이터, 구성, 관개 기록, 원격 측정 새로 고침, 구역 또는 시퀀스 시작, 멱등 중지 작업.

• 에너지 및 SolarEdge: 생산량, 모듈 비교, 전력 흐름, 에너지 분석, 저장 요약, 원격 측정, 경고 및 선택적 Home Assistant 브리지 통합.

• 지속적 기능 동기화: Home Assistant의 현재 서비스 레지스트리를 5분마다 검토된 릴리스 기준선과 비교하고, 동적으로 새 쓰기를 노출하지 않고 드리프트를 보고합니다.

• 정화된 진단: 선택적 고정 경로, 호스트/런타임, 중단 및 고정 서브넷 LAN 증거로, 엄격한 제한이 있으며 원시 주소, 임의 대상, 명령 또는 장치 제어가 없습니다.

• OAuth 네이티브 원격 접근: S256 PKCE를 사용한 인증 코드 흐름, 동적 클라이언트 등록, 범위가 지정된 액세스 토큰 및 MCP 리소스 메타데이터.

버전 2.6.1은 현재 99개의 도구를 제공합니다. 릴리스 기록은 CHANGELOG.md를 참조하십시오.

아키텍처

flowchart LR
    Client[ChatGPT, Codex, or MCP client]
    Edge[HTTPS edge<br/>Cloudflare Worker, tunnel, or reverse proxy]
    MCP[Home Assistant MCP<br/>OAuth + typed tools]
    HA[Private Home Assistant API]
    Data[(OAuth, audit, and<br/>capability-sync state)]
    Collector[Optional root-owned<br/>diagnostics collector]
    Export[Sanitized read-only export]

    Client -->|HTTPS + OAuth/PKCE| Edge
    Edge -->|loopback or shared-secret origin| MCP
    MCP -->|long-lived service token| HA
    MCP --> Data
    Collector --> Export --> MCP

참조 배포는 MCP 서비스를 127.0.0.1:8000에 바인딩합니다. HTTPS 엣지만 공개됩니다. Home Assistant는 호스트에 로컬로 유지하거나 개인 네트워크를 통해 연결할 수 있습니다.

도구 표면

위험도가 높은 작업은 파괴적 작업으로 주석 처리되며 명시적 확인 인수가 필요합니다. 정확한 레지스트리가 권위적입니다. 배포 후 인증된 MCP 클라이언트에서 검사하십시오.

요구 사항

• MCP 호스트에서 연결할 수 있는 Home Assistant.

• 전용 Home Assistant 장기 액세스 토큰. 가능하면 별도의 서비스 ID를 사용하십시오.

• 개발 및 테스트를 위한 Python 3.12 이상 및 uv.

• 참조 컨테이너 배포를 위한 Docker 및 Compose.

• 원격 MCP 클라이언트를 위한 공개 HTTPS URL.

• 루프백을 통해 MCP에 도달하거나 구성된 오리진 공유 비밀을 주입하는 HTTPS 엣지. 포함된 Caddy 및 Cloudflare 예제는 두 패턴을 보여줍니다.

• 선택적 호스트 진단 수집기를 사용하는 경우에만 Linux 및 systemd.

번들된 Compose 파일은 범용 원클릭 설치 프로그램이 아닌 프로덕션 참조입니다. 호스트 네트워킹, /opt/homeassistant/config에 있는 기존 Home Assistant 구성, /var/lib/ha-host-diagnostics/export에 설치된 진단 내보내기를 가정합니다. Home Assistant API 또는 Docker 소켓을 노출하지 않고 해당 마운트를 설치에 맞게 조정하십시오.

개발 빠른 시작

저장소를 클론하고 잠긴 종속성을 설치합니다:

git clone https://github.com/shogun301/ha-chatgpt-mcp.git
cd ha-chatgpt-mcp
uv sync --frozen

테스트 스위트 및 공개 소스 감사는 프로덕션 자격 증명이 필요하지 않습니다:

uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

서비스를 실행하려면 .env.example을 무시된 .env에 복사하고 모든 예제 도메인 및 엔티티 ID를 교체하고 아래 설명된 필수 런타임 경로와 비밀 파일을 제공하십시오. 애플리케이션은 .env를 자동으로 로드하지 않습니다. 프로세스 관리자에서 변수를 내보내거나 uvicorn --env-file .env를 사용하거나 Docker Compose가 로드하도록 하십시오.

환경을 구성한 후 로컬 프로세스의 경우:

uv run uvicorn app.server:app --host 127.0.0.1 --port 8000 --no-proxy-headers

마운트 및 선택적 통합을 조정한 후 참조 컨테이너 배포의 경우:

docker compose build --pull
docker compose up -d
curl --fail http://127.0.0.1:8000/healthz

Uvicorn을 공용 인터페이스에 직접 바인딩하지 마십시오.

구성

핵심 설정

.env.example의 엔티티별 변수는 일반 도구 표면을 한 배포의 존재, 알림, 진공 청소기, 스프링클러, 온도 조절기 및 일정 엔티티에 매핑합니다. 실제 엔티티 ID는 Git이 아닌 로컬 구성에 유지하십시오.

필수 비밀 파일

서버는 환경 값이 아닌 파일에서 비밀을 읽습니다:

암호학적으로 안전한 생성기로 임의 값을 생성하십시오. Argon2 암호 해시는 셸 기록에 암호를 넣지 않고 생성할 수 있습니다:

uv run python -c "from argon2 import PasswordHasher; from getpass import getpass; print(PasswordHasher().hash(getpass('OAuth password: ')))"
uv run python -c "import secrets; print(secrets.token_urlsafe(48))"

출력을 소유자 전용 권한의 별도 파일에 저장하십시오. secrets/, .env, 토큰, 암호, 해시, 개인 도메인, 엔티티 인벤토리, 일정 또는 네트워크 토폴로지를 커밋하지 마십시오.

선택적 SolarEdge 구성

SolarEdge 지원은 선택적 클라이언트 자격 증명, 암호화된 토큰 저장소, 브리지 비밀, 리디렉션 URI 및 보호된 포털 대체 자격 증명을 사용합니다. SolarEdge를 사용하지 않으면 해당 SOLAREDGE_*_FILE 변수를 생략하십시오. 참조 Compose 파일은 해당 경로를 설정하므로 파일을 제공하거나 로컬 오버라이드에서 해당 항목을 제거하십시오.

OAuth 범위

• mcp:read는 읽기 도구를 허용합니다.

• mcp:write는 검토된 쓰기 표면을 허용하며 현재 가장 강력한 호환성 부여도 충족합니다.

• mcp:diagnostics는 mcp:read와 함께 장치 쓰기를 부여하지 않고 권한 있는 읽기 전용 호스트 및 LAN 진단을 허용합니다.

클라이언트를 https://your-mcp-host.example/mcp에 연결하십시오. 서버는 동일한 오리진에서 OAuth 인증 서버, 보호 리소스, OpenID 구성 및 동적 클라이언트 등록 메타데이터를 게시합니다.

엣지 옵션

애플리케이션은 루프백이 아닌 요청이 구성된 오리진 공유 비밀을 전달하도록 요구합니다. 두 가지 예제가 포함되어 있습니다:

• cloudflare/는 좁은 Cloudflare Worker 프록시를 포함합니다. MCP, OAuth, 상태 및 SolarEdge 콜백 경로만 전달하고, 1MiB 요청 제한을 적용하고, 오리진 비밀을 추가하고, 불필요한 헤더를 제거합니다.

• Caddyfile은 루프백 MCP 리스너에 대한 동일 호스트 HTTPS 역방향 프록시를 제공합니다.

포함된 cloudflared 서비스는 토큰 파일을 사용하고 루프백에서만 메트릭을 게시합니다. 모든 예제 경로를 교체하고 MCP 오리진, Home Assistant API 및 메트릭 리스너를 공용 네트워크에서 분리하십시오.

기능 동기화

Home Assistant 통합은 이 프로젝트와 독립적으로 서비스를 추가하거나 제거할 수 있습니다. 따라서 서버는 5분마다 Home Assistant의 서비스 레지스트리를 폴링하고 릴리스에 바인딩된 기준선을 /data/ha-capability-sync.json에 유지합니다.

get_capability_sync_status는 재시작 간에 추가되거나 제거된 서비스 및 필드 스키마 변경을 보고합니다. 모니터는 의도적으로 관찰 전용입니다. 서비스를 호출하지 않으며 검토되지 않은 Home Assistant 서비스를 새 MCP 쓰기 도구로 전환하지 않습니다. 새 기능은 검토되고, 타입화된 도구로 구현되고, 테스트되고, Git을 통해 릴리스되어야 합니다.

선택적 호스트 및 LAN 진단

collector/ 아래의 systemd 수집기는 리스너가 없으며 호출자가 선택한 명령, 경로, 컨테이너, 로그 표현식 또는 URL을 허용하지 않습니다. 고정 디렉터리에 제한되고 정화된 스냅샷과 원장을 게시합니다. MCP 컨테이너는 해당 디렉터리만 읽기 전용 마운트로 받습니다—Docker 소켓, 호스트 저널, procfs, sysfs 또는 systemd 제어는 절대 아닙니다.

LAN 도구는 구성된 하나의 /24 내에서만 작동하고, 불투명 노드 ID를 반환하고, 폐쇄된 TCP 서비스 허용 목록을 사용하고, 애플리케이션 페이로드를 보내지 않으며, 원시 주소를 생략합니다. 임의 네트워크를 스캔하거나 장치를 제어할 수 없습니다.

전체 데이터 모델, 보존 제한, 배포, 검증, 사고 및 롤백 절차는 docs/operations.md 및 collector/README.md를 참조하십시오.

보안 모델

이 서버는 의도적으로 Home Assistant API보다 범위를 좁게 설계되었습니다:

• 셸 실행, 임의 WebSocket 패스스루, 임의 파일, 원시 로그, Docker 관리, 서비스 재시작, 종료, 자격 증명 조회, 카메라 영상, 알람 해제 기능이 없습니다.

• 일반 Home Assistant 서비스 호출은 도메인과 서비스별로 허용 목록에 등록되며, 전용 타입 기반 도구가 우선 사용됩니다.

• 입력은 스키마 검증을 거치고, 결과 크기는 제한되며, 민감한 진단 필드는 재귀적으로 삭제(redact)됩니다.

• 파괴적이거나 물리적 작업에는 명시적 주석과 확인 게이트가 사용됩니다.

• 감사 기록에는 도구 이름과 제한된 메타데이터만 포함되며, 자격 증명이나 반환된 진단 증거는 포함되지 않습니다.

• 컨테이너는 권한이 없는 사용자로 실행되며, 읽기 전용 파일 시스템, 모든 Linux capability 제거, no-new-privileges 활성화가 적용됩니다.

• 공개 릴리스 감사는 게시 전에 현재 트리와 Git 히스토리를 모두 검사합니다.

연결 테스트 목적으로 온도조절기, 조명, 잠금장치, 진공청소기, 스프링클러, 카메라, 스피커, 텔레비전, 백업, 알림 또는 기타 물리적 부작용을 절대 사용하지 마십시오.

취약점 신고 및 민감한 배포 정보 처리에 대해서는 SECURITY.md를 읽어주세요.

배포 및 검증

scripts/deploy-production.ps1의 PowerShell 배포 스크립트는 AWS Lightsail 참조 구현입니다. 명시적인 AWS 프로필, 리전, 인스턴스, 프런트엔드 URL, MCP URL 매개변수가 필요하며, 검토된 소스를 패키징하고, 백업을 생성하고, 수집기와 컨테이너를 배포하고, 검증을 실행하며, 롤백을 지원합니다. 다른 호스트에 적용하기 전에 신중히 검토하세요.

모든 공개 푸시 또는 프로덕션 릴리스 전에:

uv sync --frozen
uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

그런 다음 장치 상태를 변경하지 않고 다음을 검증하세요:

1. /healthz가 로컬 및 공개 엣지를 통해 성공적으로 응답합니다.

2. 인증되지 않은 MCP 요청과 잘못된 토큰의 MCP 요청이 거부됩니다.

3. 인증된 디스커버리가 예상 버전과 도구 수를 보고합니다.

4. 읽기 전용 개요, 기능 동기화, 경로, 통합 검사가 성공합니다.

5. 공개 Git 커밋, 배포된 아티팩트, 보고된 서비스 버전이 동일합니다.

프로덕션 절차와 롤백 게이트는 docs/operations.md에 자세히 설명되어 있습니다.

기여

프로젝트의 제한된 보안 모델을 유지하는 이슈와 풀 리퀘스트를 환영합니다.

새 도구에 대해서는:

1. 일반 패스스루보다 좁은 범위의 타입 기반 작업을 우선 사용하세요.

2. 읽기 전용, 멱등성, 쓰기, 파괴적 주석을 정확하게 정의하세요.

3. 엔티티 도메인, 열거형, 길이, 시간 창, 결과 제한을 검증하세요.

4. 결과적으로 물리적 또는 관리적 영향을 미치는 작업에는 명시적 확인을 요구하세요.

5. 권한 부여, 부정 경로, 삭제(redaction), 회귀 테스트를 추가하세요.

6. 기능 문서를 업데이트하고 공개 히스토리 감사를 실행하세요.

이슈, 픽스처, 스크린샷, 커밋 또는 풀 리퀘스트에 실제 가정 구성, 개인 URL, 자격 증명, 로그, 토큰, 일정, 토폴로지 또는 공급자 응답을 포함하지 마세요.

라이선스

현재 오픈소스 라이선스는 포함되어 있지 않습니다. 공개적으로 볼 수 있다고 해서 코드를 복사, 수정 또는 재배포할 수 있는 권한이 부여되는 것은 아닙니다. 저장소 소유자는 재사용 또는 재배포를 허용하기 전에 명시적 라이선스를 추가해야 합니다.

참고 자료

• Model Context Protocol

• OpenAI: Build an MCP server

• OpenAI: Authenticate users

• Cloudflare Tunnel monitoring

• Cloudflare Tunnel metrics