# claymore666/debmatic-mcp [Health: Active]

**Category:** 🏠 Home Automation  
**Repository:** https://github.com/claymore666/debmatic-mcp  
**GitHub Stars:** 9  
**npm Downloads (last month):** 277  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/claymore666-debmatic-mcp

## Description
Control a HomeMatic / debmatic CCU (eq-3 home automation) over its JSON-RPC and HM-Script APIs — switch and dim actuators, read sensors, system variables and service messages, run programs, and manage rooms, functions, channel links and device assignments. 25 tools over HTTP or stdio; runs locally against your own CCU.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## What claymore666/debmatic-mcp does

claymore666/debmatic-mcp gives an MCP-compatible AI client access to a HomeMatic central control unit. It works with debmatic on Debian, CCU3, and OpenCCU installations that expose the standard `/api/homematic.cgi` endpoint. Communication stays on the local network and uses the CCU's built-in JSON-RPC and HM-Script interfaces; no additional CCU addon or XML-API installation is needed.

The server covers both everyday device control and administrative organization. An assistant can inspect temperatures, window states, battery conditions, gas-meter readings, and other values; change heating targets; operate switches and dimmers; and read service messages and system variables. It can also run CCU programs and work with rooms, functions, channel links, and device assignments.

## How it works

The server handles CCU login sessions, device discovery, type resolution, and conversion of returned values before exposing operations as MCP tools. This lets the client work with named HomeMatic objects rather than implementing the CCU protocols itself. The package provides 25 tools in total.

Two transports are available. In stdio mode, an MCP client starts the process as a child and passes the CCU connection settings through its environment. In HTTP mode, the server runs independently, commonly in Docker, and clients connect to its MCP endpoint over the network. The HTTP deployment creates a bearer token at first startup and stores it in the data volume.

## Setup and configuration

A reachable CCU and its WebUI administrator credentials are required. Running from source or using stdio requires Node.js 24 or newer; Docker is also supported. The basic stdio setup supplies `CCU_HOST` and `CCU_PASSWORD`, then starts the package with `npx ccu-mcp --stdio`.

Docker images are published for Linux amd64 and arm64. An HTTP container typically maps port 3000, passes the CCU credentials, and mounts `/data` so the generated authentication token, CCU session, and device-type cache can persist. Remote HTTP clients require `MCP_ALLOWED_HOSTS` to include each hostname or IP and port used to reach the server. Requests use the generated bearer token. Browser-based clients additionally need trusted origins listed in `MCP_ALLOWED_ORIGINS`.

The default cache location is `/data`, which suits the container layout. For a non-container installation, set `CACHE_DIR` to a writable directory if session and device-type data should survive restarts. The `init` command can probe the CCU, pin its TLS certificate, test login credentials, create a `.env` file, and print a matching client configuration.

## Tools and capabilities

Available operations include:

- Discover HomeMatic devices, channels, rooms, and functions.
- Read sensor values, system variables, service messages, battery status, and meter readings.
- Switch and dim actuators and change heating setpoints.
- Run CCU programs.
- Manage rooms, functions, channel links, and device assignments.
- Inspect naming and assignment patterns, including channels whose names differ from their devices.

## Limitations and notes

The CCU must be reachable from the process or container, and the supplied credentials are the same ones used by the CCU WebUI. HTTP deployments should use TLS through a reverse proxy when accessed beyond loopback because the bearer token is sent with requests. DNS-rebinding protection is enabled for HTTP; unlisted hostnames receive a 403 response. Browser access is blocked unless its origin is explicitly allowed, and authentication remains required for every MCP request.

_Full upstream README: https://allmcps.com/mcp/claymore666-debmatic-mcp/readme_