Debmatic Mcp

@claymore666

About Debmatic Mcp

# debmatic-mcp

#mcp #homematic #debmatic #ccu #smart-home #home-automation #iot #raspberrymatic #homematic-ip #eq3

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "debmatic": {
      "command": "npx",
      "args": [
        "debmatic-mcp",
        "--stdio"
      ],
      "env": {
        "CCU_HOST": "your-ccu-hostname-or-ip",
        "CCU_PASSWORD": "your-ccu-admin-password"
      }
    }
  }
}

Tools

List all devices with their channels, types, and addresses. Optional filters: room, function, type, name. Use this first to discover device addresses for get_value/set_value.

List available communication interfaces (BidCos-RF, HmIP-RF, VirtualDevices, etc.).

List all rooms with their assigned channel IDs. Use with list_devices to find devices by room.

List all function groups (Heating, Lighting, etc.) with their assigned channel IDs.

List all automation programs. Use execute_program to trigger them.

List all system variables with current values and metadata. Use set_system_variable to modify them.

Get the full channel/datapoint schema for a device type (e.g. 'HmIP-eTRV-2'). Shows all channels, paramsets, datapoint names, types, ranges, and operations. Served from cache (instant). Use list_devices first to find device types.

Read a single datapoint value from a device channel. Only address and valueKey are required — interface is auto-resolved. Use list_devices to find addresses, describe_device_type to find valid valueKeys.

Read datapoint values for multiple channels at once via HM Script. Provide either a list of channel addresses, or filter by room or function name.

Read all parameters for a channel (VALUES, MASTER, or LINK). Interface is auto-resolved from the address.

Set a single datapoint value on a device channel. Only address, valueKey, and value are required — interface and type are auto-resolved. Returns the previous value for undo. Use describe_device_type to find valid valueKeys and ranges.

Write multiple parameters at once (e.g. thermostat weekly profile). Interface is auto-resolved from address.

Set a system variable value. Type is auto-detected — use list_system_variables to see available variables.

Trigger an automation program on the CCU. NOT idempotent — will not be auto-retried. Use list_programs to find program IDs.

Get all active service messages (low battery, unreachable, etc.) with device details and timestamps.

Get CCU system information: firmware version, serial number, addresses.

Context-aware help. No args: conceptual guide. Tool name (e.g. 'set_value'): tool usage. Device type (e.g. 'HmIP-eTRV-2'): capabilities from cache.

Execute arbitrary HomeMatic Script on the CCU. NOT idempotent — will not be auto-retried. Use for anything the other tools don't cover.

Overview

What is Debmatic Mcp?

Debmatic Mcp connects to any HomeMatic CCU (debmatic, CCU3, or OpenCCU) via its built-in JSON-RPC API and exposes devices, rooms, programs, and system variables as MCP tools. It works directly on your local network — no addons, no XML-API, no cloud required.

How to use Debmatic Mcp?

Install via npx ccu-mcp --stdio or run a Docker container with environment variables CCU_HOST and CCU_PASSWORD. Configure your MCP client (e.g., Claude Code) by adding a debmatic server entry in .mcp.json — either as a stdio subprocess or an HTTP server. The HTTP mode uses a bearer token generated on first startup.

Key features of Debmatic Mcp

Connects directly to any HomeMatic CCU via its JSON-RPC API
Exposes devices, rooms, programs, and system variables as MCP tools
Supports stdio (subprocess) and HTTP (standalone) transports
Bearer token authentication with rotation, TTL, and grace period
TLS support with cert pinning, CA trust, or system verification
CORS and DNS-rebinding protection for secure HTTP access

Use cases of Debmatic Mcp

Ask an AI assistant for room temperatures, open windows, or low‑battery devices
Set heating to a specific temperature or rename devices with consistent naming
Find which room a window sensor belongs to or list devices with stale data
Read gas meter readings or detect naming inconsistencies across channels

FAQ from Debmatic Mcp

What are the prerequisites?

A running HomeMatic CCU (debmatic, CCU3, or OpenCCU) reachable on your network, the CCU’s admin username and password, and Node.js 22+ (for stdio mode) or Docker.

How do I get the auth token for HTTP mode?

Run docker exec ccu-mcp grep MCP_AUTH_TOKEN /data/.env — the token is the part after =. The server generates it on first startup and saves it to the container’s data volume.

Does it work with HTTPS? How do I handle self‑signed certificates?

Yes. Set CCU_HTTPS=true and optionally CCU_PORT=443. The server accepts self‑signed certificates by default — you can pin the certificate fingerprint via CCU_TLS_FINGERPRINT, trust a CA file via CCU_CA_CERT, or enable system trust with CCU_TLS_VERIFY=true.

How can I protect against brute‑force attacks?

Use fail2ban. The server logs every rejected request as a structured JSON line to stderr, making it easy to parse. Ready‑to‑use fail2ban filter and jail configuration are provided in the fail2ban/ directory.

What transport options are available?

Stdio (the server runs as a subprocess of the MCP client) and HTTP (a standalone Docker container that clients connect to over the network). Both are fully supported.

Frequently asked questions

What are the prerequisites?

A running HomeMatic CCU (debmatic, CCU3, or OpenCCU) reachable on your network, the CCU’s admin username and password, and Node.js 22+ (for stdio mode) or Docker.

How do I get the auth token for HTTP mode?

Run `docker exec ccu-mcp grep MCP_AUTH_TOKEN /data/.env` — the token is the part after `=`. The server generates it on first startup and saves it to the container’s data volume.

Does it work with HTTPS? How do I handle self‑signed certificates?

Yes. Set `CCU_HTTPS=true` and optionally `CCU_PORT=443`. The server accepts self‑signed certificates by default — you can pin the certificate fingerprint via `CCU_TLS_FINGERPRINT`, trust a CA file via `CCU_CA_CERT`, or enable system trust with `CCU_TLS_VERIFY=true`.

How can I protect against brute‑force attacks?

What transport options are available?

Stdio (the server runs as a subprocess of the MCP client) and HTTP (a standalone Docker container that clients connect to over the network). Both are fully supported.

Comments

Basic information

More Other MCP servers

ICSS

chokcoco

不止于 CSS

20.7K

Reactive Resume

amruthpillai

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

39.5K

IDA Pro MCP

mrexodia

AI-powered reverse engineering assistant that bridges IDA Pro with language models through MCP.

9.9K

MCP Toolbox for Databases

googleapis

MCP Toolbox for Databases is an open source MCP server for databases.

15.9K

Nginx UI

0xJacky

Yet another WebUI for Nginx

11.3K

About Debmatic Mcp

Config

Tools

list_devices

list_interfaces

list_rooms

list_functions

list_programs

list_system_variables

describe_device_type

get_value

get_values

get_paramset

set_value

put_paramset

set_system_variable

execute_program

get_service_messages

get_system_info

help

run_script

Overview

What is Debmatic Mcp?

How to use Debmatic Mcp?

Key features of Debmatic Mcp

Use cases of Debmatic Mcp

FAQ from Debmatic Mcp

What are the prerequisites?

How do I get the auth token for HTTP mode?

Does it work with HTTPS? How do I handle self‑signed certificates?

How can I protect against brute‑force attacks?

What transport options are available?

Frequently asked questions

What are the prerequisites?

How do I get the auth token for HTTP mode?

Does it work with HTTPS? How do I handle self‑signed certificates?

How can I protect against brute‑force attacks?

What transport options are available?

Comments

More Other MCP servers

ICSS

Reactive Resume

IDA Pro MCP

MCP Toolbox for Databases

Nginx UI