A production-ready Model Context Protocol (MCP) server that gives AI agents like Claude access to the comprehensive reservoir engineering library pyResToolbox. Now Claude can perform sophisticated PVT calculations, well performance analysis, and reservoir simulation tasks through natural conversation.

---

---

What is This?

This MCP server bridges the gap between AI assistants and petroleum engineering workflows. Instead of manually calculating reservoir properties or writing complex scripts, you can simply ask Claude:

"Calculate the bubble point pressure for API 35° oil at 180°F with solution GOR of 800 scf/stb and gas gravity 0.75 using the Valko-McCain correlation"

"Generate an IPR curve for my well with Pi=4000 psia, Pb=3500 psia, API 38°, 175°F, pay thickness 75 ft, permeability 150 mD"

"Create a black oil table for simulation with pressures from 500 to 5000 psia"

Claude will execute the calculations using industry-standard correlations and return accurate, formatted results.

Built On

• pyResToolbox by Mark Burgoyne - Comprehensive Python library for reservoir engineering calculations
• FastMCP - Modern Python framework for building MCP servers
• Model Context Protocol by Anthropic - Standard for AI-application integration

Key Features

• 108 Production-Ready Tools - All tools tested and validated
• Industry-Standard Correlations - Standing, Valko-McCain, Velarde, DAK, Beggs-Robinson, Corey, LET, and more
• Dual Unit Support - Field units (psia, °F, ft) and Metric units (barsa, °C, m)
• Array Support - Calculate properties at multiple pressures simultaneously
• Zero Configuration - Works out of the box with Claude Desktop
• GPL-3.0 Licensed - Free and open source

---

Quick Start

Installation

Prerequisites: Python 3.10+ (UV package manager recommended but optional)

# 1. Clone the repository
git clone https://github.com/gabrielserrao/pyrestoolbox-mcp.git
cd pyrestoolbox-mcp

# 2. Install UV (optional but 10-100x faster than pip)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Setup and test
make uv-install    # Creates venv and installs dependencies
make uv-test       # Verifies all 108 tools work correctly

Connect to Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

IMPORTANT: Use absolute paths for both uv and the project directory. GUI applications like Claude Desktop don't inherit your terminal's PATH.

Find your UV path:

# macOS/Linux
which uv

# Windows (PowerShell)
Get-Command uv | Select-Object -ExpandProperty Source

Configuration:

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "/absolute/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

Common UV paths:

• macOS/Linux: /Users/username/.local/bin/uv or /home/username/.local/bin/uv
• Windows: C:\Users\username\.cargo\bin\uv.exe

Example (macOS):

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "/Users/john/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/john/projects/pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

Example (Linux):

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "/home/john/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/home/john/projects/pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

Example (Windows):

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "C:\\Users\\john\\.cargo\\bin\\uv.exe",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\john\\projects\\pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

Restart Claude Desktop completely (Quit and reopen, not just close the window) and you're ready to go!

---

Add the AI Skill (Recommended)

The SKILL/ folder in this repository contains a pre-built skill that teaches your AI assistant exactly how to use all 108 tools — correct parameter names, valid method codes, validation constraints, and multi-step workflows.

What's included:

File	Purpose
SKILL/pyrestoolbox-mcp.skill	Ready-to-install skill bundle (zip format)
SKILL/SKILL.md	Skill definition with YAML front-matter trigger conditions
SKILL/tools-reference.md	Complete parameter reference for all 108 tools

Installation (Claude Code):

Copy the skill file to your Claude skills directory:

cp SKILL/SKILL.md ~/.claude/skills/pyrestoolbox-mcp.md

# Optional but recommended — full parameter reference
mkdir -p ~/.claude/skills/references
cp SKILL/tools-reference.md ~/.claude/skills/references/tools-reference.md

Once installed, the skill activates automatically when you ask about reservoir engineering calculations, PVT analysis, well performance, geomechanics, or any pyResToolbox topic.

What the skill teaches the AI:

• Exact parameter names (psd not pwf, sg not sg_g for gas tools, zmethod vs method)
• All valid enum strings ("VALMC", "DAK", "SWOF", "COR", etc.)
• Required vs optional parameters for every tool
• Numeric validation constraints (API 0–100, gas SG 0.5–2.0, Poisson's ratio 0–0.5)
• Common multi-step workflows (PVT analysis, well performance, simulation input, geomechanics drilling window)

---

Your First Query

Open Claude Desktop and try:

"What's the bubble point pressure for a 35° API oil at 180°F with 800 scf/stb solution GOR and 0.75 gas gravity?"

Claude will use the oil_bubble_point tool and return results like:

Bubble Point Pressure: 3,456.7 psia
Method: Valko-McCain (VALMC)
Inputs: API=35°, T=180°F, Rs=800 scf/stb, SG_gas=0.75

---

What Can You Do?

Oil PVT Analysis

• Calculate bubble point pressure (Standing, Valko-McCain, Velarde)
• Solution GOR, formation volume factor, viscosity, density, compressibility
• Generate comprehensive black oil tables for simulators

Gas PVT Analysis

• Z-factor calculations (DAK, Hall-Yarborough, WYW, BUR/Peng-Robinson EOS)
• Hydrogen-capable gas PVT via BUR method (SPE-229932-MS) - handles arbitrary mixtures including pure CO₂ and 30%+ H₂
• Critical properties with contaminants (CO₂, H₂S, N₂, H₂)
• Gas viscosity, density, compressibility, pseudopressure
• Formation volume factors, hydrate prediction, water content

Well Performance & IPR

• Oil and gas production rates (radial and linear flow)
• IPR curve generation for vertical and horizontal wells
• Vogel IPR for pressures below bubble point
• Sensitivity analysis for permeability, skin, reservoir pressure

Reservoir Simulation Support

• Relative permeability tables (SWOF, SGOF, SGWFN) with Corey, LET, and Jerauld curve families
• Rel perm fitting - fit lab data to any model family, or auto-select best fit
• LET physical feasibility checking
• PVDO/PVDG/PVTO black oil tables and PVTW water PVT generation
• VFPPROD/VFPINJ lift curve tables for ECLIPSE
• Van Everdingen & Hurst aquifer influence functions (AQUTAB)
• Rachford-Rice flash calculations for phase behavior

Nodal Analysis & VLP

• Four multiphase VLP correlations: Woldesemayat-Ghajar (WG), Hagedorn-Brown (HB), Gray, Beggs & Brill (BB)
• Multi-segment deviated and horizontal completions (not just vertical pipes)
• IPR curve generation (gas, oil, water wells)
• VLP outflow curves and operating point calculation
• Production and injection modes supported
• VFPPROD/VFPINJ table generation for ECLIPSE/Intersect simulators
• GasPVT and OilPVT wrapper classes for consistent fluid characterization

Decline Curve Analysis (DCA)

• Arps decline (exponential, hyperbolic, harmonic)
• Rate and cumulative production forecasting
• EUR estimation
• Duong tight/unconventional decline
• Production ratio analysis (WOR, GOR, WGR)

Material Balance

• P/Z gas material balance for OGIP estimation
• Havlena-Odeh oil material balance for OOIP estimation
• Cole plot diagnostics and regression

Geomechanics & Wellbore Stability (27 tools)

• Vertical/horizontal stress, pore pressure prediction (Eaton)
• Fracture gradient, breakdown pressure, mud weight window
• Borehole breakout, sand production, fault stability
• Elastic moduli, rock strength, compaction, thermal stress
• UCS from logs, stress polygon, critical drawdown

Brine Properties

• CH₄-saturated brine properties (density, viscosity, FVF, compressibility)
• CO₂-brine mutual solubility for sequestration studies
• Soreide-Whitson VLE for multi-gas brine systems (CO₂, H₂S, N₂, H₂) with Sechenov salting-out corrections
• IAPWS-IF97 freshwater density, Spivey/McCain salinity corrections
• Per-component solubility, water content, and thermodynamic properties from a single framework

Advanced Calculations

• Reservoir heterogeneity analysis (Lorenz coefficient, beta parameter)
• Layer permeability distributions
• Component library (critical properties for 100+ hydrocarbons)
• Sensitivity analysis (parameter sweeps, tornado plots)
• Method recommendation engine

Configuration & Help

• Query available calculation methods and correlations
• Access unit system documentation
• Get physical constants
• Comprehensive usage guides

---

Example Queries for Claude

Basic PVT Calculations

"Calculate Z-factor for gas with SG 0.7 at 3500 psia and 180°F using DAK method"

"What's the oil formation volume factor for 38° API oil at 3000 psia, 175°F with Rs=600?"

"Compare bubble point pressures using Standing, Valko-McCain, and Velarde for 35° API oil"

Well Performance Analysis

"Generate IPR curve for well: Pi=4000 psia, Pb=3500 psia, API 38, T=175°F,
 h=75 ft, k=150 mD, skin=-2, re=1500 ft, rw=0.5 ft"

"Calculate oil production rate at 2000 psia flowing pressure for the same well"

"Show me how permeability affects production - test 50, 100, 150, 200, 250 mD"

Simulation Preparation

"Generate a SWOF relative permeability table using Corey correlation with 25 rows,
 kromax=1.0, krwmax=0.25, swc=0.15, sorw=0.15, no=2.5, nw=1.5"

"Create aquifer influence functions for dimensionless radius 10.0"

"Generate black oil table from 500 to 5000 psia for 38° API oil at 175°F"

Reservoir Heterogeneity

"Convert Lorenz coefficient 0.5 to Dykstra-Parsons beta"

"Generate layered permeability distribution for Lorenz coefficient 0.6,
 10 layers, average permeability 100 mD"

Multi-Step Workflows

"Perform complete reservoir analysis: Calculate bubble point, generate PVT table,
 create IPR curve, and analyze well performance for 38° API oil at 175°F with
 initial pressure 4000 psia"

"Design a well completion: Calculate optimal flowing pressure, generate IPR,
 and compare different skin factors"

"Evaluate a gas reservoir: Calculate critical properties, generate IPR,
 and compare different Z-factor methods"

Advanced Queries

Comprehensive PVT Workflows

"Generate a complete PVT table for API 38 oil at 175°F with gas gravity 0.68
 and solution GOR 750 scf/stb. Include pressures from 500 to 4000 psia and
 show Rs, Bo, viscosity, and density"

"Compare bubble point pressures using Standing, Valko-McCain, and Velarde
 correlations for API 35 oil at 180°F with GOR 800 scf/stb"

"Calculate PVT properties at multiple pressures: 1000, 2000, 3000, and 4000 psia
 for API 38 oil at 175°F"

Gas Analysis

"Calculate the critical properties (Tc and Pc) for a gas with specific gravity 0.7
 containing 2% CO2, 1% H2S, and 3% N2"

"Compare Z-factors using DAK, HY, and WYW methods for a gas at 3500 psia and 180°F"

"Calculate gas pseudopressure from 1000 to 3500 psia for a gas with SG 0.7 at 180°F"

Well Performance & IPR

"Generate an IPR curve for an oil well with reservoir pressure 4000 psia,
 bubble point 3500 psia, API 38 oil at 175°F. Well has 75 ft net pay,
 150 mD permeability, skin -2, drainage radius 1500 ft"

"What's the oil production rate at 2000 psia flowing pressure for a well with
 Pi=4000 psia, Pb=3500 psia, API 35, 180°F, 50 ft pay, 100 mD permeability?"

"Generate a Vogel IPR curve for pressures below bubble point for API 38 oil"

Sensitivity Analysis

"How does oil rate change with permeability? Test values from 50 to 250 mD"

"What's the impact of skin factor on production? Compare rates for skin values
 from -5 to +10"

"Analyze the effect of net pay thickness on production rate: test 25, 50, 75,
 and 100 ft"

"How does reservoir pressure depletion affect production? Calculate rates at
 4000, 3500, 3000, and 2500 psia"

Brine & CO₂ Sequestration

"Calculate brine properties for fresh water at 3000 psia and 175°F"

"What are the properties of saline brine (5% NaCl) at reservoir conditions:
 3000 psia, 175°F?"

"Calculate CO₂-brine mutual solubility at 3000 psia and 180°F with salinity
 50000 ppm"

"Compare brine properties with and without CO₂ saturation at sequestration conditions"

Reservoir Heterogeneity

"Convert Lorenz coefficient 0.5 to Dykstra-Parsons beta parameter"

"Calculate Lorenz coefficient from production logging data: flow fractions
 [0.45, 0.25, 0.15, 0.10, 0.05] and permeability fractions [0.30, 0.25, 0.20, 0.15, 0.10]"

"Generate a layered permeability distribution for Lorenz coefficient 0.5,
 10 layers, average permeability 100 mD"

Phase Behavior & Flash Calculations

"Solve Rachford-Rice flash for a mixture with compositions [0.5, 0.3, 0.2]
 and K-values [2.5, 1.8, 0.6]"

"Calculate vapor-liquid equilibrium for a three-component system"

Component Library

"What are the critical properties for methane?"

"Get critical temperature and pressure for ethane, propane, and butane"

"What's the molecular weight of n-heptane?"

Economic & Optimization

"What's the optimal flowing pressure to maximize production? Generate IPR
 and find the sweet spot"

"Compare production rates for stimulated (skin -2) vs damaged (skin +5) wells"

"Analyze the impact of reservoir pressure depletion on well performance over time"

Comparison & Benchmarking

"Compare Standing vs Valko-McCain vs Velarde bubble point correlations for the same oil"

"Compare DAK vs HY vs WYW Z-factor methods and their impact on gas rate calculations"

"Compare radial vs linear flow geometries for the same reservoir properties"

Educational Queries

"Explain what bubble point pressure means and calculate it for API 35 oil"

"What's the difference between solution GOR and producing GOR? Calculate both"

"How does gas gravity affect Z-factor? Show me calculations for different gravities"

"Explain Lorenz coefficient and calculate it for a heterogeneous reservoir"

Troubleshooting & Validation

"Validate my PVT data: bubble point 3500 psia, API 38, 175°F, GOR 750 scf/stb -
 does this make sense?"

"Check if my gas composition is realistic: SG 0.7 with 5% CO2, 3% H2S, 2% N2"

"Verify my well performance calculation: Are these rates reasonable for the
 given reservoir properties?"

Tips for Better Queries

1. Be Specific - Include all relevant parameters (API, temperature, pressure, etc.)
2. Specify Methods - Mention which correlation you want (VALMC, DAK, Corey, LET, etc.)
3. Include Units - Always specify units (psia, degF, mD, ft, etc.)
4. Ask for Comparisons - Request comparisons between methods or scenarios
5. Request Tables - Ask for tabulated results when you need multiple values
6. Follow-up Questions - Build on previous answers for complex workflows

---

Unit System

All calculations default to Field Units (US Oilfield) per industry standard. Set metric: true on any tool to use Metric Units (Eclipse METRIC conventions: barsa, °C, metres, sm³/d) with no manual conversion needed. ECLIPSE keyword output automatically switches to METRIC headers.

Property	Unit	Example
Pressure	psia	3000 psia
Temperature	°F	180°F
Permeability	mD	100 mD
Pay Thickness	ft	50 ft
Viscosity	cP	0.85 cP
Oil Rate	STB/day	542 STB/day
Gas Rate	MSCF/day	1250 MSCF/day
Oil Gravity	API° or SG	35° API
Gas Gravity	SG (air=1)	0.75
Solution GOR	scf/stb	800 scf/stb
Oil FVF	rb/stb	1.25 rb/stb
Gas FVF	rcf/scf	0.0045 rcf/scf
Compressibility	1/psi	1.2×10⁻⁵ 1/psi
Density	lb/ft³	42.5 lb/ft³

Access complete unit documentation anytime by asking Claude: "What units does pyRestToolbox use?"

---

Architecture

Project Structure

pyrestoolbox-mcp/
├── src/pyrestoolbox_mcp/
│   ├── server.py              # Main MCP server (FastMCP)
│   ├── config.py              # Server configuration & constants
│   ├── tools/                 # 108 MCP tool implementations
│   │   ├── oil_tools.py       # 19 oil PVT tools
│   │   ├── gas_tools.py       # 15 gas PVT tools
│   │   ├── inflow_tools.py    # 4 well performance tools
│   │   ├── simtools_tools.py  # 11 simulation support tools
│   │   ├── nodal_tools.py     # 6 nodal analysis / VLP tools
│   │   ├── dca_tools.py       # 9 decline curve analysis tools
│   │   ├── matbal_tools.py    # 2 material balance tools
│   │   ├── brine_tools.py     # 3 brine property tools
│   │   ├── geomech_tools.py   # 27 geomechanics tools
│   │   ├── layer_tools.py     # 5 heterogeneity tools
│   │   ├── recommend_tools.py # 4 method recommendation tools
│   │   ├── sensitivity_tools.py # 2 sensitivity analysis tools
│   │   ├── library_tools.py   # 1 component library tool
│   │   └── gas_fixes.py       # Upstream bug workarounds
│   ├── models/                # Pydantic validation models
│   │   ├── oil_models.py
│   │   ├── gas_models.py
│   │   ├── inflow_models.py
│   │   ├── simtools_models.py
│   │   ├── nodal_models.py
│   │   ├── dca_models.py
│   │   ├── matbal_models.py
│   │   ├── brine_models.py
│   │   ├── geomech_models.py
│   │   ├── layer_models.py
│   │   ├── recommend_models.py
│   │   ├── sensitivity_models.py
│   │   ├── library_models.py
│   │   └── common_models.py
│   └── resources/             # MCP configuration resources
│       └── config_resources.py
├── tests/                     # Test suite (52 pytest tests)
│   ├── test_oil_tools.py
│   ├── test_gas_tools.py
│   ├── test_geomech_tools.py
│   ├── test_simtools_new.py
│   ├── test_dca_tools.py
│   ├── test_brine_new.py
│   ├── test_nodal_tools.py
│   ├── test_matbal_tools.py
│   ├── test_recommend_tools.py
│   └── conftest.py
├── examples/                  # 12 comprehensive workflow examples
│   ├── basic_usage.py
│   ├── pvt_workflow.py
│   ├── gas_well_analysis.py
│   └── ...
├── server.py                  # Entry point
├── pyproject.toml            # UV/pip configuration
├── Makefile                  # Development commands
├── Dockerfile                # Docker deployment
└── docker-compose.yml        # Multi-transport deployment

How It Works

1. FastMCP Server - Handles MCP protocol communication (STDIO, HTTP, SSE)
2. Pydantic Models - Validate all inputs with descriptive error messages
3. Tool Layer - 108 functions wrapping pyrestoolbox calculations
4. pyRestToolbox - Performs actual reservoir engineering calculations
5. Type Conversion - Handles numpy/pandas/mpmath serialization for JSON

Tool Categories

Category	Count	Description
Oil PVT	19	Bubble point, Rs, Bo, viscosity, density, compressibility, black oil tables, PVT harmonization
Gas PVT	15	Z-factor, critical properties, Bg, viscosity, density, pseudopressure, hydrate prediction
Inflow	4	Oil/gas rates for radial/linear flow, IPR generation
Simulation	11	Relative permeability (Corey, LET, Jerauld), aquifer functions, flash, PVTW, black oil OG
Nodal / VLP	6	Flowing BHP, IPR/VLP curves, operating point, VFPPROD/VFPINJ tables
DCA	9	Arps decline, forecasting, EUR, Duong, ratio analysis
Material Balance	2	Gas P/Z and oil Havlena-Odeh OOIP/OGIP estimation
Brine	3	CH₄ and CO₂ saturated brine, Soreide-Whitson VLE
Geomechanics	27	Stress, pore pressure, fracture gradient, wellbore stability, sand production
Heterogeneity	5	Lorenz coefficient, beta conversion, layer distributions
Recommend	4	Method recommendation for gas, oil, VLP correlations
Sensitivity	2	Parameter sweeps and tornado sensitivity analysis
Library	1	Critical properties for 100+ components
Config	4	Units, methods, constants, help resources

---

pyResToolbox v3 Feature Coverage

This MCP server wraps pyResToolbox v3.0.4. The following table shows coverage of the major v3 features announced in the v3 release post:

v3 Feature	MCP Coverage	Details
Nodal Analysis - 4 VLP correlations (WG, HB, BB, Gray)	Full	flowing_bhp, ipr_curve, outflow_curve, operating_point tools with vlp_method parameter
Multi-segment deviated/horizontal completions	Full	WellSegment and Completion classes exposed via segments parameter in nodal tools
Production and injection modes	Full	injection flag on flowing_bhp; generate_vfp_inj_table for injection VLP
GasPVT and OilPVT wrapper classes	Full	Used internally by nodal tools for consistent fluid characterization
VFPPROD/VFPINJ table generation	Full	generate_vfp_prod_table, generate_vfp_inj_table tools
Multi-gas brine (Soreide-Whitson VLE)	Full	soreide_whitson_vle tool with CO₂, H₂S, N₂, H₂ mole fractions
IAPWS-IF97 freshwater density	Full	Handled internally by pyRestToolbox brine functions
Hydrogen-capable gas PVT (BUR/Peng-Robinson)	Full	gas_z_factor with method: BUR and h2 parameter; all gas tools support H₂
Metric unit support	Full	metric: true flag on all tools using Eclipse METRIC conventions
Simulation tables (PVDO/PVDG/PVTO/PVTW)	Full	generate_black_oil_table_og, generate_pvtw_table, black_oil_table tools
Rel perm fitting (Corey, LET, Jerauld)	Full	fit_relative_permeability, fit_relative_permeability_best, evaluate_jerauld, check_let_physical tools
Input validation & proper exceptions	Full	Pydantic models with field constraints on all 108 tools
DCA (Arps, Duong, ratio analysis)	Full	9 DCA tools covering all decline types
Material Balance (gas P/Z, oil Havlena-Odeh)	Full	gas_material_balance, oil_material_balance tools

Functions Not Exposed as MCP Tools

Some pyResToolbox functions are used internally but not exposed as standalone MCP tools:

Function	Reason
GasPVT / OilPVT classes	Used internally by nodal tools; individual PVT tools cover same calculations
darcy_gas	Low-level function; gas_rate_radial / gas_rate_linear provide higher-level access
oil_rs_bub / oil_rs_st / sg_st_gas	Specialized functions covered by oil_solution_gor tool
oil_harmonize_pb_rsb	Covered by oil_harmonize tool
gas_ponz2p	Inverse P/Z lookup; covered by gas_pressure_from_pz tool
brine_props / make_pvtw_table (brine)	Covered by calculate_brine_properties and generate_pvtw_table tools
validate_methods	Internal validation utility

---

Development

Running Tests

# Quick validation (all 108 tools)
make uv-test
# or
uv run python test_tools.py

# Full pytest suite
uv run pytest

# With coverage report
uv run pytest --cov=pyrestoolbox_mcp --cov-report=html

# Specific test modules
uv run pytest tests/test_oil_tools.py
uv run pytest tests/test_gas_tools.py

See TEST_RESULTS.md for complete validation report.

Running Examples

# Run all examples
make uv-examples

# Run specific example
make uv-example EXAMPLE=basic_usage.py
make uv-example EXAMPLE=gas_well_analysis.py

# Or manually
cd examples
uv run python basic_usage.py

Code Quality

# Format code
uv run black src/ tests/

# Lint
uv run ruff check src/ tests/

# Type checking (if mypy added)
uv run mypy src/

Docker Deployment

# Build image
make docker-build

# Run HTTP server (port 8000)
make docker-up-http

# Run SSE server (port 8001)
make docker-up-sse

# View logs
make docker-logs

# Stop services
make docker-down

See DOCKER.md for complete Docker documentation.

Adding New Tools

See CONTRIBUTING.md for detailed instructions. Quick overview:

1. Define Pydantic Model in src/pyrestoolbox_mcp/models/
2. Implement Tool Function in appropriate src/pyrestoolbox_mcp/tools/ file
3. Register Tool in the module's register_*_tools() function
4. Add Tests to test_tools.py and appropriate pytest file
5. Update Documentation in README and examples

---

Available Calculation Methods

Oil Correlations

Bubble Point Pressure

• VALMC - Valko & McCain (2003) - Recommended for most applications
• STAN - Standing (1947) - Classic correlation
• VELAR - Velarde (1997) - For specific regions

Solution GOR (Rs)

• VELAR - Velarde (1997)
• STAN - Standing (1947)
• VALMC - Valko & McCain (2003)

Formation Volume Factor (Bo)

• MCAIN - McCain et al. (1988) - Recommended
• STAN - Standing (1947)

Viscosity

• BR - Beggs & Robinson (1975)

Gas Correlations

Z-Factor

• DAK - Dranchuk & Abou-Kassem (1975) - Recommended for hydrocarbon gases
• HY - Hall & Yarborough (1973) - Fast, good for most conditions
• WYW - Wang, Ye & Wu (2021) - Reasonably fast
• BUR - Burgoyne, Nielsen & Stanko (2025) - Universal EOS-based correlation (5-component Peng-Robinson), best for high concentrations of non-hydrocarbons (CO₂, H₂S, N₂, H₂), including pure CO₂ and up to 30%+ hydrogen. Only method supporting H₂. (SPE-229932-MS)

Critical Properties

• PMC - Piper, McCain & Corredor (1993) - Recommended for hydrocarbon gases
• SUT - Sutton (1985)
• BUR - Burgoyne, Nielsen & Stanko (2025) - Universal correlation, best for gases with high non-hydrocarbon content (SPE-229932-MS)

Viscosity

• LGE - Lee, Gonzalez & Eakin (1966)

Relative Permeability

Curve Types

• COR - Corey (1954) - Power law, simple
• LET - Lomeland, Ebeltoft & Thomas (2005) - Flexible, complex shapes

Table Types

• SWOF - Water-oil saturation functions
• SGOF - Gas-oil saturation functions
• SGWFN - Gas-water saturation functions (3-phase)

---

Programmatic Usage

While this server is designed for Claude Desktop integration, you can also use it programmatically:

Python Client

import asyncio
from fastmcp.client import InMemoryTransport
from pyrestoolbox_mcp import mcp

async def calculate_pvt():
    transport = InMemoryTransport(mcp)

    async with transport.get_client() as client:
        # Calculate bubble point
        pb_result = await client.call_tool(
            "oil_bubble_point",
            {
                "api": 35.0,
                "degf": 180.0,
                "rsb": 800.0,
                "sg_g": 0.75,
                "method": "VALMC"
            }
        )
        pb = pb_result['value']
        print(f"Bubble Point: {pb:.2f} psia")

        # Calculate Rs at multiple pressures
        rs_result = await client.call_tool(
            "oil_solution_gor",
            {
                "api": 35.0,
                "degf": 180.0,
                "p": [1000, 2000, 3000, pb, 4000],
                "sg_g": 0.75,
                "pb": pb,
                "rsb": 800.0,
                "method": "VELAR"
            }
        )
        print(f"Rs values: {rs_result['value']}")

        # Access configuration resources
        methods = await client.read_resource("config://methods")
        print(f"Available methods:\n{methods.content}")

asyncio.run(calculate_pvt())

HTTP/SSE Transport

# Start HTTP server
uv run fastmcp run server.py --transport http --port 8000

# Or using Docker
docker-compose --profile http up -d

Then connect using any MCP client or HTTP client supporting the MCP protocol.

---

Troubleshooting

Installation Issues

"uv: command not found"

• Close and reopen terminal after installing UV
• Verify: uv --version
• Alternative: Use pip instead (pip install -e .)

"make: command not found" (Windows)

• Use manual commands from Makefile
• Or install Make for Windows via Chocolatey: choco install make

UV sync fails

• Clear cache: rm -rf .venv && make uv-install
• Check Python version: python --version (needs 3.10+)

Claude Desktop Integration

Error: "spawn uv ENOENT"

• This means Claude Desktop cannot find the uv command
• GUI applications don't inherit your terminal's PATH
• Solution: Use absolute path to uv in your config
• Find UV path: which uv (macOS/Linux) or Get-Command uv (Windows)
• Common locations:
  • macOS/Linux: /Users/username/.local/bin/uv or /home/username/.local/bin/uv
  • Windows: C:\Users\username\.cargo\bin\uv.exe

Claude doesn't see the tools

1. Use absolute paths for both uv command and project directory (no ~, use full path)
2. Verify paths are correct: ls /path/to/uv and ls /path/to/pyrestoolbox-mcp
3. Completely restart Claude Desktop (Quit, not just close window)
4. Check Claude Desktop logs:
   • macOS: ~/Library/Logs/Claude/
   • Windows: %APPDATA%\Claude\logs\
   • Linux: ~/.config/Claude/logs/
5. Test server manually: cd /path/to/pyrestoolbox-mcp && make uv-server

Tools fail with errors

• Verify all inputs use Field Units (psia, °F, ft, mD)
• Check parameter names match exactly (case-sensitive)
• Run validation: uv run python test_tools.py

Runtime Issues

Import errors

# Reinstall dependencies
make uv-install
# or
uv sync --force

Calculation errors

• Check units (must be psia, °F, etc.)
• Verify inputs are realistic (e.g., API 10-50, temperatures 60-300°F)
• Some correlations have valid ranges - try different methods
• Check pyResToolbox docs for correlation limits

Performance issues

• Array calculations are optimized via numpy
• For large datasets, consider batching requests
• Docker deployment adds minimal overhead

Getting Help

• Check INTERESTING_QUERIES.md for query examples
• Review examples/ directory for working code
• See CONTRIBUTING.md for development setup
• Open an issue for bugs or feature requests

---

Contributing

Contributions are welcome! This project follows the GPL-3.0 license of the upstream pyResToolbox library.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes (follow code style guidelines)
4. Test thoroughly (uv run pytest - all tests must pass)
5. Format code (uv run black src/ tests/)
6. Commit (git commit -m 'Add amazing feature')
7. Push (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Setup

git clone https://github.com/gabrielserrao/pyrestoolbox-mcp.git
cd pyrestoolbox-mcp
make uv-install
uv run python test_tools.py  # Verify all 108 tools pass

Guidelines

• Use type hints for all function parameters and return values
• Write Google-style docstrings
• Add tests for all new tools
• Follow existing code structure
• Update documentation

See CONTRIBUTING.md for detailed guidelines.

---

License

GNU General Public License v3.0 (GPL-3.0)

This MCP server is built on pyResToolbox, which is licensed under GPL-3.0. This project maintains full compliance with GPL-3.0 license terms.

Key Points:

• Free and open source software
• You may use, modify, and distribute under GPL-3.0 terms
• Any modifications must also be released under GPL-3.0
• No warranty provided (see LICENSE for details)
• Commercial use is permitted under GPL-3.0 terms

See LICENSE for complete license text.

---

Project Status

Aspect	Status	Details
Tests		100% tool coverage
Production	✅ Ready	All tools validated
Documentation	✅ Complete	README, examples, guides
License	GPL-3.0	Matches upstream
Python	3.10+	Type hints throughout
Framework	FastMCP 3.1+	Modern MCP implementation

See PRODUCTION_READY.md for detailed verification results.

Version History

v2.0.0 (2026-03-11) - Major upgrade to pyResToolbox 3.0.4

• 108 production-ready tools (up from 47)
• Dual unit support (Field + Metric)
• New modules: DCA, Material Balance, Nodal Analysis, Geomechanics, Sensitivity, Recommend
• FastMCP 3.x compatibility
• 52 pytest tests passing

v1.0.0 (2024-11-15) - Initial production release

• 47 production-ready tools
• Docker deployment support
• GPL-3.0 license compliance

See CHANGELOG.md for detailed version history.

---

Roadmap

Planned Features

• Web UI for HTTP transport with interactive forms
• Additional workflow examples for common tasks
• Performance benchmarking suite
• Extended simulation tools (grid processing, ECLIPSE utilities)
• Jupyter notebook integration with examples
• API documentation site (Sphinx/MkDocs)
• Rate limiting and authentication for HTTP deployments
• Prometheus metrics export

See open issues for full list of proposed features and known issues.

Upstream Integration

We're exploring opportunities to contribute improvements back to pyResToolbox, including:

• Standalone gas_grad2sg implementation (bug fix)
• Enhanced type hints
• Additional validation utilities

---

Related Projects

Core Dependencies

• pyResToolbox - Reservoir engineering library by Mark Burgoyne
• FastMCP - Python framework for MCP servers
• Model Context Protocol - MCP specification by Anthropic

Similar MCP Servers

• mcp-servers - Official MCP server examples
• awesome-mcp-servers - Curated list of MCP servers

Petroleum Engineering Tools

• PVTpy - PVT calculations in Python
• petbox - Petroleum engineering toolbox

---

Acknowledgments

This project wouldn't exist without:

• Mark Burgoyne - Creator of pyResToolbox, the foundation of this MCP server
• Marvin AI Team - Developers of FastMCP framework
• Anthropic - For Claude and the Model Context Protocol specification
• The reservoir engineering community - For developing and refining the correlations implemented in this project

Special thanks to all contributors who help improve this project!

---

Citation

If you use this MCP server in academic or commercial work, please cite the original pyResToolbox library:

@software{pyrestoolbox,
  author = {Burgoyne, Mark W.},
  title = {pyResToolbox: A Collection of Reservoir Engineering Utilities},
  url = {https://github.com/mwburgoyne/pyResToolbox},
  version = {3.0.4},
  year = {2025}
}

For this MCP server:

@software{pyrestoolbox_mcp,
  author = {Serrao, Gabriel},
  title = {pyResToolbox MCP Server: AI-Powered Reservoir Engineering Calculations},
  url = {https://github.com/gabrielserrao/pyrestoolbox-mcp},
  version = {2.0.0},
  year = {2026},
  note = {Built on pyResToolbox by Mark W. Burgoyne}
}

---

Support

Getting Help

For MCP server issues:

• Check Troubleshooting section
• Review examples/ directory
• Search existing issues
• Open a new issue

For calculation accuracy or pyResToolbox features:

• See pyResToolbox documentation
• Check pyResToolbox issues

For FastMCP framework:

• See FastMCP documentation

For Model Context Protocol:

• See MCP specification
• Join MCP Discord (if available)

Community

• Discussions: GitHub Discussions
• Issues: GitHub Issues
• Pull Requests: Contributing Guide

---

Support & Star

---