thermal-mcp-server

Ein Python-Paket und MCP-Server, der vereinfachte thermische Modelle für flüssigkeitsgekühlte Beschleuniger als KI-aufrufbare Werkzeuge für die Rack-Level-Kühlungsanalyse bereitstellt.

Was es modelliert

• Stationäre 1D-Wärmewiderstandsnetzwerke für GPU-Kühlplatten.

• Kühlmittel-Wärmeaufnahme aus der Energiebilanz.

• Darcy-Weisbach-Druckverlust mit einfacher laminarer, Übergangs- und turbulenter Behandlung.

• Wasser- und 50/50-Glykol-Vergleiche mit festen nominalen Eigenschaften.

• Racks mit identischen GPUs in Serien- oder Parallel-Topologie.

• Erste CDU-Durchfluss-, Druckverlust-, Rücklauf-Temperatur- und Junction-Temperatur-Auslegung.

• Öffentliche Beschleuniger-Referenzfälle mit expliziten Quellen- und Schätzetiketten.

Related MCP server: cad-mcp

Was es nicht modelliert

• Es ist kein CFD-Löser oder Ersatz für die thermische Auslegung durch den Hersteller.

• Es ist nicht gegen proprietäre Testergebnisse validiert.

• Es modelliert keine Verteiler-/Kopfstückdruckverluste, Pumpenkennlinien, Verschmutzung, transientes/Zweiphasen-Verhalten, 2D-Ausbreitung, detaillierte Kühlplattengeometrie oder Fehlverteilung des Durchflusses.

• Es unterstützt keine heterogenen Racks; jede Rack-Analyse geht von identischen GPUs und Kühlplatten aus.

• Finanz- und ROI-Modellierung gehört nicht in dieses Paket.

Schnellstart

git clone https://github.com/riccardovietri/thermal-mcp-server.git
cd thermal-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
python examples/quickstart.py

Erwartete Ausgabe von python examples/quickstart.py:

thermal-mcp-server quickstart

Single H100 SXM cold plate
  Heat load:        700 W
  Flow rate:        8.0 LPM water
  Inlet temp:       25.0 deg C
  Junction temp:    70.9 deg C
  Margin to 83 C:   12.1 deg C
  Pressure drop:    16.8 kPa
  Flow regime:      transitional

8-GPU rack, parallel topology
  Rack heat load:   5.6 kW
  Total CDU flow:   64.0 LPM
  Max junction:     70.9 deg C
  CDU return temp:  26.3 deg C
  Cold-plate dP:    16.8 kPa

Für einen Serien-gegen-Parallel-Rack-Vergleich:

python examples/rack_sizing_example.py

MCP-Verwendung

Installieren Sie das Paket:

pip install thermal-mcp-server

Fügen Sie den Server zu einem MCP-Client hinzu:

{
  "mcpServers": {
    "thermal": {
      "command": "python",
      "args": ["-m", "thermal_mcp_server"]
    }
  }
}

Wenn Ihr MCP-Client Ihren Shell-PATH nicht erbt, verwenden Sie den absoluten Pfad zur Python-Ausführungsdatei in der Umgebung, in der thermal-mcp-server installiert ist.

Beispiel für einen MCP-Client-Lauf:

Der Client ruft analyze_coldplate über den MCP-Server auf, erhält das thermische Ergebnis und interpretiert die Ausgabe im Gespräch.

Um dies lokal ohne separaten Client zu reproduzieren, führen Sie die In-Memory-Demo aus – sie treibt denselben MCP-Server prozessintern an (kein Netzwerk, kein API-Schlüssel) und gibt die exakten Anfrage-/Antwort-Payloads aus, die ein Modell sieht:

python examples/mcp_client_demo.py

Werkzeuge

Siehe docs/mcp.md für Werkzeugverträge.

Physikalische Annahmen

Das Modell verwendet:

T_junction = T_inlet + 0.5 * coolant_rise + Q * R_total
R_total = R_jc + R_tim + R_base + R_conv
coolant_rise = Q / (m_dot * cp)

Die Wärmeübertragung verwendet Dittus-Boelter für turbulente Strömung, Nu = 4,36 für laminare Strömung und eine lineare Mischung im Übergangsbereich. Der Druckverlust verwendet Darcy-Weisbach mit derselben Strömungsregime-Aufteilung.

Lesen Sie die prägnanten Modellnotizen in docs/model_overview.md und docs/assumptions.md. Die detaillierte Herleitung und Handrechnungsreferenzen finden Sie in docs/physics.md.

Öffentliche Referenzfälle

Die Beispiele enthalten Fälle für H100 SXM, B200 / GB200 NVL72-artig, MI300X und Gaudi 3. Nur H100 TDP und thermische Grenze werden in den Standardbeispielen als vom Hersteller veröffentlichte Werte behandelt. Andere Grenzen, Paketwiderstände und Hochleistungs-Kühlplattengeometrie sind als Schätzwerte oder Näherungen gekennzeichnet, wenn Hersteller sie nicht veröffentlichen.

Siehe docs/public_specs.md und examples/real_chip_benchmarks.py.

Tests

Die aktuelle Suite umfasst 75 Tests:

• Physikverhalten und Handrechnungsprüfungen.

• MCP-Wrapper-Verträge und Fehlerhüllen.

• Entscheidungsberichtverhalten, einschließlich rackbewusster Machbarkeit.

• Rauchtests für examples/quickstart.py, examples/rack_sizing_example.py und examples/mcp_client_demo.py.

Ausführen:

pytest

Entwicklung

uv sync --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv build
uv run python examples/quickstart.py
uv run python examples/rack_sizing_example.py

Diese spiegeln das CI-Gate wider; alle müssen bestanden sein, bevor ein PR gemergt werden kann.

Fahrplan

• Unterstützung von Pumpenkennlinien als explizite Eingabe anstelle einer festen Pumpenwirkungsgrad-Schätzung.

• Transientes Wärmekapazitätsmodell.

• Weitere öffentliche Referenzfälle mit klar gekennzeichneter Quellenqualität.

• Interaktive Notebook-Verbesserung für die Colab-Nutzung.

• Kühlplattenoptimierung nur als separates experimentelles Modul oder Paket.

Warum es dies gibt

Dieses Projekt begann als eine Möglichkeit zu erkunden, wie KI-Assistenten leichte Ingenieurmodelle direkt aufrufen können, anstatt nur statischen Text zu produzieren. Das Paket stellt vereinfachte Flüssigkeitskühlungsberechnungen über Python- und MCP-Werkzeuge bereit und ermöglicht es, reproduzierbare Design-Abwägungsfragen zu Beschleuniger-Kühlung, Rack-Level-CDU-Auslegung und Kühlmittel-Topologie zu stellen.