홈 어시스턴트 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 파일을 만듭니다.

# 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)

환경 변수

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

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

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

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

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

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

용법

독립형 서버로 실행

# 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과 함께 사용하려면:

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

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

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

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

{
  "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 로 설정하기만 하면 됩니다.

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