프로젝트 소개

ccu-mcp는 AI 어시스턴트(Claude, Cursor 또는 모든 MCP 클라이언트)를 HomeMatic 스마트 홈 시스템에 연결하는 Model Context Protocol(MCP) 서버입니다. CCU의 내장 JSON-RPC API(`/api/homematic.cgi`)에 직접 연결되므로 애드온, XML-API 또는 클라우드 서비스가 필요 없습니다. debmatic, CCU3, OpenCCU(이전 RaspberryMatic)를 포함한 모든 HomeMatic CCU에서 작동합니다. 이 서버는 기기 검색, 유형 해석, 세션 관리, 값 변환을 처리하며, 사용자가 "욕실 온도는?", "열린 창문이 있나?", "거실 난방을 21도로 설정해", "배터리 부족한 모든 기기 표시"와 같은 자연어 질문을 할 수 있는 도구를 노출합니다. 또한 명명 규칙에 따른 기기 이름 변경, 채널 이름 불일치 찾기, 기기 상태 확인과 같은 고급 작업도 지원합니다. **주요 기능:** - **직접 CCU 연결**: 애드온이나 클라우드 없이 표준 JSON-RPC 엔드포인트 사용. - **다중 전송**: 하위 프로세스(stdio) 또는 독립 HTTP 서버(Docker)로 실행. - **Docker 지원**: linux/amd64 및 linux/arm64용 이미지 게시, 공급망 보안을 위한 증명 포함. - **다중 CCU 프로필**: 하나의 서버에서 여러 CCU(예: 프로덕션 및 개발) 구성 및 전환. - **보안**: Bearer 토큰 인증(자동 생성 또는 명시적), DNS 리바인딩 보호, CORS 허용 목록, TLS 지원(자체 서명 인증서 핀닝 포함), 선택적 fail2ban 통합. - **설정 마법사**: 대화형 `init` 명령이 CCU를 프로브하고, TLS 인증서를 핀하고, 로그인을 테스트하고, 사용 준비된 `.env` 파일을 작성합니다. 대화형 설정 모드를 통해 LLM이 채팅으로 프로세스를 안내할 수 있습니다. - **진단**: `doctor` 명령이 구성을 종단 간 검증합니다. - **속도 제한**: CCU를 보호하기 위한 내장 버스트 및 지속 속도 제한. - **리소스 폴링**: MCP 리소스 변경 알림을 위한 선택적 폴링. **설치 및 사용:** - **빠른 시작(stdio)**: `CCU_HOST` 및 `CCU_PASSWORD` 환경 변수를 설정한 후 `npx ccu-mcp --stdio`를 실행합니다. `.mcp.json` 파일로 MCP 클라이언트(예: Claude Code)를 구성합니다. - **Docker(HTTP)**: 이미지를 가져오고 환경 변수로 실행한 후 컨테이너 데이터 볼륨에서 인증 토큰을 얻습니다. 서버 URL과 bearer 토큰으로 클라이언트를 구성합니다. - **구성**: 모든 설정은 환경 변수를 통해 이루어집니다(README의 표 참조). 인라인 env, `.env` 파일 또는 셸 내보내기를 지원합니다. - **CLI 플래그**: `init`, `doctor`, `secret`, `--stdio`, `--http`, `--env`, `--version`, `--help`. **보안 고려 사항:** - 서버는 기본적으로 일반 HTTP를 사용하지만 루프백이 아닌 인터페이스에서 토큰을 제공할 때 경고합니다. 인정하려면 `MCP_ALLOW_PLAINTEXT=true`를 설정하세요. - 원격 액세스의 경우 TLS(리버스 프록시 또는 기본 HTTPS)를 사용하고 403 오류를 피하려면 `MCP_ALLOWED_HOSTS`를 설정하세요. - 클라이언트 중단을 피하기 위해 유예 기간과 함께 토큰 회전이 지원됩니다. - CORS는 기본적으로 거부됩니다. 브라우저 기반 클라이언트를 위해 출처를 허용 목록에 추가하세요. **요구 사항:** Node.js 24+(소스/stdio용) 또는 Docker. 관리자 자격 증명이 있는 실행 중인 HomeMatic CCU. **예제 클라이언트 구성(stdio):** ```json { "mcpServers": { "ccu-mcp": { "command": "npx", "args": ["ccu-mcp", "--stdio"], "env": { "CCU_HOST": "your-ccu-hostname-or-ip", "CCU_PASSWORD": "your-ccu-admin-password" } } } } ``` **예제 클라이언트 구성(HTTP):** ```json { "mcpServers": { "ccu-mcp": { "url": "http://your-server-ip:3000", "headers": { "Authorization": "Bearer PASTE-YOUR-TOKEN-HERE" } } } } ``` 이 프로젝트는 오픈소스이며 기여를 환영합니다. OpenSSF 모범 사례 및 Scorecard 배지를 포함하여 보안과 품질에 중점을 두고 있음을 나타냅니다.