# ccu-mcp

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 9 repo stars
- Author: claymore666
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/claymore666/ccu-mcp
- Updated: 2026-10-21
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/ccu-mcp

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- 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` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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

### Codex

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values. 15 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values. 15 more environment variables are in the server README

## When to use it
- 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
- What's the temperature in the bathroom?
- Set the living room heating to 21 degrees.
- Find all devices with low battery.

## Similar
- [mcp-hass](https://affpapa.org/en/nevibecode/skills/mcp-hass.md) — skill · 3200 installs
- [homeassistant-mcp-server](https://affpapa.org/en/nevibecode/skills/homeassistant-mcp-server.md) — skill · 207 installs
- [Tapo MCP](https://affpapa.org/en/nevibecode/mcp/tapo-mcp.md) — MCP server · ★ 877 repo stars
- [wemo](https://affpapa.org/en/nevibecode/mcp/wemo.md) — MCP server · ★ 56 repo stars
- [Homebridge](https://affpapa.org/en/nevibecode/mcp/homebridge.md) — MCP server · ★ 12 repo stars
- [Yeelight IoT MCP Server](https://affpapa.org/en/nevibecode/mcp/yeelight-iot-mcp-server.md) — MCP server · ★ 10 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
