pyResToolbox

You run an MCP server that exposes the pyResToolbox reservoir engineering library to AI agents. This server lets you issue natural-language queries and receive calculated results such as PVT properties, IPR curves, relative permeability tables, and other reservoir calculations, all using industry-standard correlations and field units. It is designed to work out of the box with Claude Desktop, enabling seamless, conversational access to powerful petroleum engineering tools.

How to use

You connect to the MCP server using an MCP client (such as Claude Desktop) and run calculations by sending requests that describe the calculation you want. Start the local server, then configure your client to point at that server. Once connected, you can ask for bubble point pressures, Rs and Bo calculations, Z-factor evaluations, IPR curves, or full black oil tables, and receive structured results formatted for easy interpretation.

How to install

Prerequisites: Python 3.10 or newer.

1. Clone the MCP server repository.

2. Install UV for fast, parallel package execution (optional but strongly recommended). Run the installer script.

3. Set up the Python virtual environment and install dependencies, then validate the 47 tools. Use the provided Make targets to install and test.

Configuration and startup

To connect Claude Desktop, you expose a local MCP server via a standard stdio configuration. Use a Claude Desktop config entry that points to the UV command and the project directory to start the server.

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

Starting an HTTP transport (optional)

If you prefer serving over HTTP/SSE, start the HTTP transport after the MCP server is running. Use the recommended transport command to expose the server on a port.

uv run fastmcp run server.py --transport http --port 8000

What you can do with Claude

Ask Claude to perform PVT analyses, generate IPR curves, compute brine properties, or build relative permeability tables. Typical queries include requesting bubble point pressures with different correlations, generating black oil tables, or comparing Z-factor methods for a gas. Claude will execute the calculations using the embedded pyResToolbox library and return formatted results.

Notes and tips

• Use absolute paths for both the UV executable and the project directory in your client configuration. GUI apps don’t inherit your terminal PATH, so rely on explicit paths.

• Restart Claude Desktop completely after changes to the MCP configuration to ensure the client discovers the local server.

Troubleshooting and validation

• If Claude cannot find the MCP server, verify the path to UV and the project directory are correct, then restart Claude Desktop.

• If a tool returns unexpected results, confirm inputs use Field Units (psia, °F, ft, mD) and verify the parameter names exactly match expected tool inputs.

• For unit and calculation validation, run the built-in test suite to ensure all 47 tools pass in your environment.

Project structure overview

The server is built around a FastMCP-based Python implementation. Core components include the MCP server, tool wrappers for 47 reservoir engineering calculations, Pydantic models for input validation, and a modular organization for oil PVT, gas PVT, inflow, simulation, brine, layer heterogeneity, library access, and configuration utilities.