ccu-mcp

ccu-mcp es un servidor del Protocolo de Contexto de Modelo (MCP) que conecta asistentes de IA (como Claude, Cursor o cualquier cliente MCP) con sistemas domóticos HomeMatic. Se conecta directamente a la API JSON-RPC integrada de la CCU (a través de `/api/homematic.cgi`), eliminando la necesidad de complementos, XML-API o servicios en la nube. Funciona con cualquier HomeMatic CCU, incluyendo debmatic, CCU3 y OpenCCU (anteriormente RaspberryMatic). El servidor gestiona el descubrimiento de dispositivos, la resolución de tipos, la gestión de sesiones y la conversión de valores, exponiendo herramientas que permiten a los usuarios hacer preguntas en lenguaje natural como "¿Cuál es la temperatura en el baño?", "¿Hay alguna ventana abierta?", "Pon la calefacción del salón a 21 grados" o "Muéstrame todos los dispositivos con batería baja". También admite operaciones avanzadas como renombrar dispositivos para seguir convenciones de nomenclatura, encontrar nombres de canales no coincidentes y comprobar el estado de salud de los dispositivos. **Características principales:** - **Conexión directa a la CCU**: Sin complementos ni nube; utiliza el endpoint JSON-RPC estándar. - **Múltiples transportes**: Ejecutar como subproceso (stdio) o como servidor HTTP independiente (Docker). - **Soporte Docker**: Imágenes publicadas para linux/amd64 y linux/arm64, con atestación para la seguridad de la cadena de suministro. - **Múltiples perfiles de CCU**: Configurar y cambiar entre varias CCU (por ejemplo, prod y dev) desde un solo servidor. - **Seguridad**: Autenticación con token Bearer (autogenerado o explícito), protección contra rebinding de DNS, lista blanca CORS, soporte TLS (incluida la fijación de certificados autofirmados) e integración opcional con fail2ban. - **Asistente de configuración**: El comando interactivo `init` sondea la CCU, fija los certificados TLS, prueba el inicio de sesión y escribe un archivo `.env` listo para usar. Un modo de configuración conversacional permite que un LLM guíe el proceso a través del chat. - **Diagnóstico**: El comando `doctor` valida la configuración de extremo a extremo. - **Límite de velocidad**: Límites de ráfaga y sostenidos integrados para proteger la CCU. - **Sondeo de recursos**: Sondeo opcional para notificaciones de cambios de recursos MCP. **Instalación y uso:** - **Inicio rápido (stdio)**: Establecer las variables de entorno `CCU_HOST` y `CCU_PASSWORD`, luego ejecutar `npx ccu-mcp --stdio`. Configurar el cliente MCP (por ejemplo, Claude Code) con un archivo `.mcp.json`. - **Docker (HTTP)**: Extraer la imagen, ejecutar con variables de entorno y obtener el token de autenticación del volumen de datos del contenedor. Configurar el cliente con la URL del servidor y el token Bearer. - **Configuración**: Todos los ajustes mediante variables de entorno (ver tabla en el README). Admite env en línea, archivos `.env` o exportaciones de shell. - **Opciones de CLI**: `init`, `doctor`, `secret`, `--stdio`, `--http`, `--env`, `--version`, `--help`. **Consideraciones de seguridad:** - El servidor usa HTTP plano por defecto, pero advierte al servir tokens en interfaces que no sean de bucle local; establecer `MCP_ALLOW_PLAINTEXT=true` para confirmar. - Para acceso remoto, usar TLS (proxy inverso o HTTPS nativo) y establecer `MCP_ALLOWED_HOSTS` para evitar errores 403. - La rotación de tokens es compatible con períodos de gracia para evitar interrupciones al cliente. - CORS está denegado por defecto; incluir en la lista blanca los orígenes para clientes basados en navegador. **Requisitos:** Node.js 24+ (para fuente/stdio) o Docker. Una HomeMatic CCU en ejecución con credenciales de administrador. **Ejemplo de configuración de cliente (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" } } } } ``` **Ejemplo de configuración de cliente (HTTP):** ```json { "mcpServers": { "ccu-mcp": { "url": "http://your-server-ip:3000", "headers": { "Authorization": "Bearer PASTE-YOUR-TOKEN-HERE" } } } } ``` El proyecto es de código abierto y acepta contribuciones. Incluye insignias de OpenSSF Best Practices y Scorecard, lo que indica un enfoque en la seguridad y la calidad.