Power your agent
The publisher's own command. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code has no install link for a local command. Copy the command below and run it in a terminal.
CCU_HOST=<value> CCU_PASSWORD=<secret> CCU_USER=<value> CCU_HTTPS=<value> CCU_PORT=<value> CACHE_DIR=<value> MCP_ALLOWED_ORIGINS=<value> MCP_ALLOWED_HOSTS=<value> CCU_PROFILES=<value> CCU_DEFAULT_PROFILE=<value> CCU_TLS_VERIFY=<value> CCU_TLS_FINGERPRINT=<value> CCU_CA_CERT=<value> CCU_TIMEOUT=<value> CCU_SCRIPT_TIMEOUT=<value> CACHE_TTL=<value> CCU_RATE_LIMIT_BURST=<value> CCU_RATE_LIMIT_RATE=<value> RESOURCE_POLL_INTERVAL=<value> LOG_LEVEL=<value> claude mcp add io.github.claymore666-ccu-mcp -- npx -y ccu-mcp@1.11.8Run in a terminal.
{ "mcpServers": { "io.github.claymore666-ccu-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "CCU_HOST": "<value>", "CCU_PASSWORD": "<secret>", "CCU_USER": "<value>", "CCU_HTTPS": "<value>", "CCU_PORT": "<value>", "CACHE_DIR": "<value>", "MCP_ALLOWED_ORIGINS": "<value>", "MCP_ALLOWED_HOSTS": "<value>", "CCU_PROFILES": "<value>", "CCU_DEFAULT_PROFILE": "<value>", "CCU_TLS_VERIFY": "<value>", "CCU_TLS_FINGERPRINT": "<value>", "CCU_CA_CERT": "<value>", "CCU_TIMEOUT": "<value>", "CCU_SCRIPT_TIMEOUT": "<value>", "CACHE_TTL": "<value>", "CCU_RATE_LIMIT_BURST": "<value>", "CCU_RATE_LIMIT_RATE": "<value>", "RESOURCE_POLL_INTERVAL": "<value>", "LOG_LEVEL": "<value>" } } }}claude_desktop_config.json
Remote URL or a command on your machine? How the two installs differ
From the publisher
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.
MCP server for controlling HomeMatic smart home devices via the CCU JSON-RPC API
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchWorks with any HomeMatic CCU: debmatic (HomeMatic on Debian), a CCU3, or OpenCCU (formerly RaspberryMatic) — anything that exposes the standard /api/homematic.cgi endpoint.
Ask your AI assistant things like:
The MCP server handles device discovery, type resolution, session management, and value conversion — the AI just calls the tools.
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.
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.
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
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_HOSTSis required for remote clients. The server's DNS-rebinding protection rejects any request whoseHostheader isn't on the allowlist — by default onlylocalhost/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
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:
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.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!
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:
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
CCU_CA_CERT at the certificate file for standard chain validation.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).
All configuration is via environment variables:
To drive several CCUs from one server, these flat CCU_* vars are replaced
by named profiles — see Multiple CCU targets
below.
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.
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.
.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.
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:
CCU_<NAME>_PROTECTED=true — write tools refuse unless called with
confirm: true, which unlocks writes to that target for the rest of the session.
Exception: run_script and delete_system_variable require confirm: true on
every call — they never ride on the session unlock (scripts bypass all
typed-tool guards; deletion is unrecoverable), and confirming them does not
unlock the session for other writes.CCU_<NAME>_READONLY=true — write tools are refused outright.With CCU_PROFILES unset, the flat CCU_* vars are used as a single default
profile (unchanged behavior). At runtime, list_ccu_targets shows the targets,
get_connection_info reports the active one, and use_ccu switches it. Read
tools also accept an optional target to read from another CCU for a single call
without switching.
With the wizard. ccu-mcp init asks up front, then loops over name →
endpoint → certificate pin → credentials → policy flags per target, and ends
by asking which one starts active:
$ npx ccu-mcp init --env ~/.config/ccu-mcp/.env
ccu-mcp setup — probes your CCU, pins its TLS certificate, tests the
login, and writes the result to /home/you/.config/ccu-mcp/.env.
Set up multiple CCU targets (e.g. prod/dev)? [y/N]: y
Profile name [prod]: prod
CCU hostname or IP: ccu.example
Probing ccu.example ...
Found the CCU API on port 443 (HTTPS).
Use HTTPS? [Y/n]: y
Port [443]: 443
The CCU presents this TLS certificate:
Subject: ccu.example
Issuer: ccu.example
Valid: Jun 19 21:37:09 2026 GMT — Jun 16 21:37:09 2036 GMT
SHA-256: 90:0C:4C:F2:53:22:E7:78:...:40:ED:16:95:6E:BB:B1:53
Pin this certificate's fingerprint (recommended)? [Y/n]: y
CCU user [Admin]: ai
CCU password (input hidden):
Testing login ...
Login OK (CCU 3.87.6.20260614) — privilege level ADMIN: all tools available.
Protect this target (write tools then require confirm:true)? [y/N]: y
Make this target read-only (write tools refused entirely)? [y/N]: n
Add another CCU target? [y/N]: y
Profile name: dev
CCU hostname or IP: 192.168.1.50
Probing 192.168.1.50 ...
Found the CCU API on port 80 (HTTP).
Use HTTPS? [Y/n]: n
Port [80]: 80
CCU user [Admin]: Admin
CCU password (input hidden):
Testing login ...
Login OK (CCU 3.87.6.20260614) — privilege level ADMIN: all tools available.
Protect this target (write tools then require confirm:true)? [y/N]: n
Make this target read-only (write tools refused entirely)? [y/N]: n
Add another CCU target? [y/N]: n
Default target (prod/dev) [prod]: prod
Wrote /home/you/.config/ccu-mcp/.env (mode 0600).
The file it writes is the profile form, one commented block per target — and
the wizard rewrites only these keys, so anything else in the file (LOG_LEVEL,
CACHE_DIR, MCP_*) survives:
# Written by ccu-mcp setup — https://github.com/claymore666/ccu-mcp#configuration
CCU_PROFILES=prod,dev
CCU_DEFAULT_PROFILE=prod
# --- target: prod ---
CCU_PROD_HOST=ccu.example
CCU_PROD_PORT=443
CCU_PROD_HTTPS=true
CCU_PROD_USER=ai
CCU_PROD_PASSWORD="..."
CCU_PROD_TLS_FINGERPRINT=90:0C:4C:F2:53:22:E7:78:...:40:ED:16:95:6E:BB:B1:53
CCU_PROD_PROTECTED=true
# --- target: dev ---
CCU_DEV_HOST=192.168.1.50
CCU_DEV_PORT=80
CCU_DEV_HTTPS=false
CCU_DEV_USER=Admin
CCU_DEV_PASSWORD=""
Rerunning init on an existing file offers to replace those settings; adding a
third target means walking the whole list again, so for a one-off addition edit
the file (or use setup_write_profile, which upserts a single target) and then
run doctor.
One password per target. ccu-mcp secret writes exactly one key, so it
takes the target name — init prompts for passwords inline, but the
LLM-guided flow and every later rotation go
through secret. Called without a name on a profile file it lists the runs you
need:
$ ccu-mcp secret --env ~/.config/ccu-mcp/.env
This file configures named targets (prod, dev) — one password each:
node /home/you/.local/bin/ccu-mcp secret prod --env /home/you/.config/ccu-mcp/.env
node /home/you/.local/bin/ccu-mcp secret dev --env /home/you/.config/ccu-mcp/.env
$ ccu-mcp secret prod --env ~/.config/ccu-mcp/.env
CCU password for [email protected] (input hidden):
Wrote CCU_PROD_PASSWORD to /home/you/.config/ccu-mcp/.env (mode 0600).
Those hints come out as node <path> rather than ccu-mcp on purpose: the
path is the build that printed them, so copying the line cannot land on some
older copy that lacks the subcommand. secret refuses a name against a flat
single-CCU file, and refuses an unknown one against a profile file, so it can
never write the wrong key.
Verify everything at once. doctor walks every target — configuration,
reachability, pin, login and privilege level — and exits non-zero if any check
fails:
$ ccu-mcp doctor --env ~/.config/ccu-mcp/.env
ccu-mcp doctor — checking /home/you/.config/ccu-mcp/.env
✓ configuration loads: 2 target(s), default "prod"
Target "prod" — ccu.example:443 (HTTPS)
✓ CCU API reachable
✓ pinned TLS fingerprint matches the presented certificate
✓ login OK as "ai" (CCU 3.87.6.20260614) — privilege level ADMIN
Target "dev" — 192.168.1.50:80 (HTTP)
✓ CCU API reachable
✓ login OK as "Admin" (CCU 3.87.6.20260614) — privilege level ADMIN
All checks passed.
In the client. One MCP server entry serves all targets — the --env file
carries the roster, so nothing about the client config changes when you add a
CCU:
{
"mcpServers": {
"ccu-mcp": {
"command": "npx",
"args": ["ccu-mcp", "--stdio", "--env", "/home/you/.config/ccu-mcp/.env"]
}
}
}
Then, in chat: "which CCUs are configured?" (list_ccu_targets), "read the
living-room temperature on dev" (a one-call target: "dev"), "switch to
dev" (use_ccu). With CCU_PROD_PROTECTED=true as above, the first write
against prod comes back asking for confirm: true and unlocks that target for
the rest of the session — except run_script and delete_system_variable,
which ask every time.
Some mistakes stop the server at startup instead of being ignored. Each of these
would otherwise fail silently and much later, so the exit is deliberate.
ccu-mcp doctor reports the same errors against an env file without starting
the server, alongside its live checks (reachability, certificate pin, login).
One exception: started with --stdio --env <path>, a failing configuration
enters setup mode (with the error in the
server's instructions) instead of exiting, so it can be fixed conversationally:
ccu-mcp --version and --help work without any configuration, so they stay
usable while you sort one of these out.
28 tools organized by what you'd actually want to do:
Find things — list_devices, list_rooms, list_functions, list_interfaces, list_programs, list_system_variables, list_links, describe_device_type
Read state — get_value, get_values (bulk), get_paramset
Change things — set_value, put_paramset, set_system_variable, create_system_variable, delete_system_variable, assign_channel, unassign_channel, execute_program
Check health — get_service_messages, acknowledge_service_messages, get_rssi, get_system_info
Switch targets — list_ccu_targets, get_connection_info, use_ccu (multi-CCU profiles; see above)
Other — help (context-aware), run_script (raw HomeMatic Script for bulk operations, renaming devices/channels, querying room membership, or anything not covered by the other tools)
Most tools auto-resolve the interface and value types from the device address — you don't need to know whether a device is on BidCos-RF or HmIP-RF.
Besides tools, the server exposes MCP resources — browsable JSON snapshots your client can attach as context:
homematic://devices, homematic://rooms, homematic://functions, homematic://programs, homematic://sysvars, homematic://interfaces, homematic://device-types, homematic://system
The server polls the CCU in the background (every RESOURCE_POLL_INTERVAL seconds) and sends notifications/resources/updated for resources whose content changed — to clients that subscribed to them via resources/subscribe.
It also ships MCP prompts — ready-made workflows you can invoke from clients that support them (e.g. as slash commands in Claude Code):
check-windows — are any windows or doors open?room-status — full status report for one roomset-heating — set a room's target temperaturegood-night — prepare the house for nightdiagnostics — check for device issuesdevice-info — detailed info about a device's capabilities and parametersThe room and device arguments autocomplete: clients that support
completion/complete offer the rooms and device names this CCU actually has,
so there's no need to remember how a room was spelled in the WebUI.
The server implements revision 2025-11-25 and negotiates down for older
clients (2025-06-18, 2025-03-26, 2024-11-05 are all accepted) — you do
not need a particular client version. It advertises tools, resources
(with subscribe), prompts, completions and logging.
Revision 2026-07-28 — per-request protocol version, server/discover — is
not implemented yet: the TypeScript SDK this server is built on does not
support it at the time of writing, and this server follows the SDK.
The server talks to the CCU's JSON-RPC API (the same one the WebUI uses). On startup it:
Device type schemas are cached locally so the AI can look up valid parameters, types, and value ranges without hitting the CCU every time.
Values come back as native types — 21.5 not "21.500000", true not "true".
This has been tested against a production debmatic installation with:
Other device types should work too — the server queries the CCU for parameter descriptions rather than maintaining a static device database.
Release notes — including behavior changes to check before upgrading
(stricter config validation, /health response shape, per-session write
confirmation, retry semantics) — live in CHANGELOG.md.
claymore666.Everyone taking part is expected to follow the Code of Conduct.
MIT
© 2026 MCP Directory.
MCP server for controlling HomeMatic smart home devices via the CCU JSON-RPC API
{ "mcpServers": { "io.github.claymore666-ccu-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "CCU_HOST": "<value>", "CCU_PASSWORD": "<secret>", "CCU_USER": "<value>", "CCU_HTTPS": "<value>", "CCU_PORT": "<value>", "CACHE_DIR": "<value>", "MCP_ALLOWED_ORIGINS": "<value>", "MCP_ALLOWED_HOSTS": "<value>", "CCU_PROFILES": "<value>", "CCU_DEFAULT_PROFILE": "<value>", "CCU_TLS_VERIFY": "<value>", "CCU_TLS_FINGERPRINT": "<value>", "CCU_CA_CERT": "<value>", "CCU_TIMEOUT": "<value>", "CCU_SCRIPT_TIMEOUT": "<value>", "CACHE_TTL": "<value>", "CCU_RATE_LIMIT_BURST": "<value>", "CCU_RATE_LIMIT_RATE": "<value>", "RESOURCE_POLL_INTERVAL": "<value>", "LOG_LEVEL": "<value>" } } }}Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
The publisher lists these environment variables: CCU_HOST, CCU_PASSWORD, CCU_USER, CCU_HTTPS, CCU_PORT, CACHE_DIR, MCP_ALLOWED_ORIGINS, MCP_ALLOWED_HOSTS, CCU_PROFILES, CCU_DEFAULT_PROFILE, CCU_TLS_VERIFY, CCU_TLS_FINGERPRINT, CCU_CA_CERT, CCU_TIMEOUT, CCU_SCRIPT_TIMEOUT, CACHE_TTL, CCU_RATE_LIMIT_BURST, CCU_RATE_LIMIT_RATE, RESOURCE_POLL_INTERVAL, LOG_LEVEL.
Ccu runs locally over stdio.
Last checked 2026-11-13. MCP server for controlling HomeMatic smart home devices via the CCU JSON-RPC API