๐ pyResToolbox MCP Server
Bring Reservoir Engineering Calculations to AI. Power your AI assistants with industry - standard petroleum engineering calculations.
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.

Key Information
| Property |
Details |
| Model Type |
A production - ready MCP server for AI agents |
| Training Data |
Not applicable |
Badges

Navigation
Quick Start โข Features โข Examples โข Documentation โข Contributing
Tools and Capabilities
47 Production - Ready Tools | Field Units | Zero Configuration
PVT Analysis โข Well Performance โข Simulation Support โข Brine Properties โข Heterogeneity Analysis
๐ Quick Start
Installation
Prerequisites: Python 3.10+ (UV package manager recommended but optional)
git clone https://github.com/gabrielserrao/pyrestoolbox-mcp.git
cd pyrestoolbox-mcp
curl -LsSf https://astral.sh/uv/install.sh | sh
make uv-install
make uv-test
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:
which uv
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!
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
โจ Features
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, Burrows)
- Critical properties with contaminants (COโ, HโS, Nโ, Hโ)
- Gas viscosity, density, compressibility, pseudopressure
- Formation volume factors
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)
- Corey and LET correlations
- Van Everdingen & Hurst aquifer influence functions (AQUTAB)
- Rachford - Rice flash calculations for phase behavior
Advanced Calculations
- Brine properties (methane and COโ saturated)
- COโ sequestration studies
- Reservoir heterogeneity analysis (Lorenz coefficient, beta parameter)
- Layer permeability distributions
- Component library (critical properties for 100+ hydrocarbons)
Configuration & Help
- Query available calculation methods and correlations
- Access unit system documentation
- Get physical constants
- Comprehensive usage guides
๐ป Usage Examples
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"
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"
๐ Documentation
Project Structure
pyrestoolbox-mcp/
โโโ src/pyrestoolbox_mcp/
โ โโโ server.py # Main MCP server (FastMCP)
โ โโโ config.py # Server configuration & constants
โ โโโ tools/ # 47 MCP tool implementations (~13,800 LOC)
โ โ โโโ oil_tools.py # 17 oil PVT tools
โ โ โโโ gas_tools.py # 11 gas PVT tools
โ โ โโโ inflow_tools.py # 4 well performance tools
โ โ โโโ simtools_tools.py # 3 simulation support tools
โ โ โโโ brine_tools.py # 2 brine property tools
โ โ โโโ layer_tools.py # 5 heterogeneity tools
โ โ โโโ library_tools.py # 1 component library tool
โ โโโ models/ # Pydantic validation models
โ โ โโโ oil_models.py
โ โ โโโ gas_models.py
โ โ โโโ inflow_models.py
โ โ โโโ simtools_models.py
โ โ โโโ brine_models.py
โ โ โโโ layer_models.py
โ โ โโโ library_models.py
โ โโโ resources/ # MCP configuration resources
โ โโโ config_resources.py
โโโ tests/ # Test suite (pytest + custom)
โ โโโ test_oil_tools.py
โ โโโ test_gas_tools.py
โ โโโ conftest.py
โโโ examples/ # 10 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
- FastMCP Server - Handles MCP protocol communication (STDIO, HTTP, SSE)
- Pydantic Models - Validate all inputs with descriptive error messages
- Tool Layer - 47 functions wrapping pyrestoolbox calculations
- pyRestToolbox - Performs actual reservoir engineering calculations
- Type Conversion - Handles numpy/pandas/mpmath serialization for JSON
Tool Categories
| Category |
Count |
Description |
| Oil PVT |
17 |
Bubble point, Rs, Bo, viscosity, density, compressibility, black oil tables |
| Gas PVT |
11 |
Z - factor, critical properties, Bg, viscosity, density, pseudopressure |
| Inflow |
4 |
Oil/gas rates for radial/linear flow, IPR generation |
| Simulation |
3 |
Relative permeability, aquifer functions, Rachford - Rice flash |
| Brine |
2 |
CHโ and COโ saturated brine properties |
| Heterogeneity |
5 |
Lorenz coefficient, beta conversion, layer distributions |
| Library |
1 |
Critical properties for 100+ components |
| Config |
4 |
Units, methods, constants, help resources |
๐ง Technical Details
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, best for high concentrations of non - hydrocarbons (COโ, HโS, Nโ, Hโ), including 100% COโ. 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)
๐ 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.