ccu-mcp

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 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):

{
  "mcpServers": {
    "ccu-mcp": {
      "command": "npx",
      "args": ["ccu-mcp", "--stdio"],
      "env": {
        "CCU_HOST": "your-ccu-hostname-or-ip",
        "CCU_PASSWORD": "your-ccu-admin-password"
      }
    }
  }
}

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:

claude mcp add ccu-mcp -- npx ccu-mcp --stdio

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.

docker pull ghcr.io/claymore666/ccu-mcp:latest

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:

git clone https://github.com/claymore666/ccu-mcp.git && cd ccu-mcp
docker build -t ghcr.io/claymore666/ccu-mcp .

Then run it:

docker run -d \
  --name ccu-mcp \
  -e CCU_HOST=your-ccu-hostname-or-ip \
  -e CCU_PASSWORD=your-ccu-admin-password \
  -e MCP_ALLOWED_HOSTS=your-server-ip:3000 \
  -v ccu-data:/data \
  -p 3000:3000 \
  ghcr.io/claymore666/ccu-mcp:latest

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:

docker exec ccu-mcp grep MCP_AUTH_TOKEN /data/.env

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:

{
  "mcpServers": {
    "ccu-mcp": {
      "url": "http://your-server-ip:3000",
      "headers": {
        "Authorization": "Bearer PASTE-YOUR-TOKEN-HERE"
      }
    }
  }
}

To inject the token automatically (requires jq):

TOKEN=$(docker exec ccu-mcp grep MCP_AUTH_TOKEN /data/.env | cut -d= -f2)
jq --arg t "$TOKEN" '.mcpServers["ccu-mcp"].headers.Authorization = "Bearer " + $t' .mcp.json > .mcp.json.tmp && mv .mcp.json.tmp .mcp.json

This only updates the ccu-mcp entry — other servers in your .mcp.json are left alone.

4. Check it's healthy:

curl http://localhost:3000/health

Browser-based clients (CORS)

By default the HTTP server sends no CORS headers, so a random web page can't drive a local instance. To let browser-based MCP clients like MCP Inspector connect directly, set MCP_ALLOWED_ORIGINS to a comma-separated allowlist of trusted origins (e.g. https://app.example,http://localhost:6274). A request whose Origin is on the list gets that exact origin reflected in Access-Control-Allow-Origin — never the wildcard *, which would let any site drive a local instance that controls real CCU hardware. A request from any other origin gets no CORS headers (the browser blocks it) and is rejected server-side by DNS-rebinding protection. Authentication is always enforced regardless: every MCP request needs the bearer token.

The HTTP transport also has DNS-rebinding protection on by default: it rejects requests whose Host header isn't localhost/127.0.0.1/[::1] on the configured port. If you reach the server under another hostname or IP (reverse proxy, container DNS name, the server's LAN address), list those hosts in MCP_ALLOWED_HOSTS or legitimate requests get a 403.

TLS. The bearer token travels in the request, so anything beyond loopback should be encrypted. You have two options: terminate TLS at a reverse proxy (Caddy/nginx) in front and bind the server to loopback (MCP_HOST=127.0.0.1), or let the server serve HTTPS itself by setting MCP_TLS_CERT and MCP_TLS_KEY to a PEM cert/key pair. Plain HTTP is still fully supported — it stays the zero-config default — but the server logs a warning at startup when it's serving the token over unencrypted HTTP on a non-loopback bind; set MCP_ALLOW_PLAINTEXT=true to acknowledge that and silence it.

Token rotation & expiry. By default the bearer token lives forever. Two optional, composable controls let you rotate it without dropping clients:

• Auto-generated token — set MCP_AUTH_TOKEN_TTL_DAYS (fractional days allowed) to give the generated token a lifetime. The server rotates it automatically at runtime shortly before it lapses (no restart needed; also on startup if it expired while the server was down), prints the new token on stderr, and keeps the just-replaced token validating for MCP_AUTH_TOKEN_GRACE_HOURS (default 24) so in-flight clients survive the swap. To force a rotation sooner, delete $CACHE_DIR/.env (or just its MCP_AUTH_TOKEN line) and restart.
• Explicit token — when you set MCP_AUTH_TOKEN yourself, you own its lifetime (TTL doesn't apply). To rotate, put the new token in MCP_AUTH_TOKEN, move the old one to MCP_AUTH_TOKEN_PREVIOUS, and restart; both are accepted during the overlap. Drop MCP_AUTH_TOKEN_PREVIOUS and restart once every client is on the new token. Comparison stays timing-safe across every currently-valid token.

Brute-force protection (fail2ban). The auto-generated token is 256 bits of randomness, so guessing it is infeasible. If you set MCP_AUTH_TOKEN yourself, make it long and random (e.g. openssl rand -base64 32) — a short or guessable token is the one case brute force matters. The server does not rate-limit or lock out failed logins in-process; that job belongs to a firewall-level tool like fail2ban, which bans the source IP before the request ever reaches the server. To make that easy, every rejected request logs a structured line to stderr:

{"ts":"2026-06-18T17:28:00.370Z","level":"warn","msg":"auth_failed","client":"203.0.113.7","hadToken":true}

Ready-to-use fail2ban config ships in fail2ban/: copy filter.d/ccu-mcp.conf to /etc/fail2ban/filter.d/ and the jail in jail.d/ccu-mcp.local to /etc/fail2ban/jail.d/ (it defaults to 5 failures in 10 minutes → 1-hour ban). The server logs to stderr, so point fail2ban at wherever you collect it — the journal (backend = systemd) when run as a unit, or a file when you redirect stderr/docker logs; both are spelled out in the jail file. Requires LOG_LEVEL=warn or lower (info, the default, is fine; error suppresses the line). Behind a reverse proxy the logged IP is the proxy's, so run fail2ban against the proxy's access log instead.

CORS support was first implemented by @marcinn2 in his fork marcinn2/debmatic-mcp — thanks!

HTTPS

If your CCU uses HTTPS (self-signed certificates are fine), add these environment variables:

CCU_HTTPS=true
CCU_PORT=443

The server accepts self-signed certificates automatically — certificate verification is off by default because CCUs ship with self-signed certs (the server logs a warning when running unverified). To actually verify the connection and close the MITM gap, you have three options:

• Pin the fingerprint (simplest for a self-signed appliance cert): set CCU_TLS_FINGERPRINT to the cert's SHA-256 (hex, with or without colons). The connection is rejected unless the CCU presents exactly that certificate. Read it with:

  echo | openssl s_client -connect "$CCU_HOST:443" 2>/dev/null | openssl x509 -noout -fingerprint -sha256
  

• Trust a CA/self-signed PEM: point CCU_CA_CERT at the certificate file for standard chain validation.
• System trust store: if your CCU has a publicly-trusted certificate, set CCU_TLS_VERIFY=true.

CCU_TLS_FINGERPRINT takes precedence over CCU_CA_CERT, which takes precedence over CCU_TLS_VERIFY.

ccu-mcp init does the pinning for you: it shows the certificate the CCU presents and writes the fingerprint into the env file on confirmation, and ccu-mcp doctor re-checks the pin later (offering a refresh after a legitimate certificate rotation).

Configuration

All configuration is via environment variables:

Variable	Default	Description
CCU_HOST	required	Hostname or IP of your CCU
CCU_PASSWORD	required	CCU admin password. Must be set, but may be empty for a box without one (a fresh OpenCCU)
CCU_USER	Admin	CCU username
CCU_PORT	80	API port (443 when using HTTPS)
CCU_HTTPS	false	Connect via HTTPS (self-signed certs supported)
CCU_TLS_VERIFY	false	Verify the CCU's TLS certificate against the system trust store (for a publicly-trusted cert)
CCU_TLS_FINGERPRINT	unset	Pin the CCU's self-signed leaf cert by its SHA-256 fingerprint (hex, colons optional). Takes precedence over the other TLS options
CCU_CA_CERT	unset	Path to the CCU's CA/self-signed PEM for chain validation
CCU_TIMEOUT	10000	CCU request timeout in milliseconds
CCU_SCRIPT_TIMEOUT	30000	HM Script execution timeout in milliseconds
LOG_LEVEL	info	error, warn, info, or debug
CACHE_DIR	/data	Where to store device type cache and session
CACHE_TTL	86400	Cache lifetime in seconds (24h)
MCP_TRANSPORT	http	http or stdio (the --stdio CLI flag overrides this)
MCP_PORT	3000	HTTP server port (HTTP mode only)
MCP_AUTH_TOKEN	auto-generated	Bearer token for HTTP mode; generated and saved to $CACHE_DIR/.env on first start
MCP_AUTH_TOKEN_PREVIOUS	unset	Previous bearer token, accepted alongside MCP_AUTH_TOKEN during a rotation overlap; remove it (and restart) to end the overlap. Explicit-token path only
MCP_AUTH_TOKEN_TTL_DAYS	unset (never expires)	Lifetime of the auto-generated token, in days (fractional allowed). The server auto-rotates it at runtime shortly before expiry (new token announced on stderr); ignored when MCP_AUTH_TOKEN is set
MCP_AUTH_TOKEN_GRACE_HOURS	24	Overlap (hours) after an auto-rotation during which the just-replaced token is still accepted
MCP_ALLOWED_ORIGINS	unset	Comma-separated allowlist of browser origins. Unset = no cross-origin browser access (default-deny). An allowlisted origin is reflected exactly in Access-Control-Allow-Origin (never *); the list also drives DNS-rebinding origin checks
MCP_ALLOWED_HOSTS	localhost/127.0.0.1/[::1] on the MCP port	Extra Host values accepted by DNS-rebinding protection (comma-separated host:port); add every name/IP clients use to reach the server (proxy, container DNS name, plain server IP)
MCP_HOST	unset (all interfaces)	Bind address for the HTTP listener; set 127.0.0.1 to restrict to loopback (e.g. behind a TLS-terminating proxy), which also silences the plaintext warning
MCP_TLS_CERT / MCP_TLS_KEY	unset	PEM cert/key paths. Set both to serve MCP over HTTPS natively; leave unset for plain HTTP. Setting only one is a configuration error
MCP_ALLOW_PLAINTEXT	false	Set true to acknowledge serving the bearer token over plain HTTP and silence the non-loopback plaintext warning
CCU_RATE_LIMIT_BURST	20	Max burst of requests sent to the CCU
CCU_RATE_LIMIT_RATE	10	Sustained CCU requests per second
RESOURCE_POLL_INTERVAL	60	Seconds between polls for MCP resource change notifications

To drive several CCUs from one server, these flat CCU_* vars are replaced by named profiles — see Multiple CCU targets below.

Command-line flags

ccu-mcp init           # interactive setup: probe the CCU, pin its TLS cert,
                       #   test the login, write an env file (default ./.env)
ccu-mcp doctor         # validate an env file end-to-end: reachability,
                       #   certificate pin, login, privilege level
ccu-mcp secret [prof]  # store ONE CCU password into an env file via a local
                       #   hidden prompt — name the target when the file
                       #   defines profiles, omit it for a single CCU (used by
                       #   the LLM-guided setup below; also the rotation path)
ccu-mcp --stdio        # serve over stdin/stdout (overrides MCP_TRANSPORT)
ccu-mcp --http         # serve over HTTP (default)
ccu-mcp --env <path>   # load configuration from a dotenv file (already-set
                       #   environment variables win); also accepted by
                       #   init/doctor/secret to pick the file they
                       #   write/check/update (default ./.env)
ccu-mcp --version      # print the installed version and exit
ccu-mcp --help         # print usage and exit

ccu-mcp init walks through one or more CCU targets (profiles) — it asks up front whether you want several, then loops over name, endpoint, certificate pin, credentials and the two policy flags per target and asks which one starts active. It detects whether each configured user is ADMIN- or USER-level (script-based tools need ADMIN), and ends with a ready-to-paste MCP client snippet. It needs no pre-existing configuration. ccu-mcp doctor exits non-zero when any check fails, so it also works in scripts; run it interactively to be offered a pin refresh when the CCU's certificate legitimately rotated. Worked example: Setting up several targets.

LLM-guided setup (setup mode)

The wizard has a conversational twin: register the server in an MCP client before configuring it. Started with --stdio --env <path> and a missing or incomplete configuration, the server comes up in setup mode — a minimal MCP server exposing only four setup_* tools (setup_status, setup_probe, setup_write_profile, setup_test) plus instructions that let the LLM walk you through the same probe → pin → test-login → write flow in plain chat.

{
  "mcpServers": {
    "ccu-mcp": {
      "command": "npx",
      "args": ["ccu-mcp", "--stdio", "--env", "/path/to/.env"]
    }
  }
}

Then just ask: "set up my CCU connection". One deliberate exception: the password never travels through the model or the chat transcript. setup_write_profile has no password parameter; instead the assistant hands you a one-liner to run in a terminal — npx ccu-mcp secret <profile> --env /path/to/.env, or the equivalent for however you installed it — which prompts locally with echo off and writes only the password into the file (mode 0600). Copy the command the tool prints rather than this one: it names the build that printed it, so it cannot land on an older install that lacks the subcommand. Once setup_test reports green, reconnect the MCP server and the identical client entry starts it fully configured.

Several CCUs work here too — say so ("I have a prod and a dev CCU") and the assistant repeats probe → write → secret per target: setup_write_profile takes a name (plus protected, readonly and makeDefault) and upserts that one target, preserving the others and their already-stored passwords. Each target needs its own ccu-mcp secret <name> run, and the server stays in setup mode until every configured target has one: reconnecting halfway through lands you back in setup mode, naming the target still missing a password and the exact secret command that finishes it. A CCU that genuinely has no password is not a missing one — write the key with an empty value (CCU_<NAME>_PASSWORD=) to say so deliberately.

Setup mode is stdio-only (an unconfigured HTTP endpoint that writes config files would be an unacceptable surface), and a bare start without --env still fails loudly instead of silently serving setup tools.

--version and --help need no configuration — use them to check what an installed copy actually is, e.g. after updating:

$ npx ccu-mcp@latest --version
1.10.0

Note that a bare npx ccu-mcp reuses the copy cached in ~/.npm/_npx without re-resolving against the registry; pin @latest (or clear that cache) when you want the newest release.

How to supply these (inline, .env, or export)

The required CCU_HOST / CCU_PASSWORD (and everything else) are environment variables. Provide them in whichever of these you prefer — you need just one:

• Inline in .mcp.json — the env block shown in Option A above. Simplest; self-contained.

• Shell export — as in Quick start above.

• A .env file — keeps secrets out of .mcp.json. Pass it with the server's own --env flag (this is also what ccu-mcp init writes and the snippet it prints):

  {
    "mcpServers": {
      "ccu-mcp": {
        "command": "npx",
        "args": ["ccu-mcp", "--stdio", "--env", "/path/to/.env"]
      }
    }
  }
  

  (Node's own --env-file= flag before the script path works too, but node refuses to start when that file doesn't exist yet, and it needs the full path to dist/index.js.)

  Copy .env.example to .env and fill it in (it documents every variable). Docker users can pass the same file with docker run --env-file .env or compose's env_file:. Keep .env gitignored.

Multiple CCU targets (profiles)

By default the CCU_* vars above configure a single CCU. To reach several CCUs (e.g. prod + dev) from one server, define named profiles instead. Set these the same way as any other config (inline, .env, or export — see above):

CCU_PROFILES=prod,dev
CCU_DEFAULT_PROFILE=prod           # active at startup (defaults to the first listed)

CCU_PROD_HOST=ccu.example
CCU_PROD_USER=ai
CCU_PROD_PASSWORD=...
CCU_PROD_HTTPS=true
CCU_PROD_PROTECTED=true            # writes need confirm:true

CCU_DEV_HOST=127.0.0.1
CCU_DEV_PORT=18080
CCU_DEV_USER=Admin
CCU_DEV_PASSWORD=                  # may be empty (e.g. an OpenCCU dev box)

Each profile takes the same settings as the flat vars, prefixed CCU_<NAME>_ (name upper-cased, non-alphanumerics → _): HOST (required), PASSWORD (may be empty — and, unlike the flat CCU_PASSWORD, may also be left out entirely, which reads as empty), USER, PORT, HTTPS, TIMEOUT, SCRIPT_TIMEOUT, TLS_FINGERPRINT, CA_CERT, TLS_VERIFY — plus two policy flags: