Ccu Mcp

io.github.claymore666/ccu-mcp · v1.11.8

MCP server for controlling HomeMatic smart home devices via the CCU JSON-RPC API

Source code Set it up

Connect Runs on your machine

Terminal

claude mcp add ccu-mcp -e CCU_HOST=<CCU_HOST> -e CCU_PASSWORD=<CCU_PASSWORD> -e CCU_USER=<CCU_USER> -e CCU_HTTPS=<CCU_HTTPS> -e CCU_PORT=<CCU_PORT> -e CACHE_DIR=<CACHE_DIR> -e MCP_ALLOWED_ORIGINS=<MCP_ALLOWED_ORIGINS> -e MCP_ALLOWED_HOSTS=<MCP_ALLOWED_HOSTS> -e CCU_PROFILES=<CCU_PROFILES> -e CCU_DEFAULT_PROFILE=<CCU_DEFAULT_PROFILE> -e CCU_TLS_VERIFY=<CCU_TLS_VERIFY> -e CCU_TLS_FINGERPRINT=<CCU_TLS_FINGERPRINT> -e CCU_CA_CERT=<CCU_CA_CERT> -e CCU_TIMEOUT=<CCU_TIMEOUT> -e CCU_SCRIPT_TIMEOUT=<CCU_SCRIPT_TIMEOUT> -e CACHE_TTL=<CACHE_TTL> -e CCU_RATE_LIMIT_BURST=<CCU_RATE_LIMIT_BURST> -e CCU_RATE_LIMIT_RATE=<CCU_RATE_LIMIT_RATE> -e RESOURCE_POLL_INTERVAL=<RESOURCE_POLL_INTERVAL> -e LOG_LEVEL=<LOG_LEVEL> -- npx -y [email protected]

claude_desktop_config.json

{
  "mcpServers": {
    "ccu-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "env": {
        "CCU_HOST": "<CCU_HOST>",
        "CCU_PASSWORD": "<CCU_PASSWORD>",
        "CCU_USER": "<CCU_USER>",
        "CCU_HTTPS": "<CCU_HTTPS>",
        "CCU_PORT": "<CCU_PORT>",
        "CACHE_DIR": "<CACHE_DIR>",
        "MCP_ALLOWED_ORIGINS": "<MCP_ALLOWED_ORIGINS>",
        "MCP_ALLOWED_HOSTS": "<MCP_ALLOWED_HOSTS>",
        "CCU_PROFILES": "<CCU_PROFILES>",
        "CCU_DEFAULT_PROFILE": "<CCU_DEFAULT_PROFILE>",
        "CCU_TLS_VERIFY": "<CCU_TLS_VERIFY>",
        "CCU_TLS_FINGERPRINT": "<CCU_TLS_FINGERPRINT>",
        "CCU_CA_CERT": "<CCU_CA_CERT>",
        "CCU_TIMEOUT": "<CCU_TIMEOUT>",
        "CCU_SCRIPT_TIMEOUT": "<CCU_SCRIPT_TIMEOUT>",
        "CACHE_TTL": "<CACHE_TTL>",
        "CCU_RATE_LIMIT_BURST": "<CCU_RATE_LIMIT_BURST>",
        "CCU_RATE_LIMIT_RATE": "<CCU_RATE_LIMIT_RATE>",
        "RESOURCE_POLL_INTERVAL": "<RESOURCE_POLL_INTERVAL>",
        "LOG_LEVEL": "<LOG_LEVEL>"
      }
    }
  }
}

~/.cursor/mcp.json

{
  "mcpServers": {
    "ccu-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "env": {
        "CCU_HOST": "<CCU_HOST>",
        "CCU_PASSWORD": "<CCU_PASSWORD>",
        "CCU_USER": "<CCU_USER>",
        "CCU_HTTPS": "<CCU_HTTPS>",
        "CCU_PORT": "<CCU_PORT>",
        "CACHE_DIR": "<CACHE_DIR>",
        "MCP_ALLOWED_ORIGINS": "<MCP_ALLOWED_ORIGINS>",
        "MCP_ALLOWED_HOSTS": "<MCP_ALLOWED_HOSTS>",
        "CCU_PROFILES": "<CCU_PROFILES>",
        "CCU_DEFAULT_PROFILE": "<CCU_DEFAULT_PROFILE>",
        "CCU_TLS_VERIFY": "<CCU_TLS_VERIFY>",
        "CCU_TLS_FINGERPRINT": "<CCU_TLS_FINGERPRINT>",
        "CCU_CA_CERT": "<CCU_CA_CERT>",
        "CCU_TIMEOUT": "<CCU_TIMEOUT>",
        "CCU_SCRIPT_TIMEOUT": "<CCU_SCRIPT_TIMEOUT>",
        "CACHE_TTL": "<CACHE_TTL>",
        "CCU_RATE_LIMIT_BURST": "<CCU_RATE_LIMIT_BURST>",
        "CCU_RATE_LIMIT_RATE": "<CCU_RATE_LIMIT_RATE>",
        "RESOURCE_POLL_INTERVAL": "<RESOURCE_POLL_INTERVAL>",
        "LOG_LEVEL": "<LOG_LEVEL>"
      }
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "ccu-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "env": {
        "CCU_HOST": "<CCU_HOST>",
        "CCU_PASSWORD": "<CCU_PASSWORD>",
        "CCU_USER": "<CCU_USER>",
        "CCU_HTTPS": "<CCU_HTTPS>",
        "CCU_PORT": "<CCU_PORT>",
        "CACHE_DIR": "<CACHE_DIR>",
        "MCP_ALLOWED_ORIGINS": "<MCP_ALLOWED_ORIGINS>",
        "MCP_ALLOWED_HOSTS": "<MCP_ALLOWED_HOSTS>",
        "CCU_PROFILES": "<CCU_PROFILES>",
        "CCU_DEFAULT_PROFILE": "<CCU_DEFAULT_PROFILE>",
        "CCU_TLS_VERIFY": "<CCU_TLS_VERIFY>",
        "CCU_TLS_FINGERPRINT": "<CCU_TLS_FINGERPRINT>",
        "CCU_CA_CERT": "<CCU_CA_CERT>",
        "CCU_TIMEOUT": "<CCU_TIMEOUT>",
        "CCU_SCRIPT_TIMEOUT": "<CCU_SCRIPT_TIMEOUT>",
        "CACHE_TTL": "<CACHE_TTL>",
        "CCU_RATE_LIMIT_BURST": "<CCU_RATE_LIMIT_BURST>",
        "CCU_RATE_LIMIT_RATE": "<CCU_RATE_LIMIT_RATE>",
        "RESOURCE_POLL_INTERVAL": "<RESOURCE_POLL_INTERVAL>",
        "LOG_LEVEL": "<LOG_LEVEL>"
      }
    }
  }
}

Replace the values in angle brackets with your own. Keys stay on your machine; we never see them.

Tools

This server runs locally, so its tools are listed by your MCP client once it starts.

Environment variables

Name	Description
`CCU_HOST` Required	Hostname or IP of your HomeMatic CCU (debmatic, CCU3, or OpenCCU/RaspberryMatic)
`CCU_PASSWORD` Required, secret	CCU admin password (same as the WebUI login). Must be set; the value may be empty for a CCU with no password
`CCU_USER` Optional	CCU username
`CCU_HTTPS` Optional	Connect to the CCU via HTTPS (self-signed certificates supported)
`CCU_PORT` Optional	CCU API port (80 for HTTP, 443 for HTTPS)
`CACHE_DIR` Optional	Directory for the device type cache and session persistence
`MCP_ALLOWED_ORIGINS` Optional	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` Optional	Extra Host header values accepted by DNS-rebinding protection (comma-separated host:port); add your hostname when behind a proxy or container DNS name
`CCU_PROFILES` Optional	Comma-separated names of multiple CCU targets (e.g. 'prod,dev'). Each profile takes the flat CCU_* settings prefixed CCU_<NAME>_ (CCU_PROD_HOST, ...), plus policy flags CCU_<NAME>_PROTECTED (writes need confirm:true) and CCU_<NAME>_READONLY. Unset = single default profile from the flat CCU_* vars
`CCU_DEFAULT_PROFILE` Optional	Which profile from CCU_PROFILES is active at startup (default: the first listed)
`CCU_TLS_VERIFY` Optional	Verify the CCU's TLS certificate against the system trust store. Only meaningful with CCU_HTTPS=true. Default false, because a CCU ships a self-signed certificate — prefer CCU_TLS_FINGERPRINT or CCU_CA_CERT to verify one of those
`CCU_TLS_FINGERPRINT` Optional	Pin the CCU's self-signed leaf certificate by its SHA-256 fingerprint (hex, colons optional). The strongest option for an appliance: the connection is rejected unless the presented certificate matches. Takes precedence over CCU_CA_CERT
`CCU_CA_CERT` Optional	Path to a PEM file holding the CCU's CA or self-signed certificate. The connection is then validated against it with standard chain verification
`CCU_TIMEOUT` Optional	Timeout for a CCU JSON-RPC call, in MILLISECONDS
`CCU_SCRIPT_TIMEOUT` Optional	Timeout for HomeMatic Script execution (ReGa), in MILLISECONDS — scripts are slower than plain API calls
`CACHE_TTL` Optional	Lifetime of the on-disk device-type schema cache, in SECONDS
`CCU_RATE_LIMIT_BURST` Optional	Token-bucket burst size for CCU requests — how many may be issued back to back
`CCU_RATE_LIMIT_RATE` Optional	Sustained CCU request rate, in requests per second
`RESOURCE_POLL_INTERVAL` Optional	How often MCP resources are polled for change notifications, in SECONDS
`LOG_LEVEL` Optional	error \| warn \| info \| debug. Logs are structured JSON on stderr

Details

Package	`[email protected]` (NPM, stdio)
First published	10 Nov 2026
Last updated	10 Nov 2026
Registry name	`io.github.claymore666/ccu-mcp`

More other servers See all

Live status

Local install

Installed and run on your own machine, so there is no public endpoint to check.

Pair it with live search

Agents that use Ccu Mcp often also need current facts. NestDaddy MCP gives your AI today's internet: web search, real-time breaking news and full page reading in one connector.

See NestDaddy MCP

For maintainers

[![NestDaddy MCP](https://nestdaddy.com/mcp/servers/io-github-claymore666-ccu-mcp/badge.svg)](https://nestdaddy.com/mcp/servers/io-github-claymore666-ccu-mcp)

Add the badge to your README. It turns green while your server passes our daily check. Listing details come from the official MCP registry; update them there.

Listing data from the official MCP registry. Status and tools from NestDaddy's daily check. Browse all MCP servers.