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)

Related MCP server: kc_modbus_mcp

Installation

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

Umgebungsvariablen

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)

Schreibend (5)

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:

Betriebsart System (Register 1005)

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:

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

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