idm-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@idm-mcp check heat pump system status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
uvinstalliertIDM 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 syncUmgebungsvariablen
Variable | Standardwert | Beschreibung |
|
| IP-Adresse der IDM Wärmepumpe |
|
| Modbus-TCP-Port |
|
| 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 |
| Verbindungstest: Außentemp., Betriebsart, Störungsstatus |
| Betriebsart System + WP, Außentemp., Störung, Smart Grid, PV-Überschuss, Leistungsaufnahme |
| Alle Sensoren: WP-Vorlauf B33, Rücklauf B34, HGL B35, Wärmequelle B43/B36, Luft B37/B46/B72, Speicher B38/B40 |
| Trinkwasser oben/unten B48/B41, Zapftemperatur B42, Soll/Ein/Aus-Temperaturen, Ladepumpe M73 |
| Heizkreise A–G: Vorlauf ist/soll, Raumtemperatur, Betriebsart je Kreis |
| Verdichter 1–4, Stufen Heizen/Kühlen/WW, Pumpen M15/M16/M73/M84/M17, alle Umschaltventile M61–M99 |
| Momentanleistung, WP-Aufnahme, kumulierte Wärmemengen (Heizen/Kühlen/WW/Abtauung/Solar/E-Heiz) |
| Kollektor B73/B75, Ladetemperatur B74, Pool B76, Betriebsart Solar |
Schreibend (5)
Tool | Register | Besonderheit |
| 1005 | ⚠ EEPROM — nicht zyklisch schreiben! |
| 1006 | Kernsteuerung für PV & Strommarkt (0/1/2/4) |
| 74 | ⚠ E3DC schreibt diesen Wert normalerweise selbst! |
| 1032/1033/1034 | ⚠ EEPROM — nur bei Bedarf ändern |
| 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 |
| EVU-Sperre & kein PV-Ertrag | WP komplett sperren (Hochpreisstunden) |
| EVU-Bezug & kein PV-Ertrag | Normalbetrieb |
| Kein EVU-Bezug & PV-Ertrag | PV-Überschuss aktiv → WP auf Hochtouren |
| EVU-Sperre & PV-Ertrag | WP läuft trotz Netzsperrung weiter (PV-only) |
Betriebsart System (Register 1005)
Wert | Bezeichnung |
| Standby |
| Automatik (Normalbetrieb) |
| Abwesend |
| Nur Warmwasser |
| 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 |
|
06–08 Uhr | hoch |
|
17–20 Uhr | hoch |
|
PV-Überschuss | — |
|
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 |
| 1 Register, 16-Bit Unsigned Integer, Big-Endian |
| 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
Endianauspymodbus.constantsund denBinaryPayloadDecoder/Builderentfernt. Diestruct-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 toolsidm_get_compressor_statusIDM Verdichter- und PumpenstatusARead-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 EnergiedatenARead-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 HeizkreisstatusARead-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 WarmwasserstatusARead-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 SolarstatusARead-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 SystemstatusARead-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 TemperatursensorenARead-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 VerbindungstestARead-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 setzenAIdempotent
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 setzenAIdempotent
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 setzenAIdempotent
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
Scored across 13 tools
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.
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.
13 tools is within the ideal range for a device-specific server, covering both monitoring and control without being overwhelming or sparse.
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
Related MCP Connectors
Control a Loxone Miniserver smart home: lights, blinds, climate, scenes and energy.
Home energy for AI assistants: live Power flow, Energy history, solar forecast, and device control.
Superseded by io.github.f-tiger/hvac-btu-heat-klimaanlage — same server, same URL.
Superseded by io.github.f-tiger/hvac-btu-heat-klimaanlage — same server, same URL.
Related MCP Servers
- AlicenseAqualityBmaintenanceConnect 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.32134 npm7MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to read and write selected values from IDM heat pumps via Modbus TCP, providing controlled access to operational data and setpoints.3MIT
- AlicenseAqualityCmaintenanceControl and monitor Weishaupt heating systems via the WEM Portal with AI assistants, enabling device discovery, parameter reading/writing, and system overview.858 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables an LLM to read sensor values and control actuators on a Modbus TCP PLC, supporting both boolean and analog tags.5MIT