Ccu MCP Server

by claymore666io.github.claymore666/ccu-mcpv1.11.4

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

9Node.jsstdioofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Active3d ago

Install Ccu MCP server

claude mcp add ccu -e CCU_HOST='<ccu-host>' -e CCU_PASSWORD='<ccu-password>' -- npx -y ccu-mcp --stdio

{
  "mcpServers": {
    "ccu": {
      "command": "npx",
      "args": [
        "-y",
        "ccu-mcp",
        "--stdio"
      ],
      "env": {
        "CCU_HOST": "<ccu-host>",
        "CCU_PASSWORD": "<ccu-password>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

{
  "mcpServers": {
    "ccu": {
      "command": "npx",
      "args": [
        "-y",
        "ccu-mcp",
        "--stdio"
      ],
      "env": {
        "CCU_HOST": "<ccu-host>",
        "CCU_PASSWORD": "<ccu-password>"
      }
    }
  }
}

Settings → Developer → Edit Config (claude_desktop_config.json), then restart.

{
  "servers": {
    "ccu": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "ccu-mcp",
        "--stdio"
      ],
      "env": {
        "CCU_HOST": "<ccu-host>",
        "CCU_PASSWORD": "<ccu-password>"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace.

{
  "mcpServers": {
    "ccu": {
      "command": "npx",
      "args": [
        "-y",
        "ccu-mcp",
        "--stdio"
      ],
      "env": {
        "CCU_HOST": "<ccu-host>",
        "CCU_PASSWORD": "<ccu-password>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json.

Configuration

Variable	Required	Secret	Description
CCU_HOST	yes	—	Hostname or IP of your HomeMatic CCU (debmatic, CCU3, or OpenCCU/RaspberryMatic)
CCU_PASSWORD	yes	yes	CCU admin password (same as the WebUI login). Must be set; the value may be empty for a CCU with no password
CCU_USER	—	—	CCU username
CCU_HTTPS	—	—	Connect to the CCU via HTTPS (self-signed certificates supported)
CCU_PORT	—	—	CCU API port (80 for HTTP, 443 for HTTPS)
CACHE_DIR	—	—	Directory for the device type cache and session persistence
MCP_ALLOWED_ORIGINS	—	—	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	—	—	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	—	—	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	—	—	Which profile from CCU_PROFILES is active at startup (default: the first listed)
CCU_TLS_VERIFY	—	—	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	—	—	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	—	—	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	—	—	Timeout for a CCU JSON-RPC call, in MILLISECONDS
CCU_SCRIPT_TIMEOUT	—	—	Timeout for HomeMatic Script execution (ReGa), in MILLISECONDS — scripts are slower than plain API calls
CACHE_TTL	—	—	Lifetime of the on-disk device-type schema cache, in SECONDS
CCU_RATE_LIMIT_BURST	—	—	Token-bucket burst size for CCU requests — how many may be issued back to back
CCU_RATE_LIMIT_RATE	—	—	Sustained CCU request rate, in requests per second
RESOURCE_POLL_INTERVAL	—	—	How often MCP resources are polled for change notifications, in SECONDS
LOG_LEVEL	—	—	error \| warn \| info \| debug. Logs are structured JSON on stderr

Freshness

Active — last maintenance signal 3d ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-10-07 · 3d ago · GitHub
Latest release
2026-10-07 · 3d ago · GitHub · v1.11.4
Package published
no data · npm/PyPI
Registry entry updated
2026-10-07 · 3d ago · official registry · v1.11.4

FAQ

›How do I install the Ccu MCP server in Claude Code?

Run: claude mcp add ccu -e CCU_HOST='<ccu-host>' -e CCU_PASSWORD='<ccu-password>' -- npx -y ccu-mcp --stdio. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does Ccu require an API key?

Yes. It expects CCU_HOST, CCU_PASSWORD, of which 1 is a secret.

›Can I use Ccu as a remote (hosted) MCP server?

No hosted endpoint is published; it runs locally over stdio.

›Is Ccu in the official MCP registry?

Yes, as io.github.claymore666/ccu-mcp.