claymore666/debmatic-mcp

Talk to your HomeMatic smart home from Claude, Cursor, or any MCP client.
ccu-mcp connects to the CCU's built-in JSON-RPC API and exposes your devices, rooms, programs, and system variables as MCP tools. No addons, no XML-API, no cloud — just a direct connection to the CCU on your local network.
Works with any HomeMatic CCU: debmatic (HomeMatic on Debian), a CCU3, or OpenCCU (formerly RaspberryMatic) — anything that exposes the standard /api/homematic.cgi endpoint.
What can it do?
Ask your AI assistant things like:
- "What's the temperature in the bathroom?"
- "Are any windows open?"
- "Set the living room heating to 21 degrees"
- "Show me all devices with low battery"
- "What's the gas meter reading?"
- "Which devices have low battery or haven't been seen in a long time?"
- "Find all channels whose names don't match their device name"
- "Rename all devices to follow a consistent naming convention with floor labels (UG/OG/EG)"
- "Which room is the window sensor in?"
The MCP server handles device discovery, type resolution, session management, and value conversion — the AI just calls the tools.
Prerequisites
- A running HomeMatic CCU (debmatic, CCU3, or OpenCCU — formerly RaspberryMatic) reachable on your network
- The CCU's admin username and password (the same credentials you use to log into the WebUI)
- Node.js 24+ (for running from source or stdio mode) or Docker
Quick start
If it prints server_ready to stderr, it's working. Press Ctrl+C to stop. Now set it up in your MCP client — see below.
A cache_save_failed … mkdir '/data' line alongside it is harmless here but
worth fixing for real use: CACHE_DIR defaults to /data (the Docker layout),
so outside a container the device-type cache and the CCU session are never
persisted between runs. Point it somewhere writable:
export CACHE_DIR="$HOME/.cache/ccu-mcp" (or the same key in your .env /
env block).
Prefer a guided setup? npx ccu-mcp init probes your CCU, pins its TLS
certificate, tests the login, writes a ready-to-use .env file, and prints the
matching MCP client config — see Command-line flags.
Installation
There are two ways to run this: **stdio** (the server runs as a subprocess of your MCP client) or **HTTP** (the server runs standalone in Docker and clients connect over the network). Pick one.
Option A: stdio (direct, simplest)
This is the easiest setup. Your MCP client (Claude Code, Cursor, etc.) starts the server as a child process — no Docker, no network config, no auth tokens.
For Claude Code, create a .mcp.json file in your project directory (or any directory where you'll use Claude Code):
Replace your-ccu-hostname-or-ip with your CCU's hostname (like homematic-ccu3) or IP (like 192.168.1.50), and your-ccu-admin-password with the password you use to log into the CCU WebUI.
Restart Claude Code. Run /mcp to check it connected. You should see ccu-mcp in the list.
Alternatively, use the Claude Code CLI:
Option B: Docker (standalone HTTP server)
Use this if you want the server running independently — for example on a home server, accessible to multiple clients, or when your MCP client supports HTTP remotes.
**1. Start the container.** Images are published to GHCR for linux/amd64 and
linux/arm64 (so a Raspberry Pi next to the CCU works), built natively on each
architecture and attested — gh attestation verify oci://ghcr.io/claymore666/ccu-mcp:latest --repo claymore666/ccu-mcp
proves the image came from this repository's release workflow.
Every release also publishes its own X.Y.Z tag — pin that instead of latest
if you'd rather upgrade deliberately. To build from source instead:
Then run it:
> **MCP_ALLOWED_HOSTS is required for remote clients.** The server's
> DNS-rebinding protection rejects any request whose Host header isn't on
> the allowlist — by default only localhost/127.0.0.1/[::1] on the MCP
> port. Set it to every name/IP clients will use to reach the server
> (comma-separated, host:port). Without it, the local health check works
> but every remote MCP request gets **403 Invalid Host header**.
**2. Get the auth token.** The server generates a random bearer token on first startup and saves it inside the container's data volume. You need this token to authenticate your MCP client. Grab it with:
This prints something like MCP_AUTH_TOKEN=e96suzi1iG0H-GPif6K2.... The part after = is your token.
**3. Configure your MCP client.** If your client uses .mcp.json, add the HTTP server:
To inject the token automatically (requires jq):
This only updates the ccu-mcp entry — other servers in your .mcp.json are left alone.