thermal-mcp-server

Un paquete de Python y servidor MCP que expone modelos térmicos simplificados de aceleradores refrigerados por líquido como herramientas invocables por IA para el análisis de refrigeración a nivel de rack.

Lo que modela

• Redes de resistencia térmica 1D en estado estacionario para placas frías de GPU.

• Captación de calor del refrigerante mediante balance energético.

• Caída de presión de Darcy-Weisbach con manejo simple de flujo laminar, transición y turbulento.

• Comparaciones de agua y 50/50 glicol utilizando propiedades nominales fijas.

• Racks de GPU idénticas en topología serie o paralelo.

• Dimensionamiento de primera aproximación de CDU: caudal, caída de presión, temperatura de retorno y temperatura de unión.

• Casos de referencia públicos de aceleradores con etiquetas explícitas de fuente y estimación.

Related MCP server: cad-mcp

Lo que no modela

• No es un solucionador CFD ni un sustituto del diseño térmico del fabricante.

• No está validado con datos de pruebas propietarios.

• No modela pérdidas de presión en colectores/tuberías, curvas de bombas, incrustaciones, comportamiento transitorio/bifásico, dispersión 2D, geometría detallada de la placa fría ni mala distribución del flujo.

• No admite racks heterogéneos; cada análisis de rack asume GPU y placas frías idénticas.

• El modelado financiero y de ROI queda fuera de este paquete.

Inicio rápido

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

Salida esperada de 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

Para una comparación de racks en serie frente a paralelo:

python examples/rack_sizing_example.py

Uso de MCP

Instale el paquete:

pip install thermal-mcp-server

Añada el servidor a un cliente MCP:

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

Si su cliente MCP no hereda el PATH de su shell, use la ruta absoluta al ejecutable de Python dentro del entorno donde esté instalado thermal-mcp-server.

Ejemplo de ejecución de un cliente MCP:

El cliente llama a analyze_coldplate a través del servidor MCP, recibe el resultado térmico e interpreta la salida en la conversación.

Para reproducir esto localmente sin un cliente aparte, ejecute la demo en memoria: impulsa el mismo servidor MCP en proceso (sin red, sin clave API) e imprime las cargas útiles exactas de solicitud/respuesta que ve un modelo:

python examples/mcp_client_demo.py

Herramientas

Consulte docs/mcp.md para los contratos de las herramientas.

Suposiciones físicas

El modelo utiliza:

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)

La transferencia de calor emplea Dittus-Boelter para flujo turbulento, Nu = 4.36 para flujo laminar y una mezcla lineal en la transición. La caída de presión usa Darcy-Weisbach con la misma división de régimen.

Lea las notas concisas del modelo en docs/model_overview.md y docs/assumptions.md. La derivación detallada y las referencias de cálculo manual están en docs/physics.md.

Casos de referencia públicos

Los ejemplos incluyen casos H100 SXM, B200 / GB200 estilo NVL72, MI300X y Gaudi 3. Solo el TDP y el límite térmico del H100 se tratan como valores publicados por el fabricante en los ejemplos por defecto. Otros límites, resistencias del encapsulado y geometría de placa fría de alta potencia se marcan como estimaciones o aproximaciones cuando los fabricantes no los publican.

Consulte docs/public_specs.md y examples/real_chip_benchmarks.py.

Pruebas

El conjunto actual tiene 75 pruebas:

• Comprobaciones de comportamiento físico y cálculos manuales.

• Contratos del envoltorio MCP y envolventes de error.

• Comportamiento del informe de decisión, incluida la viabilidad consciente del rack.

• Pruebas de humo para examples/quickstart.py, examples/rack_sizing_example.py y examples/mcp_client_demo.py.

Ejecute:

pytest

Desarrollo

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

Estas reflejan la puerta de CI; todas deben pasar antes de que un PR pueda fusionarse.

Hoja de ruta

• Soporte de curva de bomba como entrada explícita en lugar de una estimación fija de eficiencia de bomba.

• Modelo transitorio de capacitancia térmica.

• Más casos de referencia públicos con calidad de fuente claramente etiquetada.

• Pulido del cuaderno interactivo para uso en Colab.

• Optimización de placa fría solo como módulo o paquete experimental separado.

Por qué existe esto

Este proyecto comenzó como una forma de explorar cómo los asistentes de IA pueden llamar directamente a modelos de ingeniería ligeros en lugar de solo producir texto estático. El paquete expone cálculos simplificados de refrigeración líquida a través de herramientas Python y MCP, lo que permite hacer preguntas sobre compensaciones de diseño en refrigeración de aceleradores, dimensionamiento de CDU a nivel de rack y topología de refrigerante de manera reproducible.