Skip to main content
Glama

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: IDM Heat Pump MCP Server

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)

Available Tools

13 tools
idm_get_compressor_statusIDM Verdichter- und PumpenstatusA
Read-onlyIdempotent

Liest den Status von Verdichtern, Pumpen und Umschaltventilen.

Liefert: Status Verdichter 1–4, laufende Verdichterstufen (Heizen/ Kühlen/WW), Sole/ZK-Pumpe (M16), Wärmequellen/GW-Pumpe (M15), ISC-Pumpen (M84/M17) sowie alle Umschaltventile (M61–M99).

Returns: str: JSON-Objekt mit Verdichter- und Pumpenstatus.

Inputs: no named parameters. Returns: result

idm_get_energy_dataIDM EnergiedatenA
Read-onlyIdempotent

Liest Energiezähler und Momentanleistungen der IDM Wärmepumpe.

Liefert: Momentanleistung, Leistungsaufnahme WP, sowie kumulierte Wärmemengen für Heizen, Kühlen, Warmwasser, Abtauung, Passive Kühlung, Solar und Elektroheizeinsatz.

Returns: str: JSON-Objekt mit Leistungs- und Energiedaten in kW / kWh.

Inputs: no named parameters. Returns: result

idm_get_heat_circuitsIDM HeizkreisstatusA
Read-onlyIdempotent

Liest den Status aller Heizkreise (A–G) der IDM Wärmepumpe.

Liefert für jeden Heizkreis: Ist-Vorlauftemperatur, Soll-Vorlauftemperatur, Raumtemperatur sowie die aktive Betriebsart (Aus / Zeitprogramm / Normal / ECO / Manuell Heizen / Manuell Kühlen).

Returns: str: JSON-Objekt mit Heizkreisdaten für HK A bis HK G.

Inputs: no named parameters. Returns: result

idm_get_hot_water_statusIDM WarmwasserstatusA
Read-onlyIdempotent

Liest den Warmwasser- und Trinkwasserstatus der IDM Wärmepumpe.

Liefert: Trinkwassererwärmer oben (B48) und unten (B41), Warmwasserzapftemperatur (B42), Warmwasser-Solltemperatur sowie die Einschalt- und Ausschalttemperatur der Warmwasserladung. Außerdem Status Anforderung Warmwasserladung und Ladepumpe (M73).

Returns: str: JSON-Objekt mit Warmwasser-Zustandsdaten.

Inputs: no named parameters. Returns: result

idm_get_solar_statusIDM SolarstatusA
Read-onlyIdempotent

Liest den Solarstatus der IDM Wärmepumpe (thermische Solaranlage).

Liefert: Kollektortemperatur (B73), Kollektorrücklauftemperatur (B75), Ladetemperatur (B74), Solar-Pool-Temperatur (B76), Betriebsart Solar sowie Momentanleistung Solar.

Returns: str: JSON-Objekt mit Solardaten.

Inputs: no named parameters. Returns: result

idm_get_system_statusIDM SystemstatusA
Read-onlyIdempotent

Liest den allgemeinen Systemstatus der IDM Wärmepumpe.

Liefert: Betriebsart System, Betriebsart Wärmepumpe, Außen- & gemittelte Außentemperatur, aktuelle Störungsnummer, Summenstörung, Smart-Grid-Status sowie den aktuell kommunizierten PV-Überschuss und die aktuelle Leistungsaufnahme der Wärmepumpe.

Returns: str: JSON-Objekt mit allen Statusfeldern.

Inputs: no named parameters. Returns: result

idm_get_temperaturesIDM TemperatursensorenA
Read-onlyIdempotent

Liest alle Temperatursensoren der IDM Wärmepumpe.

Liefert: WP-Vorlauf (B33), WP-Rücklauf (B34), HGL-Vorlauf (B35), Wärmequelleneintritt (B43), Wärmequellenaustritt (B36), Luftansaugtemperatur (B37/B46), Luftwärmetauscher (B72), Wärme- und Kältespeicher (B38/B40) sowie Momentanleistung.

Returns: str: JSON-Objekt mit allen Temperaturen in °C.

Inputs: no named parameters. Returns: result

idm_health_checkIDM VerbindungstestA
Read-onlyIdempotent

Prüft die Modbus-TCP-Verbindung zur IDM Wärmepumpe.

Liest Außentemperatur, Betriebsart und Summenstörung als Verbindungstest.

Returns: str: JSON-Objekt mit Verbindungsstatus und Basiswerten.

Inputs: no named parameters. Returns: result

idm_set_demandIDM Externe Anforderung setzenA

Setzt externe Heiz-, Kühl- und/oder Warmwasseranforderungen.

⚠ Diese Register MÜSSEN ZYKLISCH geschrieben werden (z. B. alle 30 s), damit die Anforderung nach einem Neustart der WP wieder anliegt!

Verwendung: heizen → Register 1710: Puffer-Bewirtschaftung Heizen kuehlen → Register 1711: Puffer-Bewirtschaftung Kühlen / Passivkühlung warmwasser → Register 1712: Warmwasserladung forcieren

Args: params (SetDemandInput): Anforderungsflags (True=Ein, False=Aus).

Returns: str: JSON-Bestätigung der gesetzten Anforderungen.

Inputs: params (required). Returns: result

idm_set_hot_water_setpointsIDM Warmwasser-Sollwerte setzenA
Idempotent

Setzt Warmwasser-Solltemperatur, Ein- und/oder Ausschalttemperatur.

⚠ EEPROM-Register (mit * markiert): Begrenzte Schreibzyklen! NICHT permanent oder zyklisch schreiben – nur bei Bedarf ändern.

Mindestens einen der drei Parameter angeben: solltemperatur_c – Warmwasser-Solltemperatur (Register 1032) einschalttemperatur_c – Einschalttemperatur Ladung (Register 1033) ausschalttemperatur_c – Ausschalttemperatur Ladung (Register 1034)

Args: params (SetHotWaterSetpointInput): Warmwasser-Sollwerte.

Returns: str: JSON-Bestätigung mit allen gesetzten Werten.

Inputs: params (required). Returns: result

idm_set_pv_surplusIDM PV-Überschuss kommunizierenA

Schreibt den aktuellen PV-Überschuss an die IDM Wärmepumpe (Register 74).

⚠ WICHTIG: Im laufenden Betrieb schreibt das E3DC Hauskraftwerk diesen Wert automatisch und zyklisch. Direktes Schreiben durch diesen Server überschreibt die E3DC-Vorgabe TEMPORÄR bis zum nächsten E3DC-Zyklus!

Die WP startet zusätzliche Wärmeproduktion (Fußbodenheizung, Pufferspeicher), sobald der PV-Überschuss die Leistungsaufnahme der WP übersteigt.

Dieser Wert muss ZYKLISCH geschrieben werden – nicht einmalig!

Args: params.pv_ueberschuss_kw (float): PV-Überschuss in kW (0 bis 100 kW).

Returns: str: JSON-Bestätigung mit geschriebenem Wert.

Inputs: params (required). Returns: result

idm_set_smart_gridIDM Smart Grid Status setzenA
Idempotent

Setzt den Smart Grid Status der IDM Wärmepumpe (Register 1006).

Ermöglicht externe Steuerung über Energiemarkt-Signale oder E3DC/Victron: 0 = EVU-Sperre & kein PV-Ertrag (gesperrter Betrieb) 1 = EVU-Bezug & kein PV-Ertrag (Normalbetrieb) 2 = Kein EVU-Bezug & PV-Ertrag (PV-Überschuss → WP läuft extra) 4 = EVU-Sperre & PV-Ertrag (PV-Betrieb trotz Sperrsignal)

Hinweis für zukünftige Strommarktsteuerung (viertelstündlich): Modus 0 bei Hochpreisphasen (06–08 Uhr, 17–20 Uhr) → WP sperren Modus 2 bei Niedrigpreisphasen → maximale PV-/Netz-Nutzung

Args: params.status (int): Smart Grid Status (0/1/2/4).

Returns: str: JSON-Bestätigung mit geschriebenem Wert.

Inputs: params (required). Returns: result

idm_set_system_modeIDM Betriebsart setzenA
Idempotent

Setzt die Betriebsart des IDM-Gesamtsystems (Register 1005, EEPROM!).

⚠ EEPROM-Register: Begrenzte Schreibzyklen. Nicht permanent/zyklisch schreiben!

Gültige Werte: 0 = Standby 1 = Automatik (Normalbetrieb) 2 = Abwesend 4 = Nur Warmwasser 5 = Nur Heizung/Kühlung

Args: params.modus (int): Gewünschte Betriebsart (0/1/2/4/5).

Returns: str: JSON-Bestätigung mit geschriebenem Wert und Bezeichnung.

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools are clearly distinct, but idm_health_check overlaps slightly with idm_get_system_status by reading similar values (Außentemperatur, Betriebsart, Summenstörung). The rest each target a unique subsystem or control aspect.

    Naming Consistency5/5

    All tools follow a consistent idm_verb_noun pattern. Reads use get_, writes use set_, and health_check is a clear exception but still follows the prefix convention.

    Tool Count5/5

    13 tools is within the ideal range for a device-specific server, covering both monitoring and control without being overwhelming or sparse.

    Completeness4/5

    Good lifecycle coverage for the heat pump domain: all major subsystems are readable, and key control actions (mode, smart grid, PV surplus, hot water setpoints, demand) are writable. Minor gap: no setters for heating circuit setpoints/curves, but that may be outside the server's scope.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Connect AI assistants to Victron Energy systems to read real-time solar, battery, grid, and inverter data from your local network via Modbus TCP or MQTT.
      32
      134 npm
      7
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Control and monitor Weishaupt heating systems via the WEM Portal with AI assistants, enabling device discovery, parameter reading/writing, and system overview.
      8
      58 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an LLM to read sensor values and control actuators on a Modbus TCP PLC, supporting both boolean and analog tags.
      5
      MIT