Skip to main content
MCP server CX Codex

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

Install into Claude Code · Platform CLI All methods and platforms ↓
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-mcp
Open on GitHub

What 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-mcp

Replace <…> 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.

Similar MCP servers

All MCP servers for Automation and no-code: n8n, Zapier, Make →

Project sponsors

Companies that keep this analytics open