홈 어시스턴트 MCP 서버

Home Assistant 와 통합하기 위한 MCP(Model Context Protocol) 서버로, LLM이 스마트 홈을 제어하고 쿼리할 수 있습니다.

특징

• 자연어를 통해 Home Assistant 엔터티 쿼리 및 제어

• 모든 MCP 호환 클라이언트(예: Claude Desktop)와 함께 작동합니다.

• 상태 관리, 서비스 호출, 기록 등을 위한 도구를 제공합니다.

• Home Assistant 장기 액세스 토큰을 사용한 보안 인증

• 다양한 전송 옵션(로컬 프로세스용 stdio, 원격 클라이언트용 SSE)

• Home Assistant를 사용할 수 없을 때 테스트 및 데모를 위한 모의 데이터가 포함된 데모 모드

Related MCP server: Home Assistant MCP Server

설치

지엑스피1

구성

다음 변수를 사용하여 현재 디렉토리에 .env 파일을 만듭니다.

환경 변수

장기 액세스 토큰을 얻으려면:

1. Home Assistant 인스턴스에 로그인하세요

2. 프로필을 클릭하세요(왼쪽 하단)

3. "장기 액세스 토큰"까지 아래로 스크롤하세요.

4. 설명적인 이름으로 새 토큰을 만듭니다.

5. 토큰 값을 복사하세요(다시는 볼 수 없습니다)

용법

독립형 서버로 실행

Claude Desktop과 통합

Claude Desktop과 함께 사용하려면:

1. Claude Desktop 구성 파일을 편집하세요.

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 서버 구성을 추가합니다.

Home Assistant가 실행 중이면 --mock 플래그를 제거하고 HASS_MOCK false 로 설정하기만 하면 됩니다.

3. Claude Desktop을 다시 시작하세요

사용 가능한 도구

서버는 Home Assistant와 상호 작용하기 위한 여러 도구를 제공합니다.

• states - 엔터티 상태 쿼리

• lights - 조명 목록

• light - 조명을 제어합니다

• service - 홈 어시스턴트 서비스 호출

• history - 과거 엔터티 데이터 검색

• services - 사용 가능한 서비스 목록

• config - 홈 어시스턴트 구성 가져오기

• domains - 사용 가능한 도메인 나열

• error_log - Home Assistant 오류 로그 가져오기

• devices - Home Assistant에서 모든 장치 가져오기

자세한 사용 예는 docs/hass-mcp.md를 참조하세요.

보안

이 서버에는 전체 액세스 권한이 있는 Home Assistant 액세스 토큰이 필요합니다. 다음 보안 권장 사항을 고려하세요.

• 신뢰할 수 있는 네트워크에서만 서버를 실행하세요

• 서버를 원격으로 노출하는 경우 HTTPS를 사용하세요.

• .env 파일을 안전하게 보관하고 소스 제어에 커밋하지 마세요.

• 가능하면 권한이 제한된 토큰을 사용하는 것을 고려하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.