thermal-mcp-server

一个Python包和MCP服务器，将简化的液冷加速器热模型作为AI可调用的工具，用于机架级冷却分析。

模型功能

• 针对GPU冷板的稳态一维热阻网络。

• 基于能量平衡的冷却液热吸收。

• 达西-魏斯巴赫压降，包含层流、过渡流和湍流的简化处理。

• 使用固定标称属性进行水和50/50乙二醇对比。

• 串联或并联拓扑结构中的相同GPU机架。

• 首次CDU流量、压降、回水温度和结温选型。

• 带有明确来源和估算标签的公开加速器参考案例。

Related MCP server: cad-mcp

模型不涵盖

• 不是CFD求解器或供应商热设计替代品。

• 未针对专有测试数据进行验证。

• 不模拟歧管/集管压力损失、泵曲线、结垢、瞬态/两相行为、二维扩散、详细冷板几何结构或流量分配不均。

• 不支持异构机架；每个机架分析假设相同的GPU和冷板。

• 财务和投资回报率建模不属于本包范围。

快速开始

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

运行 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

串联与并联机架对比：

python examples/rack_sizing_example.py

MCP 使用

安装包：

pip install thermal-mcp-server

将服务器添加到MCP客户端：

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

如果您的MCP客户端未继承shell的 PATH，请使用安装了 thermal-mcp-server 的环境中的Python可执行文件的绝对路径。

MCP客户端运行示例：

客户端通过MCP服务器调用 analyze_coldplate，接收热分析结果，并在对话中解释输出。

要在本地无需单独客户端的情况下复现，请运行内存演示——它在进程中驱动相同的MCP服务器（无需网络，无需API密钥），并打印模型看到的精确请求/响应负载：

python examples/mcp_client_demo.py

工具

工具合同见 docs/mcp.md。

物理假设

模型使用：

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)

传热采用Dittus-Boelter公式（湍流），Nu = 4.36（层流），过渡区采用线性混合。压降采用达西-魏斯巴赫公式，并采用相同的流态划分。

阅读简洁的模型说明，请参见 docs/model_overview.md 和 docs/assumptions.md。详细推导和手算参考见 docs/physics.md。

公开参考案例

示例包括H100 SXM、B200 / GB200 NVL72风格、MI300X和Gaudi 3案例。默认示例中仅将H100 TDP和热限视为供应商发布的值。其他限值、封装电阻和高功率冷板几何结构在供应商未发布的情况下标记为估算或代理值。

参见 docs/public_specs.md 和 examples/real_chip_benchmarks.py。

测试

当前套件包含75个测试：

• 物理行为及手算检查。

• MCP包装器合同和错误边界。

• 决策报告行为，包括机架感知可行性。

• examples/quickstart.py、examples/rack_sizing_example.py 和 examples/mcp_client_demo.py 的冒烟测试。

运行：

pytest

开发

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

这些镜像CI门控；所有测试必须通过才能合并PR。

路线图

• 将泵曲线作为显式输入，而非固定泵效率估算。

• 瞬态热容模型。

• 更多带有清晰标注来源质量的公开参考案例。

• 为Colab使用优化交互式笔记本。

• 冷板优化仅作为独立的实验模块或包。

存在理由

该项目最初是为了探索AI助手如何直接调用轻量级工程模型，而不仅仅是生成静态文本。该包通过Python和MCP工具暴露简化的液冷计算，使得能够以可重复的方式询问关于加速器冷却、机架级CDU选型和冷却剂拓扑结构的设计权衡问题。