홈어시스턴트 MCP

홈 어시스턴트 모델 컨텍스트 프로토콜(MCP)

AI 어시스턴트가 Home Assistant와 상호 작용할 수 있도록 표준화된 프로토콜로, 스마트 홈 기기를 제어하기 위한 안전하고 형식이 지정되고 확장 가능한 인터페이스를 제공합니다.

개요

MCP(Model Context Protocol) 서버는 Claude, GPT 등의 AI 모델과 Home Assistant 간의 브리지 역할을 하여 AI 어시스턴트가 다음을 수행할 수 있도록 합니다.

Home Assistant 장치에서 명령 실행
스마트 홈에 대한 정보를 검색합니다
장기 실행 작업에 대한 스트림 응답
매개변수 및 입력 검증
일관된 오류 처리 제공

특징

모듈형 아키텍처 - 전송, 미들웨어 및 도구 간의 명확한 분리
Typed Interface - 더 나은 개발자 경험을 위해 완전한 TypeScript 타이핑
다중 전송 :
- CLI 통합을 위한 표준 I/O (stdin/stdout)
- 스트리밍을 위한 서버 전송 이벤트 지원이 포함된 HTTP/REST API
미들웨어 시스템 - 검증, 로깅, 시간 초과 및 오류 처리
내장 도구 :
- 조명 제어(밝기, 색상 등)
- 기후 제어(온도 조절 장치, HVAC)
- 더 많은 내용이 나올 예정입니다...
확장 가능한 플러그인 시스템 - 새로운 도구와 기능을 쉽게 추가
스트리밍 응답 - 장기 실행 작업 지원
매개변수 검증 - Zod 스키마 사용
Claude & Cursor 통합 - AI 어시스턴트를 위한 기성 유틸리티

시작하기

필수 조건

노드.js 16+
Home Assistant 인스턴스(또는 테스트를 위해 모의 구현을 사용할 수 있음)

설치

지엑스피1

서버 실행

# Start with standard I/O transport (for AI assistant integration)
npm start -- --stdio

# Start with HTTP transport (for API access)
npm start -- --http

# Start with both transports
npm start -- --stdio --http

구성

환경 변수나 .env 파일을 사용하여 서버를 구성합니다.

# Server configuration
PORT=3000
NODE_ENV=development

# Execution settings
EXECUTION_TIMEOUT=30000
STREAMING_ENABLED=true

# Transport settings
USE_STDIO_TRANSPORT=true
USE_HTTP_TRANSPORT=true

# Debug and logging
DEBUG_MODE=false
DEBUG_STDIO=false
DEBUG_HTTP=false
SILENT_STARTUP=false

# CORS settings
CORS_ORIGIN=*

건축학

MCP 서버는 계층형 아키텍처로 구축되었습니다.

전송 계층 - 통신 프로토콜(stdio, HTTP)을 처리합니다.
미들웨어 계층 - 파이프라인을 통해 요청을 처리합니다.
도구 계층 - 특정 기능을 구현합니다
리소스 계층 - 상태 저장 리소스를 관리합니다.

도구

도구는 MCP 서버에 기능을 추가하는 주요 방법입니다. 각 도구의 기능은 다음과 같습니다.

고유한 이름을 가지고 있습니다
입력된 매개변수를 허용합니다
입력된 결과를 반환합니다
부분 결과를 스트리밍할 수 있습니다
입력과 출력을 검증합니다

도구 등록 예시:

import { LightsControlTool } from "./tools/homeassistant/lights.tool.js";
import { ClimateControlTool } from "./tools/homeassistant/climate.tool.js";

// Register tools
server.registerTool(new LightsControlTool());
server.registerTool(new ClimateControlTool());

API

HTTP 전송을 통해 실행할 때 서버는 JSON-RPC 2.0 API를 제공합니다.

POST /api/mcp/jsonrpc - 도구 실행
GET /api/mcp/stream - 실시간 업데이트를 위해 SSE 스트림에 연결합니다.
GET /api/mcp/info - 서버 정보 가져오기
GET /health - 상태 확인 엔드포인트

AI 모델과의 통합

클로드 통합

import { createClaudeToolDefinitions } from "./mcp/index.js";

// Generate Claude-compatible tool definitions
const claudeTools = createClaudeToolDefinitions([
  new LightsControlTool(),
  new ClimateControlTool()
]);

// Use with Claude API
const messages = [
  { role: "user", content: "Turn on the lights in the living room" }
];

const response = await claude.messages.create({
  model: "claude-3-opus-20240229",
  messages,
  tools: claudeTools
});

커서 통합

Cursor와 함께 Home Assistant MCP 서버를 사용하려면 .cursor/config/config.json 파일에 다음을 추가하세요.

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bash",
      "args": ["-c", "cd ${workspaceRoot} && bun run dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"],
      "env": {
        "NODE_ENV": "development",
        "USE_STDIO_TRANSPORT": "true",
        "DEBUG_STDIO": "true"
      }
    }
  }
}

이 구성:

stdio 전송으로 MCP 서버를 실행합니다.
모든 stderr 출력을 /dev/null로 리디렉션합니다.
grep을 사용하여 {"jsonrpc":"2.0" 포함하는 줄에 대한 stdout을 필터링하여 깨끗한 JSON-RPC 출력을 보장합니다.

커서 통합 문제 해결

Cursor와 함께 MCP 서버를 사용할 때 "클라이언트 생성에 실패했습니다" 오류가 발생하는 경우:

커서 구성에서 올바른 명령과 인수를 사용하고 있는지 확인하세요.
- bash 스크립트 접근 방식은 유효한 JSON-RPC 메시지만 Cursor에 도달하도록 보장합니다.
- 연결을 시도하기 전에 bun run build 실행하여 서버가 빌드되었는지 확인하세요.
서버가 JSON-RPC 메시지를 stdout에 올바르게 출력하는지 확인하세요.
bun run dist/index.js --stdio 2>/dev/null | grep -E '\{"jsonrpc":"2\.0"' > json_only.txt
그런 다음 json_only.txt를 조사하여 유효한 JSON-RPC 메시지만 포함되어 있는지 확인합니다.
시스템에 grep이 설치되어 있는지 확인하세요(대부분의 시스템에서는 기본적으로 사용 가능해야 함)
다음을 사용하여 서버를 다시 빌드해보세요.
bun run build
환경 변수에서 DEBUG_STDIO=true 설정하여 디버그 모드를 활성화합니다.

문제가 지속되면 다음을 시도해 보세요.

커서 재시작
커서 캐시 지우기(도움말 > 개발자 > 캐시 지우기 및 다시 로드)
Node.js에 비슷한 접근 방식을 사용하면:
{ "command": "bash", "args": ["-c", "cd ${workspaceRoot} && node dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"] }

특허

MIT

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

홈 어시스턴트용 MCP 서버 🏠🤖

개요 🌐

MCP(Model Context Protocol) 서버는 Home Assistant용 경량 통합 도구로, 기기 관리 및 자동화를 위한 유연한 인터페이스를 제공합니다. 빠르고 안전하며 사용하기 쉽게 설계되었습니다. 최대 성능을 위해 Bun으로 구축되었습니다.

핵심 기능 ✨

🔌 REST API를 통한 기본 장치 제어
📡 상태 업데이트를 위한 WebSocket/Server-Sent Events(SSE)
🤖 간단한 자동화 규칙 관리
🔐 JWT 기반 인증
🔄 Claude 및 기타 AI 어시스턴트와의 통합을 위한 표준 I/O(stdio) 전송

왜 Bun인가요? 🚀

저는 몇 가지 주요 이점 때문에 Bun을 런타임으로 선택했습니다.

⚡ 초고속 성능
- Node.js보다 최대 4배 빠름
- 내장된 TypeScript 지원
- 최적화된 파일 시스템 작업
🎯 올인원 솔루션
- 패키지 관리자(npm/yarn보다 빠름)
- Bundler(웹팩 필요 없음)
- 테스트 러너(내장 테스트)
- TypeScript 트랜스파일러
🔋 내장 기능
- SQLite3 드라이버
- .env 파일 로딩
- WebSocket 클라이언트/서버
- 파일 감시자
- 테스트 러너
💾 자원 효율성
- 메모리 사용량 감소
- 더 빠른 콜드 스타트
- 더 나은 CPU 활용도
🔄 Node.js 호환성
- 대부분의 npm 패키지를 실행합니다
- Express/Fastify와 호환 가능
- 네이티브 Node.js API

필수 조건 📋

🚀 Bun 런타임 (v1.0.26+)
🏡 홈 어시스턴트 인스턴스
🐳 Docker(선택 사항, 배포에 권장)
🖥️ Node.js 18+ (선택 사항, 음성 기능용)
🎮 CUDA를 지원하는 NVIDIA GPU(선택 사항, 더 빠른 음성 처리)

빠른 시작 🚀

내 저장소를 복제합니다.

git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

환경 설정:

# Make my setup script executable
chmod +x scripts/setup-env.sh

# Run setup (defaults to development)
./scripts/setup-env.sh

# Or specify an environment:
NODE_ENV=production ./scripts/setup-env.sh

# Force override existing files:
./scripts/setup-env.sh --force

설정을 구성하세요:

Home Assistant 세부 정보로 .env 파일 편집
필수: HASS_TOKEN (장기 액세스 토큰)을 추가하세요.

Docker로 빌드하고 실행하세요:

# Standard build
./docker-build.sh

# Launch:
docker compose up -d

Docker 빌드 옵션 🐳

내 Docker 빌드 스크립트( docker-build.sh )는 다양한 구성을 지원합니다.

1. 표준 빌드

./docker-build.sh

기본 MCP 서버 기능
REST API 및 WebSocket 지원
음성 기능이 없습니다

2. 음성 지원 빌드

./docker-build.sh --speech

웨이크워드 감지 기능 포함
음성-텍스트 기능
필요한 이미지를 가져옵니다:
- onerahmet/openai-whisper-asr-webservice
- rhasspy/wyoming-openwakeword

3. GPU 가속 빌드

./docker-build.sh --speech --gpu

모든 음성 기능
CUDA GPU 가속
더 빠른 처리를 위해 최적화됨
더 나은 성능을 위한 Float16 컴퓨팅 유형

빌드 기능

🔄 자동 리소스 할당
💾 메모리 인식 빌딩
📊 CPU 할당량 관리
🧹 자동 정리
📝 자세한 빌드 로그
📊 빌드 요약 및 상태

환경 구성 🔧

저는 계층적 구성 시스템을 구현했습니다.

파일 구조 📁

.env.example - 모든 옵션이 포함된 템플릿
.env - 구성(.env.example에서 복사)
환경 재정의:
- .env.dev - 개발 설정
- .env.prod - 프로덕션 설정
- .env.test - 테스트 설정

로딩 우선순위 ⚡

파일은 다음 순서대로 로드됩니다.

.env (기본 구성)
환경별 파일:
- NODE_ENV=development → .env.dev
- NODE_ENV=production → .env.prod
- NODE_ENV=test → .env.test

이후의 파일이 이전 파일을 덮어씁니다.

개발 💻

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Run with hot reload
bun --hot run dev

# Build for production
bun build ./src/index.ts --target=bun

# Run production build
bun run start

성능 비교 📊

작업	혈액 요소 질소	노드.js
종속성 설치	~2초	~15초
콜드 스타트	300ms	1000ms
빌드 시간	150ms	4000ms
메모리 사용량	~150MB	~400MB

문서 📚

핵심 문서

고급 기능

자연어 처리 - AI 기반 자동화 분석 및 제어
사용자 정의 프롬프트 가이드 - AI 동작 생성 및 사용자 정의
추가 기능 및 도구 - 추가 유틸리티 및 고급 기능

클라이언트 통합 🔗

커서 통합 🖱️

.cursor/config/config.json 에 추가:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bash",
      "args": ["-c", "cd ${workspaceRoot} && bun run dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"],
      "env": {
        "NODE_ENV": "development",
        "USE_STDIO_TRANSPORT": "true",
        "DEBUG_STDIO": "true"
      }
    }
  }
}

클로드 데스크탑 💬

Claude 구성에 다음을 추가합니다.

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bun",
      "args": ["run", "start", "--port", "8080"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

명령줄 💻

Windows 사용자는 제공된 스크립트를 사용할 수 있습니다.

scripts 디렉토리로 이동
start_mcp.cmd 실행합니다.

추가 기능

음성 기능 🎤

MCP 서버는 선택적으로 음성 처리 기능을 지원합니다.

🗣️ 깨우기 단어 감지("헤이 자비스", "오케이 구글", "알렉사")
🎯 Fast-Whisper를 이용한 음성-텍스트 변환
🌍 다국어 지원
🚀 GPU 가속 지원

음성 기능 설정

필수 조건

🐳 Docker 설치 및 실행 중
🎮 CUDA를 탑재한 NVIDIA GPU(선택 사항)
💾 4GB 이상 RAM (8GB 이상 권장)

구성

.env 에서 음성 활성화:

ENABLE_SPEECH_FEATURES=true
ENABLE_WAKE_WORD=true
ENABLE_SPEECH_TO_TEXT=true
WHISPER_MODEL_PATH=/models
WHISPER_MODEL_TYPE=base

STT 엔진을 선택하세요:

# For standard Whisper
STT_ENGINE=whisper

# For Fast Whisper (GPU recommended)
STT_ENGINE=fast-whisper
CUDA_VISIBLE_DEVICES=0  # Set GPU device

사용 가능한 모델 🤖

귀하의 요구 사항에 따라 선택하세요:

tiny.en : 가장 빠르고 기본적인 정확도
base.en : 균형이 좋음 (추천)
small.en : 정확도는 더 높고 느림
medium.en : 정확도 높음, 리소스 집약적
large-v2 : 정확도는 가장 높지만 리소스 소모가 매우 많음

음성 기능으로 시작

# Build with speech support
./docker-build.sh --speech

# Launch with speech features:
docker compose -f docker-compose.yml -f docker-compose.speech.yml up -d

추가 도구 🛠️

Home Assistant 사용 환경을 개선하기 위해 extra/ 디렉토리에 몇 가지 강력한 도구를 포함했습니다.

홈 어시스턴트 분석기 CLI ( ha-analyzer-cli.ts )
- AI 모델을 활용한 심층 자동화 분석
- 보안 취약점 스캐닝
- 성능 최적화 제안
- 시스템 상태 지표
음성-텍스트 변환 예제 ( speech-to-text-example.ts )
- 웨이크 워드 감지
- 음성-텍스트 변환
- 여러 언어 지원
- GPU 가속 지원
Claude 데스크탑 설정 ( claude-desktop-macos-setup.sh )
- macOS용 자동 Claude Desktop 설치
- 환경 구성
- MCP 통합 설정

자세한 사용 지침과 예시는 추가 기능 문서를 참조하세요.

라이센스 📄

MIT 라이선스. 자세한 내용은 라이선스를 참조하세요.

저자 👨‍💻

jango-blockchained 에서 생성됨

표준 I/O 전송으로 실행 📝

MCP 서버는 Claude와 같은 AI 어시스턴트와 직접 통합할 수 있는 JSON-RPC 2.0 stdio 전송 모드를 지원합니다.

MCP Stdio 기능

✅ JSON-RPC 2.0 호환성 : MCP 프로토콜 표준에 대한 완벽한 지원
✅ NPX 지원 : npx homeassistant-mcp 사용하여 설치 없이 직접 실행
✅ 자동 구성 : 필요한 디렉토리와 기본 구성을 생성합니다.
✅ 크로스 플랫폼 : macOS, Linux 및 Windows에서 작동
✅ Claude Desktop 통합 : Claude Desktop과 함께 사용 가능
✅ 매개변수 검증 : 도구 매개변수의 자동 검증
✅ 오류 처리 : 표준화된 오류 코드 및 처리
✅ 상세 로깅 : stdio를 오염시키지 않고 파일에 로깅

옵션 1: NPX 사용(가장 쉬움)

npx를 사용하여 설치 없이 MCP 서버를 직접 실행합니다.

# Basic usage
npx homeassistant-mcp

# Or with environment variables
HASS_URL=http://your-ha-instance:8123 HASS_TOKEN=your_token npx homeassistant-mcp

이렇게 하면:

패키지를 임시로 설치합니다
JSON-RPC 2.0 전송을 사용하여 stdio 모드에서 자동으로 실행
로깅을 위한 로그 디렉토리를 만듭니다.
존재하지 않으면 기본 .env 파일을 만듭니다.

Claude Desktop이나 다른 MCP 클라이언트와의 통합에 적합합니다.

Claude Desktop과 통합

Claude Desktop과 함께 MCP를 사용하려면:

Claude Desktop 설정 열기
"고급" 탭으로 이동하세요
"MCP 서버"에서 "사용자 지정"을 선택하세요.
명령을 입력하세요: npx homeassistant-mcp
"저장"을 클릭하세요

이제 Claude는 Home Assistant 통합을 위해 MCP 서버를 사용하며, 이를 통해 Claude를 통해 직접 스마트 홈을 제어할 수 있습니다.

옵션 2: 로컬 설치

stdio 전송을 활성화하려면 .env 파일을 업데이트하세요.
USE_STDIO_TRANSPORT=true
stdio-start 스크립트를 사용하여 서버를 실행합니다.
./stdio-start.sh
사용 가능한 옵션:
./stdio-start.sh --debug # Enable debug mode ./stdio-start.sh --rebuild # Force rebuild ./stdio-start.sh --help # Show help

stdio 모드에서 실행할 때:

서버는 JSON-RPC 2.0 형식을 사용하여 stdin/stdout을 통해 통신합니다.
HTTP 서버가 시작되지 않았습니다.
stdio 스트림을 오염시키지 않기 위해 콘솔 로깅이 비활성화되었습니다.
모든 로그는 logs/ 디렉토리의 로그 파일에 기록됩니다.

JSON-RPC 2.0 메시지 형식

요청 형식

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tool-name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

응답 형식

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    // Tool-specific result data
  }
}

오류 응답 형식

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32000,
    "message": "Error message",
    "data": {} // Optional error details
  }
}

알림 형식(서버에서 클라이언트로)

{
  "jsonrpc": "2.0",
  "method": "notification-type",
  "params": {
    // Notification data
  }
}

지원되는 오류 코드

암호	설명	의미
-32700	구문 분석 오류	잘못된 JSON이 수신되었습니다.
-32600	잘못된 요청입니다	JSON은 유효한 요청 객체가 아닙니다.
-32601	메서드를 찾을 수 없습니다	방법이 존재하지 않거나 사용할 수 없습니다.
-32602	잘못된 매개변수	잘못된 메서드 매개변수
-32603	내부 오류	내부 JSON-RPC 오류
-32000	도구 실행	도구 실행 중 오류 발생
-32001	검증 오류	매개변수 검증에 실패했습니다

Claude Desktop과 통합

Claude Desktop과 함께 이 MCP 서버를 사용하려면:

Claude Desktop 구성을 생성하거나 편집하세요.
# On macOS nano ~/Library/Application\ Support/Claude/claude_desktop_config.json # On Linux nano ~/.config/Claude/claude_desktop_config.json # On Windows notepad %APPDATA%\Claude\claude_desktop_config.json
MCP 서버 구성을 추가합니다.
{ "mcpServers": { "homeassistant-mcp": { "command": "npx", "args": ["homeassistant-mcp"], "env": { "HASS_TOKEN": "your_home_assistant_token_here", "HASS_HOST": "http://your_home_assistant_host:8123" } } } }
Claude Desktop을 다시 시작합니다.
이제 Claude에서 Home Assistant MCP 도구를 사용할 수 있습니다.

JSON-RPC 2.0 메시지 형식

용법

NPX 사용하기 (가장 쉬움)

Home Assistant MCP 서버를 사용하는 가장 간단한 방법은 NPX를 사용하는 것입니다.

# Start the server in stdio mode
npx homeassistant-mcp

이렇게 하면 자동으로 다음이 수행됩니다.

stdio 모드로 서버를 시작합니다
JSON-RPC 메시지를 stdout으로 출력
stderr로 로그 메시지를 보냅니다.
로그 디렉토리가 없으면 생성하세요.

stderr을 리디렉션하여 로그를 숨기고 JSON-RPC 출력만 볼 수 있습니다.

npx homeassistant-mcp 2>/dev/null

수동 설치

패키지를 글로벌 또는 로컬로 설치하려면 다음을 수행하세요.

# Install globally
npm install -g homeassistant-mcp

# Then run
homeassistant-mcp

또는 로컬로 설치:

# Install locally
npm install homeassistant-mcp

# Then run using npx
npx homeassistant-mcp

Integrations

홈 어시스턴트 모델 컨텍스트 프로토콜(MCP)

개요

특징

시작하기

필수 조건

설치

서버 실행

구성

건축학

도구

API

AI 모델과의 통합

클로드 통합

커서 통합

커서 통합 문제 해결

특허

기여하다

홈 어시스턴트용 MCP 서버 🏠🤖

개요 🌐

핵심 기능 ✨

왜 Bun인가요? 🚀

필수 조건 📋

빠른 시작 🚀

Docker 빌드 옵션 🐳

1. 표준 빌드

2. 음성 지원 빌드

3. GPU 가속 빌드

빌드 기능

환경 구성 🔧

파일 구조 📁

로딩 우선순위 ⚡

개발 💻

성능 비교 📊

문서 📚

핵심 문서

고급 기능

클라이언트 통합 🔗

커서 통합 🖱️

클로드 데스크탑 💬

명령줄 💻

추가 기능

음성 기능 🎤

음성 기능 설정

필수 조건

구성

사용 가능한 모델 🤖

음성 기능으로 시작

추가 도구 🛠️

라이센스 📄

저자 👨‍💻

표준 I/O 전송으로 실행 📝

MCP Stdio 기능

옵션 1: NPX 사용(가장 쉬움)

Claude Desktop과 통합

옵션 2: 로컬 설치

JSON-RPC 2.0 메시지 형식

요청 형식

응답 형식

오류 응답 형식

알림 형식(서버에서 클라이언트로)

지원되는 오류 코드

Claude Desktop과 통합

JSON-RPC 2.0 메시지 형식

용법

NPX 사용하기 (가장 쉬움)

수동 설치

고급 사용법

Appeared in Searches