ccu-mcp

ccu-mcp is a Model Context Protocol (MCP) server that bridges AI assistants (like Claude, Cursor, or any MCP client) to HomeMatic smart home systems. It connects directly to the CCU's built-in JSON-RPC API (via `/api/homematic.cgi`), eliminating the need for addons, XML-API, or cloud services. It works with any HomeMatic CCU, including debmatic, CCU3, and OpenCCU (formerly RaspberryMatic). The server handles device discovery, type resolution, session management, and value conversion, exposing tools that let users ask natural-language questions like "What's the temperature in the bathroom?", "Are any windows open?", "Set the living room heating to 21 degrees", or "Show me all devices with low battery". It also supports advanced operations like renaming devices to follow naming conventions, finding mismatched channel names, and checking device health. **Key Features:** - **Direct CCU connection**: No addons or cloud; uses the standard JSON-RPC endpoint. - **Multiple transports**: Run as a subprocess (stdio) or as a standalone HTTP server (Docker). - **Docker support**: Published images for linux/amd64 and linux/arm64, with attestation for supply-chain security. - **Multiple CCU profiles**: Configure and switch between several CCUs (e.g., prod and dev) from one server. - **Security**: Bearer token authentication (auto-generated or explicit), DNS-rebinding protection, CORS allowlist, TLS support (including self-signed cert pinning), and optional fail2ban integration. - **Setup wizard**: Interactive `init` command probes the CCU, pins TLS certificates, tests login, and writes a ready-to-use `.env` file. A conversational setup mode lets an LLM guide the process via chat. - **Diagnostics**: `doctor` command validates configuration end-to-end. - **Rate limiting**: Built-in burst and sustained rate limits to protect the CCU. - **Resource polling**: Optional polling for MCP resource change notifications. **Installation & Usage:** - **Quick start (stdio)**: Set `CCU_HOST` and `CCU_PASSWORD` environment variables, then run `npx ccu-mcp --stdio`. Configure your MCP client (e.g., Claude Code) with a `.mcp.json` file. - **Docker (HTTP)**: Pull the image, run with environment variables, and obtain the auth token from the container's data volume. Configure the client with the server URL and bearer token. - **Configuration**: All settings via environment variables (see table in README). Supports inline env, `.env` files, or shell exports. - **CLI flags**: `init`, `doctor`, `secret`, `--stdio`, `--http`, `--env`, `--version`, `--help`. **Security Considerations:** - The server defaults to plain HTTP but warns when serving tokens over non-loopback interfaces; set `MCP_ALLOW_PLAINTEXT=true` to acknowledge. - For remote access, use TLS (reverse proxy or native HTTPS) and set `MCP_ALLOWED_HOSTS` to avoid 403 errors. - Token rotation is supported with grace periods to avoid client disruption. - CORS is default-deny; allowlist origins for browser-based clients. **Requirements:** Node.js 24+ (for source/stdio) or Docker. A running HomeMatic CCU with admin credentials. **Example Client Config (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" } } } } ``` **Example Client Config (HTTP):** ```json { "mcpServers": { "ccu-mcp": { "url": "http://your-server-ip:3000", "headers": { "Authorization": "Bearer PASTE-YOUR-TOKEN-HERE" } } } } ``` The project is open-source and welcomes contributions. It includes badges for OpenSSF Best Practices and Scorecard, indicating a focus on security and quality.