ccu-mcp — HomeMatic CCU MCP server: control smart home from Claude Code
Exposes HomeMatic CCU devices, rooms and programs as MCP tools through the built-in JSON-RPC API. Lets an AI assistant read sensors and change heating values without cloud or addons.
MIT ★ 9 updated 2026-10-21
claude mcp add --env CCU_HOST=<CCU_HOST> --env CCU_PASSWORD=<CCU_PASSWORD> --env CCU_USER=<CCU_USER> --env CCU_HTTPS=<CCU_HTTPS> --env CCU_PORT=<CCU_PORT> --transport stdio ccu-mcp -- npx -y ccu-mcpWhat ccu-mcp does
The server talks to the CCU's standard /api/homematic.cgi endpoint and turns your smart home into a set of MCP tools. It works with CCU3, debmatic and OpenCCU. Device discovery, type resolution, session handling and value conversion all happen inside the server.
You need Node.js 24+ or Docker, plus the CCU admin credentials. Once connected, the assistant can answer questions about room temperatures, open windows, low batteries or gas meter readings. It can also rename devices following a floor-based naming scheme like UG/OG/EG.
In stdio mode the cache defaults to /data, so outside Docker nothing persists between runs. Point CACHE_DIR to a writable location such as $HOME/.cache/ccu-mcp, otherwise the device-type cache and CCU session get rebuilt on every start.
What it helps with
- ask the assistant which windows are open
- set living room heating to 21 degrees
- list devices with low battery
- rename channels to match a floor-label convention
- check the gas meter reading
Example prompts for the agent
- What's the temperature in the bathroom?
- Set the living room heating to 21 degrees.
- Find all devices with low battery.
How to install ccu-mcp
Platform CLI
claude mcp add --env CCU_HOST=<CCU_HOST> --env CCU_PASSWORD=<CCU_PASSWORD> --env CCU_USER=<CCU_USER> --env CCU_HTTPS=<CCU_HTTPS> --env CCU_PORT=<CCU_PORT> --transport stdio ccu-mcp -- npx -y ccu-mcpReplace <…> with your own values. 15 more environment variables are in the server README
Platform CLI
codex mcp add ccu-mcp --env CCU_HOST=<CCU_HOST> --env CCU_PASSWORD=<CCU_PASSWORD> --env CCU_USER=<CCU_USER> --env CCU_HTTPS=<CCU_HTTPS> --env CCU_PORT=<CCU_PORT> -- npx -y ccu-mcpReplace <…> with your own values. 15 more environment variables are in the server README
Config file
{
"mcpServers": {
"ccu-mcp": {
"command": "npx",
"args": [
"-y",
"ccu-mcp"
],
"env": {
"CCU_HOST": "<CCU_HOST>",
"CCU_PASSWORD": "<CCU_PASSWORD>",
"CCU_USER": "<CCU_USER>",
"CCU_HTTPS": "<CCU_HTTPS>",
"CCU_PORT": "<CCU_PORT>"
}
}
}
}Replace <…> with your own values. 15 more environment variables are in the server README
Config file
{
"servers": {
"ccu-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"ccu-mcp"
],
"env": {
"CCU_HOST": "<CCU_HOST>",
"CCU_PASSWORD": "<CCU_PASSWORD>",
"CCU_USER": "<CCU_USER>",
"CCU_HTTPS": "<CCU_HTTPS>",
"CCU_PORT": "<CCU_PORT>"
}
}
}
}Replace <…> with your own values. 15 more environment variables are in the server README
Platform CLI
gemini mcp add -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> ccu-mcp npx -y ccu-mcpReplace <…> with your own values. 15 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ccu-mcp
How do I install ccu-mcp in Claude Code?
Run claude mcp add ccu-mcp -e CCU_HOST=<CCU_HOST> -e CCU_PASSWORD=<CCU_PASSWORD> -- npx -y ccu-mcp, replacing the placeholders with your CCU address and password. Restart Claude Code and check the connection with /mcp.
What does ccu-mcp do?
It connects an AI assistant to a HomeMatic CCU controller over the JSON-RPC API. The assistant gets tools for devices, rooms, programs and system variables, and can read state or change values.
What is the difference between stdio and Docker modes?
Stdio runs the server as a child process of your MCP client, with no network config or auth tokens. Docker runs it as a standalone HTTP server reachable by multiple clients, but you need the bearer token and a correct MCP_ALLOWED_HOSTS value.