PyThermoModels-MCP

PyThermoModels-MCP is a Model Context Protocol (MCP) server for running selected PyThermoModels thermodynamic calculations from agents and MCP-compatible clients.

Overview 🌐

The package exposes Equation of State (EOS), activity-coefficient, tau-parameter, and YAML reference-validation workflows as MCP tools. Each calculation receives structured arguments, builds a pyThermoLinkDB ModelSource from caller-supplied pyThermoDB YAML reference content, calls the corresponding pyThermoModels core function, and returns JSON-safe data.

Use this package when an agent or MCP client needs to:

• Check pure-component or mixture EOS root behavior.
• Calculate pure-component gas or liquid fugacity.
• Calculate mixture fugacity values and fugacity coefficients.
• Calculate NRTL or UNIQUAC liquid activity coefficients.
• Calculate NRTL or UNIQUAC tau_ij interaction parameters.
• Validate whether YAML reference content is usable by the pyThermoDB reference pipeline.

The server does not search for, load, or assemble reference files automatically. Callers must pass complete YAML reference content in each tool request.

Requirements 📋

• Python >=3.11
• pip or uv

Installation 📦

pip install pythermomodels-mcp

This installs the pythermomodels-mcp command.

Running the MCP Server ▶️

The server entrypoints are:

• CLI: pythermomodels-mcp
• Module: python -m pythermomodels_mcp.server

Both support the same options.

STDIO Transport 🧵

Use STDIO for local MCP desktop and agent clients:

pythermomodels-mcp --mode stdio

Equivalent module command:

python -m pythermomodels_mcp.server --mode stdio

HTTP Transport 🌍

Use HTTP when a network-accessible MCP endpoint is needed:

pythermomodels-mcp --mode http --host 127.0.0.1 --port 8000 --path /mcp

Equivalent module command:

python -m pythermomodels_mcp.server --mode http --host 127.0.0.1 --port 8000 --path /mcp

CLI Options ⌨️

• --mode: MCP transport mode, either stdio or http (default: stdio)
• --host: HTTP bind host (default: 127.0.0.1)
• --port: HTTP bind port (default: 8000)
• --path: HTTP endpoint path (default: /mcp)
• -V, --version: print package version

MCP Client Configuration 🔌

STDIO

{
  "mcpServers": {
    "pythermomodels": {
      "command": "pythermomodels-mcp",
      "args": ["--mode", "stdio"]
    }
  }
}

HTTP

{
  "mcpServers": {
    "pythermomodels": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

MCP Resources 📚

The server exposes two guidance resources:

• pythermomodels://references/eos-requirements
  • YAML guidance for EOS tools, including required reference content, supported EOS names, solver options, component keys, and root-check guidance.
• pythermomodels://references/activity-requirements
  • YAML guidance for activity tools, including NRTL/UNIQUAC source requirements, liquid-component requirements, tau-correlation options, and source-building behavior.

MCP Tools 🧰

EOS Tools 🔥

All EOS tools require reference_content, pressure, temperature, and component data. Supported EOS model names are SRK, PR, RK, and vdW.

• check_pure_component_eos_roots
  • Checks EOS roots for one component at a specified pressure and temperature.
• calculate_gas_fugacity
  • Calculates pure-component gas fugacity and fugacity coefficient.
• calculate_liquid_fugacity
  • Calculates pure-component liquid fugacity using either the EOS or Poynting route.
• check_mixture_eos_roots
  • Checks EOS roots for a mixture. Mixture component mole fractions must sum to 1.0.
• calculate_mixture_fugacity
  • Calculates mixture fugacity results and component fugacity coefficients.

Activity-Model Tools 💧

Activity tools are for liquid mixtures. Every component must use state: l, and the component mole fractions must sum to 1.0.

• calculate_nrtl_activity_coefficient
  • Calculates NRTL activity coefficients, auxiliary model output, and excess Gibbs energy.
• calculate_nrtl_tau_ij
  • Calculates NRTL tau_ij values and returns both an array and dictionary representation.
• calculate_uniquac_activity_coefficient
  • Calculates UNIQUAC activity coefficients, auxiliary model output, and excess Gibbs energy. UNIQUAC activity calculations need component data such as r and q in addition to mixture interaction data.
• calculate_uniquac_tau_ij
  • Calculates UNIQUAC tau_ij values and returns both an array and dictionary representation.

Utility Tool 🛠️

• check_yaml_reference
  • Validates YAML reference content with the pyThermoDB custom-reference checker and returns true or false.

Input Model Notes 📝

Tool functions receive one Pydantic argument named args. Typical tool input therefore looks like:

{
  "args": {
    "reference_content": "REFERENCES:\n  ...",
    "component": {
      "name": "propane",
      "formula": "C3H8",
      "state": "g"
    },
    "temperature": {
      "value": 300.1,
      "unit": "K"
    },
    "pressure": {
      "value": 9.99,
      "unit": "bar"
    },
    "model_name": "SRK",
    "component_key": "Name-State",
    "kwargs": {
      "mode": "silent"
    }
  }
}

Use the resource documents for full reference-content requirements before calling tools.

Best Practices ✅

• Pass complete, non-empty reference_content in every calculation request.
• Use check_yaml_reference before calculations when reference content is generated dynamically.
• Keep component_key, mixture_key, separator, and delimiter choices consistent across related calls.
• For mixture tools, provide mole fractions that sum to 1.0.
• For activity tools, use liquid-state components only.
• Use kwargs for advanced pyThermoModels options such as silent mode, tolerances, or phase controls.

Development Quick Check 🧪

python -m py_compile pythermomodels_mcp/server.py
python -m py_compile pythermomodels_mcp/interface/eos_models.py
python -m py_compile pythermomodels_mcp/interface/activity_models.py

Examples 🚀

Example scripts are available under:

• examples/eos
• examples/activity
• examples/references

They show how to create an in-process FastMCP client, pass reference_content, call tools, and read JSON-safe result.data.

Troubleshooting 🩺

• pythermomodels-mcp: command not found
  • Install the package in the active environment: pip install -e .
  • Confirm the active Python environment is the one used by your MCP client.
• Port already in use in HTTP mode
  • Choose another port, for example --port 8010.
• Empty or invalid reference errors
  • Confirm that reference_content is complete YAML content and includes all component or mixture data required by the selected model.
• Mole fraction validation errors
  • Confirm mixture mole fractions sum to exactly 1.0 within numerical tolerance.

FAQ ❓

For questions, contact Sina Gilassi on LinkedIn.

License 📄

This project is licensed under the Apache License 2.0. See LICENSE.

Author 👨‍💻

• @sinagilassi