Log inSubmit server
Ccu MCP logo

Ccu MCP

Control HomeMatic devices, rooms, programs, and variables through an MCP connection to a local CCU.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Ccu MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "ccu-mcp": {
      "command": "npx",
      "args": [
        "ccu-mcp"
      ],
      "env": {
        "CCU_HOST": "YOUR_VALUE_HERE",
        "CCU_PASSWORD": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

The ccu-mcp MCP server connects AI clients to a HomeMatic CCU through its built-in JSON-RPC API. It exposes devices, rooms, programs, and system variables as MCP tools, handling discovery, sessions, type resolution, and value conversion. Use it to inspect sensors, check device status, read meters, or change supported device values from an MCP client. It supports debmatic, CCU3, and OpenCCU installations that provide the standard API endpoint.

Use cases

  • Read temperatures and meter values from HomeMatic devices
  • Check rooms for open windows or low-battery devices
  • Adjust supported heating values through an MCP client
  • Review device, room, channel, and system-variable state
  • Run the server locally or expose it through Docker HTTP

Key features

  • Connects to the CCU JSON-RPC API
  • Exposes devices, rooms, programs, and system variables
  • Handles discovery, sessions, type resolution, and value conversion
  • Supports stdio and standalone Docker HTTP modes
  • Provides HTTP bearer authentication and host allowlisting

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

5/5 checks healthy over the last 42d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 15h ago via OSV.dev · ccu-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars9Stargazers on the source repository.
npm downloads1.1kPackage downloads in the last 30 days.
Last commit2d agoMost recent push to the default branch.
Directory activity2 viewsConfig copies, upvotes, and views on AllMCPs.

How Ccu MCP works

What ccu-mcp MCP server does

The ccu-mcp MCP server gives an MCP-compatible AI client access to a HomeMatic installation through the CCU's local JSON-RPC interface. It can expose devices, rooms, programs, and system variables for querying and control. The connection stays on the local network and does not require a HomeMatic addon, XML-API, or cloud service.

Typical requests include reading a bathroom temperature, finding open windows, checking devices with low batteries, reading a gas-meter value, or identifying a room associated with a window sensor.

The server is intended for the Home Automation category and works with HomeMatic systems based on debmatic, CCU3, or OpenCCU, including installations formerly known as RaspberryMatic. The CCU must expose /api/homematic.cgi and be reachable from the process running the server.

How it works

ccu-mcp MCP server connects directly to the CCU JSON-RPC API using the same administrator credentials used by the CCU WebUI. It manages CCU sessions, discovers available devices and related objects, resolves device types, and converts values for MCP tool calls. This lets the client work with the installation's structure rather than requiring each device to be configured manually.

Two transport arrangements are documented. In stdio mode, an MCP client starts the server as a child process. In HTTP mode, Docker runs the server independently on port 3000, allowing clients to connect over the network. HTTP access uses a generated bearer token, host allowlisting, and optional origin allowlisting for browser clients.

Setup and configuration

Running from source or in stdio mode requires Node.js 24 or newer; Docker is an alternative. Set CCU_HOST to the CCU hostname or IP address and CCU_PASSWORD to the CCU administrator password. The basic command is npx ccu-mcp --stdio.

The documented Claude Code configuration starts npx ccu-mcp --stdio and passes those variables in the server environment. The init command can probe the CCU, pin its TLS certificate, test login credentials, create a .env file, and print matching client configuration.

For Docker, publish the container's port 3000 and mount /data so the generated authentication token, CCU session, and device-type cache can persist. Set MCP_ALLOWED_HOSTS for every hostname or address remote clients use. Browser-based clients additionally require trusted origins in MCP_ALLOWED_ORIGINS. Outside Docker, set CACHE_DIR to a writable location instead of relying on the default /data path.

Tools and capabilities

The ccu-mcp MCP server exposes MCP tools for working with:

  • HomeMatic devices and their values
  • Rooms and device-to-room relationships
  • Programs
  • System variables
  • Device discovery and status inspection
  • Battery and stale-device checks
  • Channel and device naming reviews

Exact operations depend on the objects and values available from the connected CCU.

Limitations and notes

The CCU must be reachable on the network, and valid administrator credentials are required. HTTP deployments should use TLS beyond loopback because bearer tokens are sent with requests. Remote HTTP clients can receive 403 Invalid Host header unless their host is included in MCP_ALLOWED_HOSTS; browser clients also need an allowed origin. A cache write failure outside a container does not stop the server, but persistence will not work until CACHE_DIR points to a writable directory.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Ccu MCP

ccu-mcp is an MCP server that connects AI clients to a HomeMatic CCU through its built-in JSON-RPC API. Its main tools expose devices, rooms, programs, and system variables, with built-in discovery, session handling, type resolution, and value conversion for local smart-home queries and control.

Install it with Node.js 24+ and run `npx ccu-mcp --stdio`, or use the published Docker image for standalone HTTP mode. Set `CCU_HOST` and `CCU_PASSWORD`; Docker deployments also need host configuration and a client bearer token.

Yes, the README names Cursor as a supported MCP client. Configure Cursor to launch the stdio command with the CCU host and password, or connect it to the Docker HTTP endpoint with the generated bearer token.

It supports any HomeMatic CCU exposing the standard `/api/homematic.cgi` endpoint, including debmatic, CCU3, and OpenCCU. The CCU must be reachable from the machine or container running the server.

Run the Docker HTTP server, set `MCP_ALLOWED_HOSTS` to the names or addresses clients will use, and send the generated bearer token in the `Authorization` header. For browser-based clients, also add trusted origins to `MCP_ALLOWED_ORIGINS`.

Related MCP servers

All in Home Automation All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewCcu MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/ccu-mcp?style=directory)](https://allmcps.com/mcp/ccu-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/ccu-mcp"><img src="https://allmcps.com/api/badge/ccu-mcp?style=directory" alt="Ccu MCP on AllMCPs" /></a>