MCP 服务器

pyResToolbox MCP Server

Enables AI assistants to perform petroleum engineering calculations including PVT analysis, well performance modeling, and reservoir simulation support using industry-standard correlations and field units.

README

pyResToolbox MCP Server

Bring Reservoir Engineering Calculations to AI

Power your AI assistants with industry-standard petroleum engineering calculations

Quick Start • Features • Examples • Documentation • Contributing

47 Production-Ready Tools | Field Units | Zero Configuration

PVT Analysis • Well Performance • Simulation Support • Brine Properties • Heterogeneity Analysis

</div>

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.

☕ Support This Project

If you find this project useful, consider buying me a coffee! Your support helps maintain and improve this open-source tool.

</div>

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

47 Production-Ready Tools - All tools tested and validated
Industry-Standard Correlations - Standing, Valko-McCain, Velarde, DAK, Beggs-Robinson, Corey, LET, and more
Field Units - Uses familiar oilfield units (psia, °F, STB/day, MSCF/day)
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 47 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

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

Replace /absolute/path/to/pyrestoolbox-mcp with your actual installation path.

Restart Claude Desktop 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

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, 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

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

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

Unit System

All calculations use Field Units (US Oilfield) per industry standard:

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/                 # 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

Development

Running Tests

# Quick validation (all 47 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:

Define Pydantic Model in src/pyrestoolbox_mcp/models/
Implement Tool Function in appropriate src/pyrestoolbox_mcp/tools/ file
Register Tool in the module's register_*_tools() function
Add Tests to test_tools.py and appropriate pytest file
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, most accurate
HY - Hall & Yarborough (1973) - Fast, good for most conditions
WYW - Wang, Ye & Wu (2021) - Latest, handles high pressure
BUR - Burrows (1981) - Special applications

Critical Properties

PMC - Piper, McCain & Corredor (1993) - Recommended
SUT - Sutton (1985)
BUR - Burrows (1981)

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

Claude doesn't see the tools

Verify absolute path in config (no ~, use full path)
Completely restart Claude Desktop (Quit, not just close window)
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/
- Windows: %APPDATA%\Claude\logs\
Test server manually: make uv-server
Ensure UV is in PATH (try which uv or where uv)

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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes (follow code style guidelines)
Test thoroughly (uv run python test_tools.py - all 47 must pass)
Format code (uv run black src/ tests/)
Commit (git commit -m 'Add amazing feature')
Push (git push origin feature/amazing-feature)
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 47 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 2.0+	Modern MCP implementation

See PRODUCTION_READY.md for detailed verification results.

Version History

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

47 production-ready tools
100% test coverage
Docker deployment support
Comprehensive documentation
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 = {2.x},
  year = {2024}
}

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 = {1.0.0},
  year = {2024},
  note = {Built on pyResToolbox by Mark W. Burgoyne}
}