Skip to main content

pyrestoolbox-mcp

A Model Context Protocol server that gives AI agents (Claude Code, Claude Desktop, Cursor, VS Code Copilot, any MCP host) the whole pyrestoolbox reservoir engineering library: gas, oil and brine PVT, VLP/IPR and nodal analysis, chokes and liquid loading, deliverability tests, gas pipelines, decline curves, material balance, capacitance-resistance models, simulator tables and more.

Requires Python 3.10 or later; installs pyrestoolbox 3.10.1 or later and the official mcp SDK (1.22 or later, 1.x and 2.x both supported).

Set up

With uv installed there is nothing to install first; uvx fetches and caches the server.

Claude Code:

claude mcp add pyrestoolbox -- uvx pyrestoolbox-mcp

Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "pyrestoolbox": {"command": "uvx", "args": ["pyrestoolbox-mcp"]}
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "pyrestoolbox": {"command": "uvx", "args": ["pyrestoolbox-mcp"]}
  }
}

Without uv: pip install pyrestoolbox-mcp, then use pyrestoolbox-mcp as the command with no arguments. Desktop apps launched from a dock or start menu often do not see your shell's PATH; if the host reports that it cannot start the server, give the full path to uvx or pyrestoolbox-mcp (which uvx, or where uvx on Windows).

To pin the version for repeatable numbers: uvx pyrestoolbox-mcp@0.1.0 and, if the library must stay fixed too, uvx --with pyrestoolbox==3.10.1 pyrestoolbox-mcp.

What the agent gets

A small set of tools that reach all 120-odd public functions, instead of one tool per function:

Tool Purpose
search(query) Engineering task in plain words ("liquid loading", "hydrate inhibitor dose", "gas in place") to the matching functions, best first
describe(name) Signature and full docstring, with units, for module.function
call(name, arguments) Run any public function with keyword arguments
read_docs(topic) A module's full documentation with worked examples; index maps tasks to functions
list_functions(module?) Module map, or the functions of one module
recommend_methods(...) Which correlations suit a fluid and well, with rationale
co2_brine_props(...) CO2-saturated brine in one call (Spycher-Pruess)
sw_brine_props(...) Gas-saturated brine for CH4/CO2/H2S/N2/H2/He mixtures (Soreide-Whitson)
fit_and_forecast(...) Fit a decline curve and forecast with EUR in one call

The same documentation is also served as MCP resources (docs://gas, docs://index, ...).

A typical exchange: the agent calls search("flowing bottomhole pressure"), gets nodal.fbhp, calls describe("nodal.fbhp"), then

call("nodal.fbhp", {"thp": 500, "well_type": "gas", "qg_mscfd": 5000,
                    "completion": {"tid": 2.441, "length": 10000, "tht": 100, "bht": 200}})

and gets {"result": 935.8, "engine": {"pyrestoolbox": "3.10.1", "rust": true}}. Every result names the library version and whether the compiled Rust path or pure Python produced it.

Behaviour an agent can rely on:

  • Errors are readable. A bad input returns the library's own message, e.g. Invalid zmethod: 'FOO'. Valid options: ['DAK', 'HY', 'BNS'] or gas_z() missing 2 required positional arguments: 'sg' and 'degf', so the agent corrects itself in one round trip.
  • Caveats travel with numbers. Library warnings (correlation range, extrapolation) come back in a notes list on the result instead of disappearing into a server log.
  • Units. Oilfield by default (psia, deg F, ft, mD, cP); "metric": true switches to Eclipse METRIC (barsa, deg C, m). Parameter names keep their oilfield spelling, so degf takes deg C under metric. Docstrings write units as (deg F | deg C), field first. Gas rates are Mscf/d (sm3/d metric); standard conditions are 60 deg F and 14.696 psia.
  • Objects as JSON. Functions that take a Completion, Reservoir, GasPVT, OilPVT, a decline result or a module.function name accept them as JSON objects of their constructor keywords, as in the completion above.
  • Results are JSON. Arrays become lists, tables become {columns, records}, non-finite numbers become null.

Remote deployment

pyrestoolbox-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Serves the MCP endpoint at /mcp, stateless, so no session affinity is needed behind a load balancer. A Dockerfile is included (runs as a non-root user, pins the library version). The server has no authentication of its own: put a gateway in front of it.

One calculation runs at a time per process (the library's warning capture is process-global); scale with more processes or replicas.

Safety

Every tool is a pure calculation, annotated read-only, idempotent and closed-world, so hosts can auto-approve them.

  • No file access by default. A few simtools functions write Eclipse include files (export=True) or read simulator decks and print files. The server refuses those arguments and functions unless started with --allow-file-io, which is meant for local use only. Tables always come back in the result.
  • Bounded results. A result over 500,000 characters of JSON is refused with a message asking for fewer rows or points; change the limit with --max-result-chars.
  • Public API only. call reaches public functions of the library's calculation modules; private names, classes and anything outside the library are rejected.

Tests

From the repository root, with an mcp SDK installed:

PYTHONPATH=$PWD:$PWD/mcp python -m pytest mcp/tests/ -q

Licence

GPL-3.0-or-later, as for pyrestoolbox.

Metadata

Release files for pyrestoolbox-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyrestoolbox-mcp 0.1.0
File Size Uploaded Provenance Actions
pyrestoolbox_mcp-0.1.0.tar.gz 34.7 kB With provenance Details for pyrestoolbox_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyrestoolbox-mcp 0.1.0
File Interpreter ABI Platform Actions
pyrestoolbox_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for pyrestoolbox_mcp-0.1.0-py3-none-any.whl

Total release size: 63.9 kB

Release files / pyrestoolbox_mcp-0.1.0.tar.gz

Download URL pyrestoolbox_mcp-0.1.0.tar.gz
Size 34.7 kB
Tags Source
SHA-256 checksum
How to use checksums
2b61f6ca2d66774d44e302ddc09ef8506153ca90ec4344cfe6eea33abbb7dacb
BLAKE2b-256 checksum
How to use checksums
ed3a1f94fffbaf41a2ddadbeb529f090fa1972349797f8bb1163b9d380e04fe4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / pyrestoolbox_mcp-0.1.0-py3-none-any.whl

Download URL pyrestoolbox_mcp-0.1.0-py3-none-any.whl
Size 29.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ede4926eecc79aa85c28425e2511cd8eefde56069db317414a8b53e29d0f8bbb
BLAKE2b-256 checksum
How to use checksums
bc33a22098cc90e3d50928fa1d3965fb89c3ad17d495a15bc67654c61046e9d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for pyrestoolbox-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pyrestoolbox_mcp-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page