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 Anlagenwerte abfragen, verständlich anzeigen und – nur nach ausdrücklicher Freigabe – ausgewählte Sollwerte schreiben.

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
          │ idm-heatpump-api (Modbus TCP im lokalen Netz)
          ▼
        IDM-Wärmepumpe

Der Server übersetzt sprechende Namen wie outdoor_temp oder hc_a_flow_temp in Modbus-Zugriffe, dekodiert Werte inklusive Einheit, Enumeration und Skalierung und stellt sie als MCP-Tools und MCP-Resources bereit. Die komplette Registerkarte (je nach Anlage 100–600 Datenpunkte) und die automatische Modell-Erkennung stammen aus der Bibliothek idm-heatpump-api, die auch die Home-Assistant- Integration idm-heatpump-hass verwendet – beide pflegen damit dieselbe, an realen Anlagen verifizierte Registerdatenbasis.

Typische Anwendungsfälle sind:

• aktuelle Betriebswerte in natürlicher Sprache abfragen („Wie warm ist der Puffer?“),

• einen vollständigen Anlagen-Snapshot mit einem Aufruf lesen (read_all_datapoints),

• einem KI-Assistenten die verfügbaren Werte samt Einheit, Grenzen und Write-Klasse zeigen,

• Diagnosegespräche mit aktuellen Anlagendaten und Fehlercode-Erklärungen unterstützen und

• nach bewusster, mehrstufiger Freigabe einzelne Sollwerte ändern – mit trockener Vorprüfung.

Der Server ist kein dauerhaftes Monitoring-System: Er speichert keine Messhistorie, erstellt keine Diagramme und ersetzt weder Home Assistant noch idm-heatpump-api selbst.

Related MCP server: WinCC OA MCP Server

Was kann der Server?

• Modell erkennen: Controller-Familie (Navigator 1.7 / 2.0 / 10 / Pro), aktive Heizkreise, Zonenmodule, Solar, ISC, PV und Kaskade automatisch ermitteln.

• Datenpunkte auflisten: Schlüssel, Adresse, Datentyp, Einheit, Skalierung, Wertebereich, Enum-Optionen und Write-Klasse anzeigen.

• Live-Werte lesen: Einzelwerte oder alle lesbaren Datenpunkte in einem Batch (mit kurzem Snapshot-Cache) lesen.

• Werte verstehen: Enumerationen (z. B. Betriebsmodi) werden mit Label übersetzt, „nicht konfiguriert“-Sentinelwerte als unused markiert.

• Fehlercodes erklären: die 2005 Meldungsnummern der Controller-Datenbank mit Benutzer- und Servicetext auflösen.

• Kontrolliert schreiben: Schreibpläne ohne Gerätekontakt validieren (validate_write) und freigegebene Register mit voller Bereichs-, Enum- und Modellprüfung schreiben.

• Diagnose: Verbindungsstatus, dauerhaft fehlgeschlagene und nicht unterstützte Register sowie zyklische Schreibanforderungen einsehen.

• Web-Supplement (optional): über die im Controller gesetzte Web-PIN (IDM_WEB_PIN) stehen das Navigator-10-WebSocket- bzw. Navigator-2.0-HTTP-Interface bereit: aktive Störungen im Klartext, Softwarestand und Gerätebezeichnung lesen sowie Betriebsmodus, Warmwasser-Sollwert, Uhrzeit setzen und Meldungen quittieren. Web-Schreibaktionen laufen durch dieselbe Write-Klassen-Freigabe wie die äquivalenten Modbus-Register.

• Hintergrund-Polling (optional): mit IDM_POLL_INTERVAL aktualisiert ein Hintergrundtask den Snapshot, überwacht die Verbindung (Exponential-Backoff bei Störungen) und hält zyklische GLT-Anforderungen (cyclic-Register) vor Ablauf ihrer TTL am Leben.

• Zwei Transporte: lokales stdio (Standard) oder Streamable-HTTP (IDM_TRANSPORT=http, bindet standardmäßig an 127.0.0.1) – etwa für Container- oder LAN-Betrieb hinter einem abgesicherten Reverse-Proxy. Ein optionaler statischer Bearer-Token (IDM_HTTP_TOKEN) schützt den HTTP-Endpunkt zusätzlich ab.

• An realer Anlage verifiziert: Modellerkennung (Navigator 10 mit Solar/ISC/PV und nicht zusammenhängenden Heizkreisen), Voll-Snapshot und Diagnose sind gegen eine echte Anlage getestet.

• Lokal bleiben: Die Verbindung zur Wärmepumpe erfolgt aus dem eigenen Netzwerk; der Server benötigt keinen Cloud-Zugang.

Verfügbare MCP-Tools

Verfügbare MCP-Resources

Welche konkreten Datenpunkte existieren, entscheidet die erkannte Anlage bzw. die Registerkarte der idm-heatpump-api.

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. die Write-Klasse des Registers (volatile, cyclic, eeprom oder write_only) steht in IDM_WRITE_CLASSES, und

3. ist IDM_WRITABLE_KEYS gesetzt, enthält diese Allowlist den Registernamen.

Darüber hinaus validiert idm-heatpump-api jeden Schreibzugriff gegen Wertebereich, Enumerationen und Modellverfügbarkeit und drosselt wiederholte EEPROM-Schreibzugriffe (max. einer pro Register und 60 s) zum Schutz des begrenzt beschreibbaren Controllerspeichers. Mit validate_write oder dry_run=true lässt sich jeder Schreibplan vorab prüfen, ohne das Gerät zu berühren. Weitere Hinweise stehen unter Sicherer Betrieb.

Web-Schreibaktionen werden über die Write-Klasse ihres jeweiligen Modbus-Äquivalents kontrolliert: web_set_system_mode und web_save_dhw_setpoint benötigen eeprom (wie system_mode bzw. dhw_setpoint), web_acknowledge_notifications benötigt write_only (wie error_acknowledge), web_set_datetime benötigt volatile. Eine gesetzte IDM_WRITABLE_KEYS-Allowlist greift auch hier.

Voraussetzungen

• IDM-Wärmepumpe mit aktiviertem und im LAN erreichbarem Modbus TCP

• Python 3.12 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
# .env an die eigene Anlage anpassen (mindestens IDM_HOST)
idm-mcp

Modell und Registerkarten werden beim ersten Aufruf von detect_model automatisch ermittelt; eine eigene Registerdatei ist nicht erforderlich. Wer die Erkennung überspringen möchte, setzt IDM_MODEL (z. B. navigator10).

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

Erkenne meine Wärmepumpe und zeige mir danach alle verfügbaren Datenpunkte. Schreibe keine Werte.

Anschließend kann ein konkreter Messwert gelesen werden:

Lies outdoor_temp und storage_temp 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

• Lesen und Schreiben einzelner 16-/32-Bit-Register gemäß Registerkarte der idm-heatpump-api; keine freien Rohadressen ohne Kartenbezug,

• Web-Supplement nur gegen lokal erreichbares Web-Interface mit gesetzter PIN; Navigator 1.x hat kein lokales Web-Interface,

• keine mitgelieferte Zeitreihen, Statistiken, Diagramme oder lokale Datenbank (das Hintergrund-Polling hält nur den letzten Snapshot vor),

• HTTP-Transport ohne eigene Authentifizierung – nur an 127.0.0.1 binden oder vor einen Reverse-Proxy mit TLS und Zugangsbeschränkung setzen,

• 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.