Ccu MCP server

<!-- Both badges stay on ONE source line: a block-level HTML comment between them would end the paragraph and stack them, which is what this used to do. The Scorecard badge reads api.scorecard.dev through shields' dynamic/json route, because Scorecard's own badge endpoint redirects to shields' ossf-scorecard route, which reads the LEGACY api.securityscorecards.dev — and that host 404s for this repo, rendering "invalid repo path" (as HTTP 200, so a status check does not catch it). Switch back to https://api.scorecard.dev/projects/github.com/claymore666/ccu-mcp/badge once curl -sS -o /dev/null -w '%{http_code}' https://api.securityscorecards.dev/projects/github.com/claymore666/ccu-mcp returns 200. -->

ccu-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

export CCU_HOST=your-ccu-hostname-or-ip
export CCU_PASSWORD=your-ccu-admin-password
npx ccu-mcp --stdio

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 cachesavefailed … mkdir '/data' line alongside it is harmless here but worth fixing for real use: CACHEDIR 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 CACHEDIR="$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)

Shortened. The full README is on GitHub.