Home Assistant용 모델 컨텍스트 프로토콜 서버

서버는 MCP 프로토콜을 사용하여 로컬 Home Assistant 인스턴스에 대한 액세스를 LLM 애플리케이션과 공유합니다.

Home Assistant 인스턴스와 언어 학습 모델(LLM)을 연결하는 강력한 브리지로, 모델 컨텍스트 프로토콜(MCP)을 통해 스마트 홈 기기의 자연어 제어 및 모니터링을 지원합니다. 이 서버는 기기 제어부터 시스템 관리까지 전체 Home Assistant 생태계를 관리할 수 있는 포괄적인 API를 제공합니다.

특징

🎮 기기 제어 : 자연어를 통해 모든 Home Assistant 기기를 제어하세요
🔄 실시간 업데이트 : SSE(Server-Sent Events)를 통해 즉각적인 업데이트를 받으세요.
🤖 자동화 관리 : 자동화를 생성, 업데이트 및 관리합니다.
📊 상태 모니터링 : 장치 상태 추적 및 쿼리
🔐 보안 : 토큰 기반 인증 및 속도 제한
📱 모바일 지원 : HTTP 지원 클라이언트와 함께 작동합니다.

SSE를 통한 실시간 업데이트

이 서버에는 Home Assistant 인스턴스에서 실시간 업데이트를 제공하는 강력한 SSE(Server-Sent Events) 시스템이 포함되어 있습니다. 이를 통해 다음과 같은 작업을 수행할 수 있습니다.

🔄 모든 기기에서 즉각적인 상태 변경을 받으세요
📡 자동화 트리거 및 실행 모니터링
🎯 특정 도메인이나 엔터티 구독
📊 서비스 호출 및 스크립트 실행 추적

빠른 SSE 예제

지엑스피1

SSE 시스템에 대한 전체 문서는 SSE_API.md를 참조하세요.

주요 특징

핵심 기능 🎮

스마트 기기 제어
- 💡 조명 : 밝기, 색온도, RGB 색상
- 🌡️ 기후 : 온도, HVAC 모드, 팬 모드, 습도
- 🚪 커버 : 위치 및 기울기 제어
- 🔌 스위치 : 켜기/끄기 제어
- 🚨 센서 및 접점 : 상태 모니터링
- 🎵 미디어 플레이어 : 재생 제어, 볼륨, 소스 선택
- 🌪️ 팬 : 속도, 진동, 방향
- 🔒 잠금 : 잠금/잠금 해제 제어
- 🧹 진공 : 시작, 중지, 베이스로 복귀
- 📹 카메라 : 동작 감지, 스냅샷

시스템 관리 🛠️

애드온 관리
- 사용 가능한 애드온 찾아보기
- 애드온 설치/제거
- 애드온 시작/중지/재시작
- 버전 관리
- 구성 액세스
패키지 관리(HACS)
- Home Assistant 커뮤니티 스토어와 통합
- 다양한 패키지 유형 지원:
  - 사용자 정의 통합
  - 프런트엔드 테마
  - 파이썬 스크립트
  - AppDaemon 앱
  - NetDaemon 앱
- 버전 제어 및 업데이트
- 저장소 관리
자동화 관리
- 자동화 생성 및 편집
- 고급 구성 옵션:
  - 다양한 트리거 유형
  - 복잡한 조건
  - 액션 시퀀스
  - 실행 모드
- 기존 자동화를 복제하고 수정합니다.
- 자동화 규칙 활성화/비활성화
- 자동화를 수동으로 트리거합니다

건축 특징 🏗️

지능형 조직
- 지역 및 층 기반 장치 그룹화
- 상태 모니터링 및 쿼리
- 스마트한 상황 인식
- 과거 데이터 접근
견고한 아키텍처
- 포괄적인 오류 처리
- 상태 검증
- 안전한 API 통합
- TypeScript 유형 안전성
- 광범위한 테스트 범위

필수 조건

Node.js 20.10.0 이상
NPM 패키지 관리자
컨테이너화를 위한 Docker Compose
Home Assistant 인스턴스 실행 중
Home Assistant 장기 액세스 토큰( 토큰을 얻는 방법 )
패키지 관리 기능을 위해 HACS가 설치됨
추가 기능 관리를 위한 감독자 액세스

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 Home Assistant MCP Server를 자동으로 설치하려면:

npx -y @smithery/cli install @drejom/homeassistant-mcp --client claude

기본 설정

# Clone the repository
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

# Install dependencies
npm install

# Build the project
npm run build

Docker 설정(권장)

이 프로젝트에는 다양한 플랫폼에서 쉬운 배포와 일관된 환경을 제공하는 Docker 지원이 포함됩니다.

저장소를 복제합니다.
git clone https://github.com/jango-blockchained/homeassistant-mcp.git cd homeassistant-mcp
환경 구성:
cp .env.example .env
Home Assistant 구성으로 .env 파일을 편집합니다.
# Home Assistant Configuration HASS_HOST=http://homeassistant.local:8123 HASS_TOKEN=your_home_assistant_token HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket # Server Configuration PORT=3000 NODE_ENV=production DEBUG=false
Docker Compose로 빌드하고 실행하세요.
# Build and start the containers docker compose up -d # View logs docker compose logs -f # Stop the service docker compose down
설치 확인: 이제 서버가 http://localhost:3000 에서 실행 중이어야 합니다. http://localhost:3000/health 에서 상태 엔드포인트를 확인할 수 있습니다.
애플리케이션을 업데이트하세요:
# Pull the latest changes git pull # Rebuild and restart the containers docker compose up -d --build

Docker 구성

Docker 설정에는 다음이 포함됩니다.

최적의 이미지 크기를 위한 다단계 빌드
컨테이너 모니터링을 위한 상태 점검
환경 구성을 위한 볼륨 마운팅
실패 시 컨테이너 자동 재시작
API 액세스를 위해 노출된 포트 3000

Docker Compose 환경 변수

모든 환경 변수는 .env 파일에서 구성할 수 있습니다. 지원되는 변수는 다음과 같습니다.

HASS_HOST : Home Assistant 인스턴스 URL
HASS_TOKEN : Home Assistant용 장기 액세스 토큰
HASS_SOCKET_URL : Home Assistant용 WebSocket URL
PORT : 서버 포트(기본값: 3000)
NODE_ENV : 환경(프로덕션/개발)
DEBUG : 디버그 모드 활성화(true/false)

구성

환경 변수

# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123  # Your Home Assistant instance URL
HASS_TOKEN=your_home_assistant_token       # Long-lived access token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket  # WebSocket URL

# Server Configuration
PORT=3000                # Server port (default: 3000)
NODE_ENV=production     # Environment (production/development)
DEBUG=false            # Enable debug mode

# Test Configuration
TEST_HASS_HOST=http://localhost:8123  # Test instance URL
TEST_HASS_TOKEN=test_token           # Test token

구성 파일

개발 : .env.example``.env.development 로 복사합니다.
프로덕션 : .env.example``.env.production 으로 복사합니다.
테스트 : .env.example``.env.test 로 복사합니다.

Claude Desktop(또는 다른 클라이언트)에 추가

새 Home Assistant MCP 서버를 사용하려면 Claude Desktop을 클라이언트로 추가하세요. 구성에 다음을 추가하세요. 이렇게 하면 Claude 내에서 MCP가 실행되며 Docker 방식에서는 작동하지 않습니다.

{
  "homeassistant": {
    "command": "node",
    "args": [<path/to/your/dist/folder>]
    "env": {
      NODE_ENV=development
      HASS_HOST=http://homeassistant.local:8123
      HASS_TOKEN=your_home_assistant_token
      PORT=3000
      HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
      LOG_LEVEL=debug
    }
  }
}

API 참조

장치 제어

공통 엔터티 컨트롤

{
  "tool": "control",
  "command": "turn_on",  // or "turn_off", "toggle"
  "entity_id": "light.living_room"
}

조명 제어

{
  "tool": "control",
  "command": "turn_on",
  "entity_id": "light.living_room",
  "brightness": 128,
  "color_temp": 4000,
  "rgb_color": [255, 0, 0]
}

애드온 관리

사용 가능한 추가 기능 목록

{
  "tool": "addon",
  "action": "list"
}

애드온 설치

{
  "tool": "addon",
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}

추가 기능 상태 관리

{
  "tool": "addon",
  "action": "start",  // or "stop", "restart"
  "slug": "core_configurator"
}

패키지 관리

HACS 패키지 목록

{
  "tool": "package",
  "action": "list",
  "category": "integration"  // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}

패키지 설치

{
  "tool": "package",
  "action": "install",
  "category": "integration",
  "repository": "hacs/integration",
  "version": "1.32.0"
}

자동화 관리

자동화 만들기

{
  "tool": "automation_config",
  "action": "create",
  "config": {
    "alias": "Motion Light",
    "description": "Turn on light when motion detected",
    "mode": "single",
    "trigger": [
      {
        "platform": "state",
        "entity_id": "binary_sensor.motion",
        "to": "on"
      }
    ],
    "action": [
      {
        "service": "light.turn_on",
        "target": {
          "entity_id": "light.living_room"
        }
      }
    ]
  }
}

복제 자동화

{
  "tool": "automation_config",
  "action": "duplicate",
  "automation_id": "automation.motion_light"
}

핵심 기능

국가 관리

GET /api/state
POST /api/state

시스템의 현재 상태를 관리합니다.

요청 예시:

POST /api/state
{
  "context": "living_room",
  "state": {
    "lights": "on",
    "temperature": 22
  }
}

컨텍스트 업데이트

POST /api/context

현재 상황을 새로운 정보로 업데이트합니다.

요청 예시:

POST /api/context
{
  "user": "john",
  "location": "kitchen",
  "time": "morning",
  "activity": "cooking"
}

작업 엔드포인트

작업 실행

POST /api/action

주어진 매개변수로 지정된 작업을 실행합니다.

요청 예시:

POST /api/action
{
  "action": "turn_on_lights",
  "parameters": {
    "room": "living_room",
    "brightness": 80
  }
}

일괄 작업

POST /api/actions/batch

여러 작업을 순서대로 실행합니다.

요청 예시:

POST /api/actions/batch
{
  "actions": [
    {
      "action": "turn_on_lights",
      "parameters": {
        "room": "living_room"
      }
    },
    {
      "action": "set_temperature",
      "parameters": {
        "temperature": 22
      }
    }
  ]
}

쿼리 함수

사용 가능한 작업 가져오기

GET /api/actions

사용 가능한 모든 작업 목록을 반환합니다.

응답 예시:

{
  "actions": [
    {
      "name": "turn_on_lights",
      "parameters": ["room", "brightness"],
      "description": "Turns on lights in specified room"
    },
    {
      "name": "set_temperature",
      "parameters": ["temperature"],
      "description": "Sets temperature in current context"
    }
  ]
}

컨텍스트 쿼리

GET /api/context?type=current

컨텍스트 정보를 검색합니다.

응답 예시:

{
  "current_context": {
    "user": "john",
    "location": "kitchen",
    "time": "morning",
    "activity": "cooking"
  }
}

웹소켓 이벤트

서버는 WebSocket 연결을 통해 실시간 업데이트를 지원합니다.

// Client-side connection example
const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);
};

지원되는 이벤트

state_change : 시스템 상태가 변경될 때 발생합니다.
context_update : 컨텍스트가 업데이트될 때 발생합니다.
action_executed : 작업이 완료될 때 발생합니다.
error : 오류가 발생할 때 발생합니다.

이벤트 데이터 예시:

{
  "event": "state_change",
  "data": {
    "previous_state": {
      "lights": "off"
    },
    "current_state": {
      "lights": "on"
    },
    "timestamp": "2024-03-20T10:30:00Z"
  }
}

오류 처리

모든 엔드포인트는 표준 HTTP 상태 코드를 반환합니다.

200: 성공
400: 잘못된 요청
401: 승인되지 않음
403: 금지됨
404: 찾을 수 없음
500: 내부 서버 오류

오류 응답 형식:

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Missing required parameter: room",
    "details": {
      "missing_fields": ["room"]
    }
  }
}

속도 제한

API는 남용을 방지하기 위해 속도 제한을 구현합니다.

일반 엔드포인트의 경우 IP당 분당 100개 요청
WebSocket 연결에 대해 IP당 분당 1000개 요청

속도 제한을 초과하면 서버는 다음을 반환합니다.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "reset_time": "2024-03-20T10:31:00Z"
  }
}

사용 예

컬을 사용하여

# Get current state
curl -X GET \
  http://localhost:3000/api/state \
  -H 'Authorization: ApiKey your_api_key_here'

# Execute action
curl -X POST \
  http://localhost:3000/api/action \
  -H 'Authorization: ApiKey your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "turn_on_lights",
    "parameters": {
      "room": "living_room",
      "brightness": 80
    }
  }'

JavaScript 사용

// Execute action
async function executeAction() {
  const response = await fetch('http://localhost:3000/api/action', {
    method: 'POST',
    headers: {
      'Authorization': 'ApiKey your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'turn_on_lights',
      parameters: {
        room: 'living_room',
        brightness: 80
      }
    })
  });
  
  const data = await response.json();
  console.log('Action result:', data);
}

개발

# Development mode with hot reload
npm run dev

# Build project
npm run build

# Production mode
npm run start

# Run tests
npx jest --config=jest.config.cjs

# Run tests with coverage
npx jest --coverage

# Lint code
npm run lint

# Format code
npm run format

문제 해결

일반적인 문제

Node.js 버전 ( toSorted is not a function )
- 해결 방법: Node.js 20.10.0+ GXP39로 업데이트
연결 문제
- Home Assistant가 실행 중인지 확인하세요
- HASS_HOST 접근성 확인
- 토큰 권한 검증
- 실시간 업데이트를 위해 WebSocket 연결을 확보하세요
애드온 관리 문제
- 감독자 액세스 확인
- 애드온 호환성 확인
- 시스템 리소스 검증
HACS 통합 문제
- HACS 설치 확인
- HACS 통합 상태 확인
- 저장소 액세스 검증
자동화 문제
- 엔터티 가용성 확인
- 트리거 조건 확인
- 서비스 호출 검증
- 실행 로그 모니터링

프로젝트 상태

✅ 완료

엔티티, 층 및 영역 액세스
장치 제어(조명, 기후, 커버, 스위치, 접점)
애드온 관리 시스템
HACS를 통한 패키지 관리
고급 자동화 구성
기본 상태 관리
오류 처리 및 검증
Docker 컨테이너화
Jest 테스트 설정
TypeScript 통합
환경 변수 관리
홈 어시스턴트 API 통합
프로젝트 문서

🚧 진행 중

실시간 업데이트를 위한 WebSocket 구현
강화된 보안 기능
도구 구성 최적화
성능 최적화
리소스 컨텍스트 통합
API 문서 생성
다중 플랫폼 데스크톱 통합
고급 오류 복구
맞춤형 프롬프트 테스트
향상된 macOS 통합
유형 안전 개선
테스트 커버리지 확장

기여하다

저장소를 포크하세요
기능 브랜치 생성
변경 사항을 구현하세요
새로운 기능에 대한 테스트 추가
모든 테스트가 통과되었는지 확인하세요
풀 리퀘스트 제출

자원

특허

MIT 라이선스 - LICENSE 파일 참조

Integrations

Home Assistant용 모델 컨텍스트 프로토콜 서버

특징

SSE를 통한 실시간 업데이트

빠른 SSE 예제

목차

주요 특징

핵심 기능 🎮

시스템 관리 🛠️

건축 특징 🏗️

필수 조건

설치

Smithery를 통해 설치

기본 설정

Docker 설정(권장)

Docker 구성

Docker Compose 환경 변수

구성

환경 변수

구성 파일

Claude Desktop(또는 다른 클라이언트)에 추가

API 참조

장치 제어

공통 엔터티 컨트롤

조명 제어

애드온 관리

사용 가능한 추가 기능 목록

애드온 설치

추가 기능 상태 관리

패키지 관리

HACS 패키지 목록

패키지 설치

자동화 관리

자동화 만들기

복제 자동화

핵심 기능

국가 관리

컨텍스트 업데이트

작업 엔드포인트

작업 실행

일괄 작업

쿼리 함수

사용 가능한 작업 가져오기

컨텍스트 쿼리

웹소켓 이벤트

지원되는 이벤트

오류 처리

속도 제한

사용 예

컬을 사용하여

JavaScript 사용

개발

문제 해결

일반적인 문제

프로젝트 상태

기여하다

자원

특허

Related Resources

Appeared in Searches