IDM Wärmepumpe MCP Server

MCP-Server für IDM Navigator 2.0 Wärmepumpen (z. B. TERRA SWM) über Modbus TCP.
Ermöglicht Claude die vollständige Überwachung und Steuerung der Wärmepumpe als Teil des integrierten Smart-Home-Energiemanagementsystems.

---

Voraussetzungen

• Python ≥ 3.11
• uv installiert
• IDM Wärmepumpe im selben LAN, Modbus TCP aktiviert (Menü „Gebäudeleittechnik")
• IP-Adresse der Wärmepumpe manuell gesetzt (kein DHCP — sonst nach Stromausfall ggf. geändert)

Installation

cd /Users/chris/Entwicklung_local/idm-mcp
uv sync

Umgebungsvariablen

Variable	Standardwert	Beschreibung
IDM_HOST	10.10.10.188	IP-Adresse der IDM Wärmepumpe
IDM_PORT	502	Modbus-TCP-Port
IDM_UNIT	1	Modbus Unit-ID

Claude Desktop Konfiguration

Ergänze ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "idm-mcp": {
      "command": "/Users/chris/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/chris/Entwicklung_local/idm-mcp",
        "run",
        "python",
        "-m",
        "idm_mcp.server"
      ],
      "env": {
        "IDM_HOST": "10.10.10.188",
        "IDM_PORT": "502",
        "IDM_UNIT": "1"
      }
    }
  }
}

---

Verfügbare Tools (13)

Read-only (8)

Tool	Beschreibung
idm_health_check	Verbindungstest: Außentemp., Betriebsart, Störungsstatus
idm_get_system_status	Betriebsart System + WP, Außentemp., Störung, Smart Grid, PV-Überschuss, Leistungsaufnahme
idm_get_temperatures	Alle Sensoren: WP-Vorlauf B33, Rücklauf B34, HGL B35, Wärmequelle B43/B36, Luft B37/B46/B72, Speicher B38/B40
idm_get_hot_water_status	Trinkwasser oben/unten B48/B41, Zapftemperatur B42, Soll/Ein/Aus-Temperaturen, Ladepumpe M73
idm_get_heat_circuits	Heizkreise A–G: Vorlauf ist/soll, Raumtemperatur, Betriebsart je Kreis
idm_get_compressor_status	Verdichter 1–4, Stufen Heizen/Kühlen/WW, Pumpen M15/M16/M73/M84/M17, alle Umschaltventile M61–M99
idm_get_energy_data	Momentanleistung, WP-Aufnahme, kumulierte Wärmemengen (Heizen/Kühlen/WW/Abtauung/Solar/E-Heiz)
idm_get_solar_status	Kollektor B73/B75, Ladetemperatur B74, Pool B76, Betriebsart Solar

Schreibend (5)

Tool	Register	Besonderheit
idm_set_system_mode	1005	⚠ EEPROM — nicht zyklisch schreiben!
idm_set_smart_grid	1006	Kernsteuerung für PV & Strommarkt (0/1/2/4)
idm_set_pv_surplus	74	⚠ E3DC schreibt diesen Wert normalerweise selbst!
idm_set_hot_water_setpoints	1032/1033/1034	⚠ EEPROM — nur bei Bedarf ändern
idm_set_demand	1710/1711/1712	⚠ Zyklisch schreiben (alle 30 s), sonst nach Neustart inaktiv

---

Systemarchitektur & Zusammenhänge

E3DC ↔ IDM Kommunikation

Das E3DC S10E Pro Hauskraftwerk (10.10.10.166) verfügt über ein integriertes Modbus-Modul speziell für IDM Wärmepumpen. Bei vorhandenem PV-Überschuss schreibt das E3DC automatisch und zyklisch den Überschusswert in Register 74 der IDM.

Die Wärmepumpe reagiert darauf und produziert mehr Wärme als für die aktuelle Raumtemperatur nötig wäre — sie „überlädt" gezielt:

• Fußbodenheizung wird höher als Normalniveau temperiert
• Pufferspeicher werden auf erhöhtes Temperaturniveau gebracht

Damit wird thermische Masse als kostenloser Energiespeicher genutzt, um z. B. über die Nacht zu kommen, ohne abends auf teuren Netzstrom angewiesen zu sein.

⚠ Das direkte Schreiben von Register 74 via idm_set_pv_surplus überschreibt die E3DC-Vorgabe temporär bis zum nächsten E3DC-Kommunikationszyklus.

Smart Grid Status (Register 1006)

Das zentrale Steuerregister für alle externen Eingriffe:

Wert	Bezeichnung	Verwendung
0	EVU-Sperre & kein PV-Ertrag	WP komplett sperren (Hochpreisstunden)
1	EVU-Bezug & kein PV-Ertrag	Normalbetrieb
2	Kein EVU-Bezug & PV-Ertrag	PV-Überschuss aktiv → WP auf Hochtouren
4	EVU-Sperre & PV-Ertrag	WP läuft trotz Netzsperrung weiter (PV-only)

Betriebsart System (Register 1005)

Wert	Bezeichnung
0	Standby
1	Automatik (Normalbetrieb)
2	Abwesend
4	Nur Warmwasser
5	Nur Heizung/Kühlung

Betriebseinschränkung Spitzenlastzeiten

Die IDM ist eine dreiphasige Erdwärme-Wärmepumpe mit 7,5 kW. Im aktuellen Tarifsystem (Kaskadenzähler ohne Smart Meter Gateway) wird der WP-Betrieb in den Hochpreisstunden 17:00–22:00 Uhr eingeschränkt, um teuren Netzstrombezug zu vermeiden.

---

Vorbereitung: Zukünftige Strommarktsteuerung

Der Server ist bereits auf eine spätere viertelstündliche Direktvermarktung am Strommarkt vorbereitet — sobald ein Smart Meter Gateway und eine direkte Marktteilnahme möglich sind.

Strategie:

Zeitfenster	Strompreis	Aktion
Nachts (günstig)	niedrig	idm_set_smart_grid(2) + Puffer & WW hochladen + E-Auto laden + Batterien füllen
06–08 Uhr	hoch	idm_set_smart_grid(0) → WP sperren, Batterie entladen
17–20 Uhr	hoch	idm_set_smart_grid(0) → WP sperren, aus Wärmespeicher leben
PV-Überschuss	—	idm_set_smart_grid(2) → maximale thermische Einlagerung

Diese Steuerung würde in Verbindung mit E3DC, Victron/Felicity und dem 22-kW-Wallbox- Lader über Node-RED oder einen dedizierten Automations-Flow koordiniert.

---

Wichtige Hinweise

• EEPROM-Register (mit * in IDM-Doku): Begrenzte Schreibzyklen → nicht permanent/zyklisch schreiben!
• Zyklische Register 1710/1711/1712 und 74: Müssen alle ~30 s geschrieben werden, damit die Anforderung nach einem WP-Neustart wieder anliegt.
• PV-Überschuss Register 74: Im laufenden Betrieb vom E3DC Hauskraftwerk beschrieben — direktes MCP-Schreiben nur für manuelle Tests/Overrides.
• Solltemperaturen nicht permanent schreiben: Bei Navigator Pro führt permanentes Schreiben der Solltemperaturen zu einem Neustart des Zonenmoduls.
• GLT Log: Zur Diagnose kann im IDM-Menü „Gebäudeleittechnik" → „GLT Log Einschalten" aktiviert werden. Zeigt alle Modbus-Lese- und Schreibzugriffe; wird nach 1 Stunde automatisch deaktiviert.

---

Datentypen

Typ	Beschreibung
uint16be	1 Register, 16-Bit Unsigned Integer, Big-Endian
floatsw	2 Register, IEEE-754 Float, Word-vertauscht (Low-Word zuerst = CDAB)

Float-Dekodierung (struct-basiert, kein pymodbus-Interna)

# Lesen: Reg[0]=Low-Word, Reg[1]=High-Word → float
raw = struct.pack(">HH", registers[1], registers[0])
value = struct.unpack(">f", raw)[0]

# Schreiben: float → [low_word, high_word]
raw = struct.pack(">f", value)
high_word, low_word = struct.unpack(">HH", raw)
registers = [low_word, high_word]

Hintergrund: pymodbus 3.x hat Endian aus pymodbus.constants und den BinaryPayloadDecoder/Builder entfernt. Die struct-basierte Implementierung ist unabhängig von pymodbus-internen APIs und damit stabiler.

---

Modbus-Registerübersicht (Kurzreferenz)

Schlüsselregister

Adresse	Typ	R/W	Bezeichnung
74	floatsw	W	PV-Überschuss (kW) — E3DC schreibt zyklisch
78	floatsw	R	Aktuelle PV-Produktion (kW)
1000	floatsw	R	Außentemperatur aktuell (°C)
1002	floatsw	R	Außentemperatur gemittelt (°C)
1004	uint16	R	Aktuelle Störungsnummer (020–999)
1005	uint16	RW	Betriebsart System ⚠ EEPROM
1006	uint16	RW	Smart Grid Status
1090	uint16	R	Betriebsart Wärmepumpe aktiv
1099	uint16	R	Summenstörung (0=OK, 1=Störung)
1710	uint16	RW	Externe Heizanforderung (zyklisch!)
1711	uint16	RW	Externe Kühlanforderung (zyklisch!)
1712	uint16	RW	Anforderung Warmwasserladung (zyklisch!)
4122	floatsw	R	Aktuelle Leistungsaufnahme WP (kW)