thermal-mcp-server

A physics engine for liquid-cooled GPU systems, exposed as an AI-callable MCP server. Ask Claude to size a cooling system for an H100 cluster, optimize cold plate flow rates, or compare water versus glycol — and get first-principles answers backed by hand-validated thermal models.

Quick Start

Try it now — open the interactive notebook in Colab to run NVL72 rack sizing, topology comparisons, and flow optimization interactively.

Install and use as an MCP server:

pip install thermal-mcp-server

Add to your MCP client config (claude_desktop_config.json for Claude Desktop):

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

Note: Claude Desktop does not inherit your shell's PATH. If the above doesn't work, use the absolute path to your Python binary (e.g. /usr/local/bin/python or the path inside a virtualenv).

Once configured, ask Claude engineering questions directly:

"I have 8 H100 SXM GPUs at 700 W each, water cooling at 8 LPM per cold plate, 25°C supply. What's the junction temperature and thermal margin?"

"Compare water versus 50/50 glycol for a 700 W load at 8 LPM."

"Size a CDU for 8 H100 GPUs in a parallel manifold — total flow, system ΔP, and return water temperature."

Claude calls the relevant tool, interprets the physics, and answers in context.

Claude Desktop calling analyze_coldplate via the MCP server. The user asks a natural-language thermal question; Claude picks the right tool, runs the physics, and interprets the result.

Example: H100 SXM Baseline

This is the hand-calculation validated reference case — every intermediate value (Reynolds number, Nusselt number, convection coefficient, pressure drop) is independently verified in tests/test_physics_behavior.py.

from thermal_mcp_server.physics import analyze
from thermal_mcp_server.schemas import AnalyzeColdplateInput

result = analyze(AnalyzeColdplateInput(
    heat_load_w=700, flow_rate_lpm=8.0, inlet_temp_c=25.0, coolant="water"
))
print(f"Junction temp: {result.junction_temp_c:.1f}°C")   # 70.9°C
print(f"Thermal margin: {83 - result.junction_temp_c:.1f}°C below throttle onset")
print(f"Flow regime: {result.regime}")                      # transitional (Re ≈ 3734)
print(f"Pressure drop: {result.pressure_drop_pa:.0f} Pa")   # 16800 Pa (0.17 bar)

For rack-scale analysis (NVL72 CDU sizing, series vs. parallel topology, B200 at 1,200 W), see the interactive notebook.

Tools

Four MCP tools, each also available as a Python function:

See docs/mcp.md for full input/output schemas.

How It Works

The physics engine models a cold plate as a 1D thermal resistance network:

T_junction = T_inlet + Q × (R_jc + R_tim + R_base + R_conv) + ΔT_coolant/2

• R_jc / R_tim: Package resistances (chip manufacturer spec or estimate)

• R_base: Copper base conduction (geometry + k = 385 W/m·K)

• R_conv: Forced convection — Dittus-Boelter (turbulent) or Nu = 4.36 (laminar), linearly blended through transition (Re 2,300–4,000)

• ΔP: Darcy-Weisbach with Blasius friction factor, same transition blend

Rack-level model stacks N single-GPU analyses in series (cumulative temperature rise) or parallel (uniform inlet, flow split) topology.

flowchart LR
    A["Input\nchip power, flow,\ncoolant, geometry"] --> B["Physics Engine\nDittus-Boelter · Darcy-Weisbach\nR_total network"]
    B --> C["Output\nT_junction · ΔP\nthermal margin · pump power"]

See docs/physics.md for the full physics documentation including equations and assumptions.

Validation

Model outputs against published chip specs. All runs use water coolant, 25°C inlet.

On B200 and Gaudi 3 numbers: NVIDIA and Intel do not publish cold plate geometry or R_jc for these chips. The B200 analysis uses engineering estimates. Treat as indicative; real sizing requires vendor data.

Chip sources: NVIDIA H100 Datasheet · NVIDIA GB200 NVL72 · SemiAnalysis B200 thermal estimates · AMD MI300X Data Sheet · Intel Gaudi 3 Product Brief

Known Limitations

These are documented explicitly because they bound what the model can and cannot tell you:

• No manifold or header pressure losses — rack ΔP is cold-plate-only. Real system ΔP should add 20–50% for manifold losses.

• No heterogeneous racks — all GPUs assumed identical TDP, geometry, and thermal resistance.

• Steady-state only — no transient thermal capacitance.

• Single-point fluid properties — water and glycol50 properties fixed at 25°C nominal.

• No flow maldistribution — uniform flow assumed across all cold plates.

Development

git clone https://github.com/riccardovietri/thermal-mcp-server.git
cd thermal-mcp-server
uv sync --group dev
uv run pytest -v  # all tests should pass

Roadmap

• Interactive demo polish — expand the Colab notebook with sensitivity outputs and clearer walkthrough

• ROI calculator — annual cooling cost delta between air and liquid, CDU payback period, per-GPU cooling cost