홈 어시스턴트 MCP 서버

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

특징

자연어를 통해 Home Assistant 엔터티 쿼리 및 제어
모든 MCP 호환 클라이언트(예: Claude Desktop)와 함께 작동합니다.
상태 관리, 서비스 호출, 기록 등을 위한 도구를 제공합니다.
Home Assistant 장기 액세스 토큰을 사용한 보안 인증
다양한 전송 옵션(로컬 프로세스용 stdio, 원격 클라이언트용 SSE)
Home Assistant를 사용할 수 없을 때 테스트 및 데모를 위한 모의 데이터가 포함된 데모 모드

설치

지엑스피1

구성

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

# Required configurations
HASS_URL=http://your-home-assistant:8123  # URL to your Home Assistant instance
HASS_TOKEN=your_long_lived_access_token   # Long-lived access token for authentication

# Optional configurations
PORT=3000                # Port for the HTTP server (default: 3000)
HASS_MOCK=false          # Enable mock data mode when Home Assistant is unavailable (default: false)

환경 변수

변하기 쉬운	필수의	기본	설명
`HASS_URL`	예	-	Home Assistant 인스턴스의 URL(예: http://homeassistant.local:8123 )
`HASS_TOKEN`	예	-	Home Assistant 인증을 위한 장기 액세스 토큰
`PORT`	아니요	3000	HTTP/SSE 전송을 사용할 때 HTTP 서버의 포트 번호
`HASS_MOCK`	아니요	거짓	"true"로 설정하면 Home Assistant 연결 없이 테스트를 위한 모의 데이터 모드가 활성화됩니다.

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

Home Assistant 인스턴스에 로그인하세요
프로필을 클릭하세요(왼쪽 하단)
"장기 액세스 토큰"까지 아래로 스크롤하세요.
설명적인 이름으로 새 토큰을 만듭니다.
토큰 값을 복사하세요(다시는 볼 수 없습니다)

용법

독립형 서버로 실행

# Standard mode (requires a running Home Assistant instance)
home-assistant-mcp-server                # Start with HTTP/SSE transport
home-assistant-mcp-server --stdio        # Start with stdio transport for direct process communication

# Demo mode (with mock data when Home Assistant is unavailable)
home-assistant-mcp-server --mock         # Start with HTTP/SSE transport and mock data
home-assistant-mcp-server --stdio --mock # Start with stdio transport and mock data

Claude Desktop과 통합

Claude Desktop과 함께 사용하려면:

Claude Desktop 구성 파일을 편집하세요.
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
서버 구성을 추가합니다.

{
  "mcpServers": {
    "homeassistant": {
      "command": "home-assistant-mcp-server"
      "env": {
        "HASS_URL": "http://your-home-assistant:8123",
        "HASS_TOKEN": "your_token_here",
        "HASS_MOCK": "true"
      }
    }
  }
}

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

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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

Home Assistant MCP Server

Integrations

홈 어시스턴트 MCP 서버

특징

설치

구성

환경 변수

용법

독립형 서버로 실행

Claude Desktop과 통합

사용 가능한 도구

보안

특허