IDM Heat Pump MCP Server

Ein unabhängiger Model Context Protocol (MCP)-Server, der KI-Assistenten kontrollierten Zugriff auf eine IDM-Wärmepumpe über Modbus TCP ermöglicht. Damit können kompatible MCP-Clients konfigurierte Anlagenwerte abfragen, verständlich anzeigen und – nur nach ausdrücklicher Freigabe – ausgewählte Sollwerte schreiben.

[!IMPORTANT] Dieses Community-Projekt steht in keiner Verbindung, Partnerschaft oder Beauftragung mit der iDM Energiesysteme GmbH und wird von ihr nicht unterstützt oder zertifiziert. „IDM“/„iDM“ und Produktnamen sind Kennzeichen ihrer jeweiligen Inhaber. Dieses Projekt ist keine offizielle Bedienoberfläche und ersetzt weder Herstellerdokumentation noch Fachbetrieb. Siehe DISCLAIMER.md.

Wofür ist das Projekt gedacht?

Eine Wärmepumpe spricht normalerweise kein MCP. KI-Clients wie Claude Desktop, Claude Code, Codex oder unterstützte IDEs können deshalb nicht direkt mit ihr kommunizieren. Dieser Server bildet die Brücke zwischen beiden Welten:

MCP-Client / KI-Assistent
          │ lokales MCP über stdio
          ▼
   IDM Heat Pump MCP Server
          │ Modbus TCP im lokalen Netz
          ▼
       IDM-Wärmepumpe

Der Server übersetzt sprechende Namen wie heating.outside_temperature in die für das jeweilige Gerät konfigurierte Modbus-Adresse, liest den Rohwert und rechnet ihn mit Datentyp, Skalierung, Offset und Einheit in einen verständlichen Wert um. Dadurch muss der KI-Assistent weder Registeradressen kennen noch selbst Binärwerte interpretieren.

Typische Anwendungsfälle sind:

• aktuelle, konfigurierte Betriebswerte in natürlicher Sprache abfragen,
• Temperaturen oder andere einzelne Messwerte auslesen,
• einem KI-Assistenten die verfügbaren Werte samt Einheit und Beschreibung zeigen,
• Diagnosegespräche mit aktuellen Anlagendaten unterstützen und
• nach bewusster Freigabe einzelne, geprüfte Sollwerte innerhalb definierter Grenzen ändern.

Der Server ist kein dauerhaftes Monitoring-System: Er speichert keine Messhistorie, erstellt keine Diagramme und ersetzt weder Home Assistant noch idm-heatpump-api. Er stellt ausschließlich die in der lokalen Registerdatei definierten Werte als MCP-Tools und MCP-Resources bereit.

Was kann der Server?

• Entities auflisten: Namen, Adressen, Einheiten, Beschreibungen und Schreibregeln anzeigen.
• Live-Werte lesen: Ein konfiguriertes Holding- oder Input-Register direkt von der Wärmepumpe lesen.
• Werte dekodieren: Vorzeichenbehaftete int16- und vorzeichenlose uint16-Register inklusive Skalierung und Offset in verständliche Werte umrechnen.
• Kontrolliert schreiben: Ein freigegebenes Holding-Register skalieren, auf Minimal- und Maximalwert prüfen und schreiben.
• Gerätespezifisch arbeiten: Die Register werden als JSON konfiguriert und können damit an Modell, Firmware und Anlagenkonfiguration angepasst werden.
• Mehrere MCP-Oberflächen bedienen: Funktionen werden sowohl als MCP-Tools als auch als MCP-Resources angeboten.
• Lokal bleiben: Die Verbindung zur Wärmepumpe erfolgt aus dem eigenen Netzwerk; der Server benötigt keinen Cloud-Zugang.

Verfügbare MCP-Tools

Tool	Zweck	Beispiel
list_entities	Alle konfigurierten Entities und Metadaten anzeigen	„Welche Wärmepumpenwerte kannst du lesen?“
read_entity	Aktuellen Wert eines Entity lesen	„Lies heating.outside_temperature aus.“
write_entity	Einen ausdrücklich erlaubten Wert setzen	„Setze den freigegebenen Sollwert auf 21 °C.“

Verfügbare MCP-Resources

Resource	Inhalt
idm://entities	Liste aller konfigurierten Entities
idm://entities/{name}	Aktueller Wert eines bestimmten Entity

Welche konkreten Temperaturen, Betriebszustände oder Sollwerte verfügbar sind, entscheidet allein die lokale registers.json. Ohne konfigurierte Entities liefert list_entities eine leere Liste.

Sicherheitskonzept

Der Server startet grundsätzlich read-only. Ein Schreibzugriff wird nur ausgeführt, wenn alle drei Bedingungen gleichzeitig erfüllt sind:

1. IDM_ALLOW_WRITES=true aktiviert Schreiben global,
2. das betreffende Entity besitzt "writable": true, und
3. seine Adresse steht zusätzlich in IDM_WRITABLE_ADDRESSES.

Optionale minimum- und maximum-Werte begrenzen den erlaubten Sollwert zusätzlich. So führt weder eine ungenaue Formulierung noch ein einzelner fehlerhafter Konfigurationseintrag automatisch zu einem Schreibzugriff. Trotzdem müssen alle Adressen und Grenzen fachlich geprüft werden. Weitere Hinweise stehen unter Sicherer Betrieb.

Voraussetzungen

• IDM-Wärmepumpe mit aktiviertem und im LAN erreichbarem Modbus TCP
• für das konkrete Gerät und die Firmware verifizierte Registeradressen
• Python 3.11 oder neuer oder alternativ Docker
• ein lokaler MCP-Client mit stdio-Unterstützung

Schnellstart

python -m venv .venv
source .venv/bin/activate
pip install .
cp .env.example .env
cp config/registers.example.json config/registers.json
# .env und registers.json an das eigene Gerät anpassen
idm-mcp

Die Beispieladressen sind keine echten bzw. universellen IDM-Adressen. Register können je nach Modell, Firmware und Anlagenkonfiguration abweichen. Nur verifizierte Adressen verwenden.

Danach wird die gewünschte KI-Anwendung gemäß der clientbezogenen Anleitung eingerichtet. Ein sinnvoller erster Test im Client ist:

Liste alle konfigurierten IDM-Entities auf. Schreibe keine Werte.

Anschließend kann ein tatsächlich konfiguriertes Entity gelesen werden:

Lies heating.outside_temperature und erkläre Wert und Einheit. Verändere nichts.

MCP-Client

Eine ausführliche, clientbezogene Anleitung ist unter Claude, ChatGPT, GitHub Copilot, Codex und Z.ai einrichten verfügbar.

Wichtig: Dieser Server verwendet aktuell den lokalen MCP-Transport stdio. Claude Desktop, Claude Code, Codex CLI und unterstützte IDEs können ihn direkt als lokalen Prozess starten. Webdienste wie ChatGPT im Browser oder GitHub.com können dagegen keinen Prozess auf dem eigenen Rechner starten. Dafür wäre ein separat abgesicherter HTTPS-MCP-Gateway erforderlich; der Modbus-Port der Wärmepumpe darf dafür keinesfalls ins Internet gestellt werden.

Dokumentation / Wiki-Vorlage

• Installation
• Konfiguration
• Claude, ChatGPT, GitHub Copilot, Codex und Z.ai
• Sicherer Betrieb
• Haftungs- und Markenhinweis

Die Seiten unter docs/ können in ein GitHub-Wiki übernommen werden. GitHub-Wikis liegen technisch in einem separaten Repository und werden nicht automatisch mit diesem Repository veröffentlicht.

Aktuelle Grenzen

• nur einzelne 16-Bit-Register (uint16 und int16), noch keine 32-Bit-, Float-, String- oder Bitfeld-Entities,
• keine automatische Erkennung von Modell, Firmware oder Registertabelle,
• keine mitgelieferte universelle IDM-Registerliste,
• keine Zeitreihen, Statistiken, Diagramme oder lokale Datenbank,
• aktuell nur lokaler MCP-Transport über stdio, kein öffentlicher HTTPS-Endpunkt,
• keine Authentifizierung innerhalb von Modbus TCP.

Diese Einschränkungen sind bewusst sichtbar dokumentiert, damit der Server nicht mit Fähigkeiten eingesetzt wird, die er derzeit nicht besitzt.

Lizenz

Der Quellcode steht unter der MIT-Lizenz. Sie erlaubt Nutzung, Änderung und Weitergabe unter Beibehaltung des Lizenz- und Copyright-Hinweises und enthält einen Gewährleistungs- und Haftungsausschluss. Der ergänzende Disclaimer erklärt Projektstatus und Betriebsrisiken in verständlicher Form; er ersetzt keine Rechtsberatung.