Content
# PVTsim MCP
<p align="center">
<strong>Enable AI to drive PVTsim Nova CCS for professional PVT calculations via MCP</strong>
</p>
PVTsim MCP is a [Model Context Protocol](https://modelcontextprotocol.io/) server that wraps Calsep's **PVTsim Nova CCS 7** fluid phase behavior calculation software into an AI-callable toolset. AI assistants (like Claude) can use natural language to read `.nfdb` fluid databases, run Flash calculations, phase envelope calculations, PVT reservoir experiments (CME/CVD/DD/MMP/Swelling, etc.), and simulator format exports (Eclipse/OLGA), with results consistent with PVTsim GUI. No GUI launch or prior `.nfdb` file preparation is required - most calculations support direct input of components and proportions in the conversation.
> This project does not distribute any binary files of PVTsim. Please purchase and install a legitimate PVTsim Nova CCS license before use.
---
## Table of Contents
- [Core Features](#core-features)
- [Project Architecture](#project-architecture)
- [Environment Requirements](#environment-requirements)
- [Quick Start](#quick-start)
- [Configuration Instructions](#configuration-instructions)
- [MCP Tool List](#mcp-tool-list)
- [Supported EOS Models](#supported-eos-models)
- [Supported Flash Modes](#supported-flash-modes)
- [Usage Examples](#usage-examples)
- [Project Structure](#project-structure)
- [Frequently Asked Questions](#frequently-asked-questions)
- [License](#license)
---
## Core Features
- 🎯 **100% consistent results with GUI** — Calling PVTsim's identical .NET / Fortran code paths
- 🧪 **Covering all 13 Flash modes** — PT, PH, PS, UV, HS, VT, P-β, T-β, K-factor, Split-factor, etc.
- 📊 **Supporting all 9 EOS models** — SpanWagner, GERG2008, SRK/PR Peneloux (including temperature-related variants), Leachman
- 🗂️ **Three fluid input methods** — `.nfdb` saved fluid, PVTsim JSON fluid export, and instant construction from components
- 📈 **Phase envelope calculation** — Automatic PT phase diagram plotting and JSON/CSV/SVG export
- 🔬 **16 PVT reservoir experiments** — CriticalPoint, Viscosity, CME, CVD, DD, MMP, Swelling, Wax, Hydrate, Scale, Pxy/Txy, PhaseMapping, SeparatorTest, SaturateWithCO2, ConstantMassExpansionDryGas. Each experiment supports `_saved_fluid` (from `.nfdb`), `_fluid_export` (from JSON), and `_from_components` (direct component input) fluid sources
- 📤 **Simulator format export** — Eclipse BlackOil PVT table (PVT/PVD/PVC), phase envelope/Flash result export (JSON/CSV/SVG)
- 🔍 **Complete property output** — Phase state, composition, fugacity, partial molar volume, partial molar residual enthalpy, JT coefficient, sound speed, viscosity, thermal conductivity, etc.
- 🛡️ **Strict input validation** — Rejecting ambiguous fields, enforcing unit clarity
---
## Project Architecture
```
Claude / Other MCP Clients
│ MCP Protocol (stdio)
▼
pvtsim-mcp Server (Python 3.10+)
│
├── MCP Tools layer (81 tools)
│ ├── Fluid database reading (9 tools)
│ ├── Flash calculation (10 tools)
│ ├── Phase Envelope calculation (8 tools)
│ ├── PVT reservoir experiment (48 tools)
│ ├── Data/format export (4 tools)
│ └── GUI Excel reading (2 tools)
│
└── PVTsimBridge (C# .NET 8.0 console program)
├── Loading PVTsim .NET assemblies
├── Calling Fortran.Model.Api via reflection
└── Serializing results to JSON and returning
│
▼
PVTsim Nova CCS 7 installation directory (pointed to by PVTSIM_PATH)
├── Foundational.*.dll (.NET assemblies)
├── Lib/*.DLL (Fortran calculation engines, ~90)
└── CCS demodataV7.nfdb (example fluid database)
```
PVTsim does not have a public REST/COM/CLI interface, and direct Fortran DLL calls are not feasible. Using the .NET Bridge to call PVTsim's .NET managed layer is the only approach that guarantees numerical accuracy consistent with the GUI.
---
## Environment Requirements
| Component | Version | Description |
|------|------|------|
| **PVTsim Nova CCS** | 7.0+ | Requires a legitimate license for purchase and installation |
| **.NET SDK** | 8.0+ (Windows) | For building the C# Bridge |
| **Python** | 3.10+ | For running the MCP Server |
| **Operating System** | Windows 10/11 | PVTsim only supports Windows |
### Python Dependencies
```bash
pip install mcp>=1.0.0
pip install openpyxl # Optional: reading PVTsim GUI-exported Pxy/Txy Excel
pip install pytest # Optional: running test suites
```
---
## Quick Start
### 1. Clone the repository
```bash
git clone https://github.com/stunner979/pvtsim-mcp.git
cd pvtsim-mcp
```
### 2. Set the PVTsim path environment variable
If PVTsim is installed in the default path `C:\Program Files\Calsep\PVTsim Nova CCS 7`, skip this step.
```powershell
# PowerShell (permanent setting)
[Environment]::SetEnvironmentVariable("PVTSIM_PATH", "C:\Program Files\Calsep\PVTsim Nova CCS 7", "User")
# Or temporarily set for the current session
$env:PVTSIM_PATH = "C:\Program Files\Calsep\PVTsim Nova CCS 7"
```
### 3. Build the C# Bridge
```powershell
cd bridge
dotnet build -c Debug
cd ..
```
### 4. Configure MCP in Claude Desktop
Edit the Claude Desktop configuration file:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"pvtsim": {
"command": "python",
"args": ["-m", "pvtsim_mcp.server"],
"cwd": "<path-to-pvtsim-mcp>",
"env": {
"PVTSIM_PATH": "C:\\Program Files\\Calsep\\PVTsim Nova CCS 7"
}
}
}
}
```
You can also directly point to the source code without `pip install`:
```json
"command": "python",
"args": ["<path-to-pvtsim-mcp>\\src\\pvtsim_mcp\\server.py"]
```
### 5. Restart Claude Desktop and start the conversation
```
You: Open CCS demodataV7.nfdb and list all fluids
Claude: [Calling pvtsim_open_file → pvtsim_list_fluids] Found 18 fluids…
You: Perform PT flash for fluid 1 at 50 bara and 10°C using Span-Wagner EOS
Claude: [Calling pvtsim_run_flash_saved_fluid] Calculation completed, vapor fraction 0.32……
```
---
## Configuration Instructions
| Variable Name | Required | Default Value | Description |
|--------|------|--------|------|
| `PVTSIM_PATH` | No* | `C:\Program Files\Calsep\PVTsim Nova CCS 7` | PVTsim installation directory |
\* Must be set if the installation path differs from the default value.
The Python side starts the C# Bridge using `subprocess` and reuses the built assembly with `dotnet run --no-build`. If C# code is modified, re-execute `dotnet build -c Debug`.
---
## MCP Tool List
There are **81 tools**, divided into 6 categories.
### Fluid Database Reading (9 tools)
Directly read PVTsim `.nfdb` SQLite databases without launching the PVTsim engine.
| Tool | Description | Key Parameters |
|------|------|---------|
| `pvtsim_open_file` | Open `.nfdb` fluid database | `file_path` |
| `pvtsim_list_fluids` | List all fluids | — |
| `pvtsim_get_fluid_info` | Get fluid detailed information | `fluid_id` |
| `pvtsim_get_composition` | Get fluid composition | `fluid_id` |
| `pvtsim_get_eos_parameters` | Get EoS parameters | `fluid_id`, `eos_type` (PR/SRK) |
| `pvtsim_get_pvt_data` | Get PVT experimental data | `fluid_id` |
| `pvtsim_get_reservoir_data` | Get reservoir conditions | `fluid_id` |
| `pvtsim_export_fluid_json` | Export complete fluid as JSON | `fluid_id` |
| `pvtsim_set_composition` | Modify fluid composition | `fluid_id`, `components[]` |
### Flash Calculation (10 tools)
Call the PVTsim Fortran engine for rigorous phase behavior flash calculations.
| Tool | Description | Fluid Source |
|------|------|---------|
| `pvtsim_run_flash` | Experimental Flash (old interface) | `.nfdb` |
| `pvtsim_run_flash_saved_fluid` | Saved fluid Flash | `.nfdb` |
| `pvtsim_run_flash_fluid_export` | PVTsim JSON fluid Flash | JSON export |
| `pvtsim_run_flash_pt_from_components` | PT Flash (single point) | Components |
| `pvtsim_run_pt_flash_from_components` | PT Flash (multi-point) | Components |
| `pvtsim_run_flash_from_components` | 13 modes Flash (relaxed input) | Components |
| `pvtsim_run_flash13_from_components` | 13 modes strict Flash | Components |
| `pvtsim_run_saturation_point_from_components` | Saturation point calculation | Components |
| `pvtsim_probe_flash_eos_official_paths_from_components` | EoS path diagnostic probe | Components |
| `pvtsim_export_pt_flash_from_components` | PT Flash + export JSON/CSV | Components |
### Phase Envelope Calculation (8 tools)
| Tool | Description | Fluid Source |
|------|------|---------|
| `pvtsim_run_phase_envelope` | Old phase envelope | `.nfdb` |
| `pvtsim_run_phase_envelope_saved_fluid` | Saved fluid phase envelope | `.nfdb` |
| `pvtsim_run_phase_envelope_fluid_export` | JSON fluid export phase envelope | JSON |
| `pvtsim_run_phase_envelope_from_components` | By components | Components |
| `pvtsim_run_phase_envelopes` | Batch calculation | `.nfdb` |
| `pvtsim_export_phase_envelope_from_components` | Phase envelope export (JSON/CSV/SVG) | Components |
| `pvtsim_export_phase_envelope_saved_fluid` | Phase envelope export (saved fluid) | `.nfdb` |
| `pvtsim_export_phase_envelope_fluid_export` | Phase envelope export (JSON fluid) | JSON |
### PVT Reservoir Experiment Calculation (48 tools)
Call the PVTsim Fortran engine for PVT reservoir experiments. Each experiment provides three fluid sources, with 16 experiments × 3 = 48 tools:
- `_saved_fluid` — Load saved fluid from `.nfdb` database
- `_fluid_export` — Load from PVTsim JSON fluid export file
- `_from_components` — Directly input components and proportions in the conversation (no `.nfdb` file needed)
| Experiment | Tool Prefix | Description | Status |
|------|---------|------|------|
| CriticalPoint | `pvtsim_run_critical_point_*` | Critical point calculation (Tc, Pc, Vc) | ✅ |
| Viscosity | `pvtsim_run_viscosity_*` | Isothermal viscosity experiment | ✅ |
| CME | `pvtsim_run_cme_*` | Constant volume expansion (oil phase) | ✅ |
| CME Dry Gas | `pvtsim_run_constant_mass_expansion_dry_gas_*` | Constant volume expansion (dry gas) | ✅† |
| Wax | `pvtsim_run_wax_*` | Wax precipitation (WAT/WPT) | ✅ |
| SeparatorTest | `pvtsim_run_separator_test_*` | Separator test | ✅† |
| CVD | `pvtsim_run_cvd_*` | Constant volume depletion | ⚠️ |
| DD | `pvtsim_run_differential_depletion_*` | Differential depletion | ⚠️ |
| MMP | `pvtsim_run_mmp_*` | Minimum miscibility pressure | ⚠️ |
| Swelling | `pvtsim_run_swelling_*` | Swelling experiment | ⚠️ |
| Pxy | `pvtsim_run_pxy_*` | Pxy phase diagram | ⚠️ |
| Txy | `pvtsim_run_txy_*` | Txy phase diagram | ⚠️ |
| PhaseMapping | `pvtsim_run_phase_mapping_*` | Phase mapping | ⚠️ |
| Hydrate | `pvtsim_run_hydrate_*` | Hydrate | ⚠️ |
| SaturateWithCO2 | `pvtsim_run_saturate_with_co2_*` | CO₂ saturation | ⚠️ |
| Scale | `pvtsim_run_scale_*` | Scaling trend | ⚠️ |
† Adapter works normally, but returns domain errors for oil phase fluids in CCS demodata (requires dry gas or two-phase separation conditions).
⚠️ Due to PVTsim headless mode API limitations, Pxy/Txy can be circumvented using the Excel reading tools below.
### Data Export (4 tools)
| Tool | Description | Output Format |
|------|------|---------|
| `pvtsim_export_flash13_from_components` | Flash13 result export | JSON + CSV |
| `pvtsim_export_fluid_data_saved_fluid` | Fluid data export (PVTsim JSON format) | PVTsim JSON |
| `pvtsim_export_eclipse_blackoil_saved_fluid` | Eclipse BlackOil PVT table export | Eclipse .inc |
| `pvtsim_export_eclipse_blackoil_fluid_export` | Eclipse BlackOil PVT table export | Eclipse .inc |
### GUI Excel Reading (2 tools)
Parse PVTsim GUI-exported Excel files. First, run experiments in PVTsim GUI and export `.xlsx`, then read as JSON using these tools.
| Tool | Description | Input |
|------|------|------|
| `pvtsim_read_pxy_excel` | Read Pxy phase diagram Excel (Dew/Bubble point table) | `file_path` |
| `pvtsim_read_txy_excel` | Read Txy phase diagram Excel (Dew/Bubble point table) | `file_path` |
---
## Supported EOS Models
There are **9** EOS models:
| Identifier | Alias | Description |
|------|------|------|
| `SpanWagner` | `Span-Wagner` | CO₂-specific reference equation (Span & Wagner 1996) |
| `GERG2008` | `GERG-2008` | GERG-2008 multi-component reference equation (natural gas) |
| `Leachman` | — | Hydrogen-specific reference equation (Leachman 2007) |
| `SrkPeneloux` | `SRK Peneloux` | Soave-Redlich-Kwong + Peneloux volume correction |
| `SrkPenelouxTemperatureDependent` | `SRK Peneloux (T)` | SRK-Peneloux + temperature-dependent α function |
| `PengRobinson76Peneloux` | `PR Peneloux` | Peng-Robinson 1976 + Peneloux correction |
| `PengRobinson76PenelouxTemperatureDependent` | `PR Peneloux (T)` | PR76-Peneloux + temperature-dependent α function |
| `PengRobinson78Peneloux` | `PR 78 Peneloux` | Peng-Robinson 1978 + Peneloux correction |
| `PengRobinson78PenelouxTemperatureDependent` | `PR 78 Peneloux (T)` | PR78-Peneloux + temperature-dependent α function |
## Supported Flash Modes
There are **13** GUI Flash modes:
| Identifier | Alias | Required Input Fields |
|------|------|-------------|
| `PressureTemperatureNonAqueous` | `PT non-aqueous` | `pressure_bara`, `temperature_c` |
| `PressureTemperature` | `PT aqueous` | `pressure_bara`, `temperature_c` |
| `PressureTemperatureMultiPhase` | `PT multi phase` | `pressure_bara`, `temperature_c` |
| `PressureTemperatureMultiPhaseSolids` | `PT multi phase w/solids` | `pressure_bara`, `temperature_c` |
| `PressureEnthalpy` | `PH` | `pressure_bara`, `enthalpy_mass_j_per_kg` |
| `PressureEntropy` | `PS` | `pressure_bara`, `entropy_mass_j_per_kg_c` |
| `EnergyVolumeMolar` | `UV` | `internal_energy_molar_j_per_mol`, `molar_volume_cm3_per_mol` |
| `EnthalpyEntropy` | `HS` | `enthalpy_mass_j_per_kg`, `entropy_mass_j_per_kg_c` |
| `VolumeTemperature` | `VT` | `molar_volume_cm3_per_mol`, `temperature_c` |
| `PressureBeta` | `P-beta` | `pressure_bara`, `beta` |
| `TemperatureBeta` | `T-beta` | `temperature_c`, `beta` |
| `FactorsK` | `K-factor` | `k_factors[]` (one value per component) |
| `SplitFactor` | `Split-factor` | `split_factors[]` (one value per component) |
## Usage Examples
### Example 1: Open Fluid Database and View Composition
```
You: Open C:\Program Files\Calsep\PVTsim Nova CCS 7\CCS demodataV7.nfdb
Claude: [invoke pvtsim_open_file]
Opened database with 18 fluids.
Fluid 1: "Gas Condensate 1" EOS: PR Peneloux
Fluid 2: "Gas Condensate 2" EOS: SRK Peneloux
...
You: View composition of Fluid 1
Claude: [invoke pvtsim_get_composition]
N₂: 0.35 mol%
CO₂: 1.25 mol%
C₁: 78.50 mol%
C₂: 10.20 mol%
...
```
### Example 2: PT Flash (Construct Fluid from Components)
```
You: Perform PT Flash with components: C₁=0.8, C₂=0.1, C₃=0.05, nC₄=0.03, nC₅=0.02
Conditions: P=200 bara, T=80°C
EOS: PengRobinson76Peneloux
Claude: [invoke pvtsim_run_flash13_from_components]
Flash calculation completed
State: Single-phase gas
Temperature: 80.0000 °C
Pressure: 202.6500 bar
Z-factor: 0.8234
Density: 0.1823 g/cm³
Enthalpy: -2.456e+03 J/kg
Entropy: -3.721 J/(kg·K)
Viscosity: 0.0234 cP
```
### Example 3: PH Flash (Saved Fluid)
```
You: Perform PH flash on Fluid 1 in PureCO2.nfdb at P=20 bara, H=1000 J/kg
EOS: GERG2008
Claude: [invoke pvtsim_run_flash_saved_fluid]
flash_mode=PressureEnthalpy, requested_eos=GERG2008
allow_saved_fluid_eos=true
PH Flash converged
Temperature: 101.856 °C
Vapor fraction: 0.85
Liquid fraction: 0.15
...
```
### Example 4: Phase Envelope + Export SVG
```
You: Calculate phase envelope of pure CO₂ with Span-Wagner EOS, export SVG
Claude: [invoke pvtsim_export_phase_envelope_from_components]
components: [{short_name: "CO2", amount: 1.0}]
eos: "SpanWagner"
Phase envelope calculation completed
Critical point: T=30.978 °C, P=73.7734 bara
Total points: 50
Files exported:
outputs/phase_envelope/phase_envelope.json
outputs/phase_envelope/phase_envelope.csv
outputs/phase_envelope/phase_envelope.svg
```
### Example 5: PVT Reservoir Experiment (CME, Load Fluid from .nfdb)
```
You: Perform CME experiment on Fluid 2 in CCS demodataV7.nfdb
Pressure steps: [200, 180, 160, 140, 120] bara
Temperature: 10°C
Claude: [invoke pvtsim_run_cme_saved_fluid]
fluid_id=2, pressure_steps=[200,180,160,140,120], temperature_c=10
allow_saved_fluid_eos=true, viscosity_model=CSP
CME experiment completed
Saturation pressure: 185.2 bara
Steps: 5
Output for each step: Bo, Rs, density, viscosity, Z-factor, ...
```
### Example 6: PVT Reservoir Experiment (Direct Component Input, No .nfdb)
```
You: Perform CME experiment with components: C1=0.65, C2=0.08, C3=0.05, nC4=0.04, nC5=0.03, nC6=0.02, C7+=0.13
Pressure steps: [200, 180, 160, 140, 120] bara
Temperature: 90°C
EOS: PengRobinson76Peneloux
Claude: [invoke pvtsim_run_cme_from_components]
components=[{short_name:"C1", amount:0.65}, ...], eos="PengRobinson76Peneloux"
pressure_steps=[200,180,160,140,120], temperature_c=90
CME experiment completed
Saturation pressure: 185.2 bara
Steps: 5
Output for each step: Bo, Rs, density, viscosity, Z-factor, ...
```
### Example 7: Read PVTsim GUI Exported Pxy/Txy Excel
First, run Pxy experiment with PVTsim GUI and export to Excel, then read with MCP:
```
You: (Run Pxy experiment with PVTsim GUI, export to Pxy-test.xlsx)
You: Read Pxy data from e:\toolbox\pvtsim-mcp\Pxy-test.xlsx
Claude: [invoke pvtsim_read_pxy_excel]
Fluid: CO2+C1
EOS: SRK Peneloux
Fixed temperature: 20.00 °C
Dew point table: 22 points (0% → 13.86%, pressure 57.6 → 81.8 bara)
Bubble point table: 20 points (0% → 13.86%, pressure 57.6 → 81.8 bara)
Both curves meet at 13.86% (near azeotrope)
```
More examples can be found in [`examples/validate_co2_span.py`](examples/validate_co2_span.py) and [`examples/validate_pvt_experiments.py`](examples/validate_pvt_experiments.py).
## Project Structure
```
pvtsim-mcp/
├── README.md
├── LICENSE # MIT
├── DESIGN.md # Design documentation
├── pyproject.toml # Python package configuration
│
├── src/
│ └── pvtsim_mcp/ # Python MCP server
│ ├── server.py # MCP Server entry point + 81 tool definitions
│ ├── bridge.py # C# Bridge subprocess encapsulation
│ ├── nfdb_reader.py # .nfdb SQLite direct reading
│ ├── exporters.py # Phase envelope export (JSON/CSV/SVG)
│ ├── flash_exporters.py # Flash result export (JSON/CSV)
│ └── pxy_txy_reader.py # PVTsim GUI exported Pxy/Txy Excel parsing
│
├── bridge/ # C# .NET 8.0 Bridge
│ ├── PVTsimBridge.csproj # Project file
│ ├── Program.cs # Entry point + command dispatch
│ ├── PvtSimulationAdapterBase.cs # Adapter base class
│ ├── FlashFluidAdapter.cs # Flash adapter
│ ├── PhaseEnvelopeAdapter.cs # Phase envelope adapter
│ ├── PvtExperimentsAdapter.cs # PVT reservoir experiment adapter (16 experiments)
│ └── FluidExportAdapter.cs # Simulator format export adapter
│
├── tools/
│ └── AssemblyInspector/ # Development utility: PVTsim assembly reflection inspection
│
├── tests/ # Test suite (71 tests)
│ ├── _helpers.py
│ ├── test_nfdb_reader.py
│ ├── test_pxy_txy_reader.py
│ ├── test_server_fluid_tools.py
│ ├── test_server_excel_tools.py
│ └── test_server_phase_envelope_tool.py
│
├── .github/workflows/ci.yml # CI: build bridge + run tests
│
└── examples/
├── validate_co2_span.py # CO2-Span flash + envelope validation
└── validate_pvt_experiments.py # PVT experiment adapter end-to-end validation
```
Run tests:
```bash
pip install pytest openpyxl
python -m pytest tests/ -v
```
## Frequently Asked Questions
### Q1: Error "Foundational.Simulations.dll not found" on startup
The `PVTSIM_PATH` environment variable is not set or points to an incorrect directory. Ensure that the directory contains `Foundational.Simulations.dll` and other assemblies.
### Q2: C# Bridge unresponsive after startup
Rebuild the C# code after first use or modification:
```powershell
cd bridge
dotnet build -c Debug
```
### Q3: Flash results inconsistent with GUI
Check if `requested_eos` matches the actual EOS of the fluid. If not, set `allow_saved_fluid_eos=true` or `allow_exported_fluid_eos=true` explicitly.
### Q4: Phase Envelope returns 0 points
Possible causes: EOS does not match fluid, fluid composition is abnormal (e.g., single component out of EOS range). Check the `diagnostics` field for detailed information.
### Q5: Some PVT experiment tools return "BLOCKED" error
CVD, DD, MMP, Swelling, Pxy, Txy, PhaseMapping, Hydrate, SaturateWithCO2, Scale, EclipseBlackOil are not available in headless mode without GUI. Pxy/Txy can be read from GUI-exported Excel as a workaround using `pvtsim_read_pxy_excel` / `pvtsim_read_txy_excel`.
### Q6: Support for Linux/macOS?
Not supported. PVTsim Nova CCS runs only on Windows, and the Bridge can only work on Windows.
## License
[MIT License](LICENSE)
PVTsim is a trademark of Calsep A/S. This project has no official affiliation with Calsep and does not distribute any binary files of PVTsim. Purchase and install a legitimate PVTsim license before using.
