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']orgas_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
noteslist on the result instead of disappearing into a server log. - Units. Oilfield by default (psia, deg F, ft, mD, cP);
"metric": trueswitches to Eclipse METRIC (barsa, deg C, m). Parameter names keep their oilfield spelling, sodegftakes 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 amodule.functionname accept them as JSON objects of their constructor keywords, as in thecompletionabove. - 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
simtoolsfunctions 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.
callreaches 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.