Debmatic MCP

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.