IPM-mcp

# IPM MCP An MCP Server for Petroleum Experts [IPM](https://www.petex.com/ipm-suite/) (Integrated Production Modelling) software. Enables AI assistants like Claude to operate the full IPM toolset—PROSPER, GAP, MBAL, PVTP, REVEAL, RESOLVE—via OpenServer .NET interface, allowing modelling, calibration, and end-to-end runs without leaving the conversation. [](#tests) [](LICENSE) [](https://www.python.org/) [](#prerequisites) > **Status:** Beta. The full toolset has been validated with real IPM 10 sample files (see [tests](#tests)). OpenServer PDF documentation discrepancies have been identified and workarounds implemented. This project is not affiliated with Petroleum Experts, see [disclaimer](#disclaimer). ## Project Significance Engineers manually build production models in the IPM graphical interface: PROSPER for well performance, GAP for network optimization, MBAL for material balance, PVTP for fluid properties, REVEAL for reservoir simulation, RESOLVE for integrated forecasting. Each model has hundreds of parameters; calibrating one parameter often requires adjusting multiple parameters across products. This MCP server exposes all six products as MCP tools. AI agents (or any MCP client) can: - **Open and modify real IPM models**—every operation goes through the real IPM OpenServer bridge. - **Run calculations**—PVT, IPR/VLP, system analysis, network solving, history matching, forecasting, laboratory studies, integrated forecasting. - **Read and write arbitrary tags**—additionally provides about 140 high-level convenience tools specifically handling IPM 10's hosted wrapper "gotchas". The goal is to support autonomous modelling workflows: e.g., "Build a gas lift well with this PVT configuration, run system analysis, and report the operating point"—can be executed directly as an agent prompt. ## Prerequisites - **Windows** (IPM only supports Windows) - **IPM 10**, installed and licensed (purchase from Petroleum Experts) - The installation directory must contain the .NET managed wrapper `PxServerManaged.dll` (bundled with IPM 10) - **Python 3.10 or higher** - **pythonnet** (`pip install pythonnet`)—Python ↔ .NET bridge - An MCP client (Claude Desktop, Cursor, or any MCP-compatible app) Older IPM versions (9, 8, 7) use 32-bit COM interfaces instead of .NET wrappers; this server is specifically designed for IPM 10. The product tag behaviors documented here are validated with real IPM 10 instance files. ## Installation ### Method A—Install from source (currently recommended) ```bash git clone https://github.com/stunner979/ipm-mcp.git cd ipm-mcp pip install -e . ``` ### Method B—Directly install from GitHub ```bash pip install git+https://github.com/stunner979/ipm-mcp.git ``` The `ipm-mcp` command-line script will be added to the PATH after installation. ## Configuration The server reads one environment variable: | Variable Name | Default Value | Purpose | |--------------|---------------|---------| | `IPM_INSTALL_DIR` | `Your_path\Petroleum Experts\IPM 10` | IPM installation directory (for finding `PxServerManaged.dll` and product `.exe`s) | If IPM is installed in a different location, set this variable: ```powershell setx IPM_INSTALL_DIR "Your_path\Petroleum Experts\IPM 10" ``` ### Register with MCP Client Add the server to the MCP client configuration. For **Claude Desktop**, edit `%APPDATA%\Claude\claude_desktop_config.json`: ```json { "mcpServers": { "ipm-mcp": { "command": "ipm-mcp", "env": { "IPM_INSTALL_DIR": "Your_path\\Petroleum Experts\\IPM 10" } } } } ``` This server uses the stdio MCP protocol, exposing only tools (no prompts, no resources). ## Quick Start The example script `examples/prosper_pvt_workflow.py` demonstrates a complete PROSPER PVT workflow—connecting to IPM, launching PROSPER, opening a sample project, reading PVT input, setting pressure-temperature ranges, running calculations, and reading results: ```bash python examples/prosper_pvt_workflow.py ``` Expected output (truncated): ``` [1/7] Connected to IPM OpenServer bridge. [2/7] PROSPER is running. [3/7] Opened: ...\T01_Basic_Oil_Well.Out [4/7] PVT input read: API = 37.000000000 Solution GOR = 800.000000000 Gas Gravity = 0.759999990 [5/7] PVT table range set (100-10000 psia, 60-300 F). [6/7] PVT calculation complete. [7/7] PVT results populated (1 rows). First row: Temperature = 60.000000000 Pressure = 100.000000000 Bubble Point = 2782.637939453 Oil FVF (Bo) = 1.013012767 Oil Viscosity = 6.279407024 Solution GOR (Rs) = 41.559024811 ``` Perform the same workflow with an MCP client (Claude Desktop): ``` > Launch PROSPER, open T01_Basic_Oil_Well.Out, and run PVT calculation, with pressure range 100-10000 psia and temperature range 60-300 F. Report bubble point pressure and oil viscosity at the first sample point. ``` ## Tool List **143 tools**, organized by IPM product. Each product module exposes high-level operations (open, calculate, read results), and additional universal `ipm_get_value` / `ipm_set_value` / `ipm_do_command` tools for reading/writing arbitrary tags or executing arbitrary commands. ### Connection Management (10 tools) | Tool | Purpose | |------|---------| | `ipm_connect` / `ipm_disconnect` | Open/close OpenServer bridge | | `ipm_status` | Report product running and readiness status | | `ipm_launch_product` / `ipm_ensure_product_running` | Launch product applications | | `ipm_set_units` | Switch unit systems (OilField, Norwegian S.I., etc.) | | `ipm_abort` | Terminate current calculation | | `ipm_get_value` / `ipm_set_value` / `ipm_do_command` | Read/write arbitrary tags or execute arbitrary commands | ### PROSPER—Well Performance (24 tools) Open/save/new, calculations (PVT, IPR, VLP, system, gradient, gas lift, ESP, PCP, jet pump, choke, WHP→BHP), PVT input/results access, system analysis results, well data, matching (VLP, gradient, pipe), GAP performance curve generation. Main tools: `prosper_open_file`, `prosper_calculate_pvt`, `prosper_set_pvt_input`, `prosper_get_pvt_results`, `prosper_calculate_system`, `prosper_get_system_results`, `prosper_calculate_esp`, `prosper_calculate_gas_lift_new`, `prosper_match_vlp`. ### GAP—Network Optimization (21 tools) Open/save/new, network solving (IPM 10 single-parameter signature), full forecasting (PREDINIT → PREDDOSTEP loop → PREDEND), scheduling and constraint management, equipment lists, passing well IPR from PROSPER, forecasting results reading. Main tools: `gap_open_file`, `gap_solve_network`, `gap_run_prediction`, `gap_get_equipment_list`, `gap_get_solver_results`, `gap_get_prediction_results`, `gap_set_constraint`, `gap_set_schedule`, `gap_transfer_prosper_ipr`, `gap_set_manifold_pressure`. ### MBAL—Material Balance (23 tools) Open/save/new, history matching simulation, forecasting (one-shot and step-wise runs), tank data (OOIP/OGIP/temperature/type), PVT input, forecasting results, well results, OOIP sensitivity analysis, forecasting well IPR setup. Main tools: `mbal_open_file`, `mbal_run_simulation`, `mbal_run_prediction`, `mbal_set_tank_data`, `mbal_set_pvt_input`, `mbal_get_prediction_results`, `mbal_sensitivity_ooip`, `mbal_start_prediction`, `mbal_next_step_prediction`. ### PVTP—Fluid Properties (14 tools) Open/save, black oil and laboratory study calculations (CCE, CVD, DIFF, SEP, PSAT, phase envelope, expansion, depletion, wax, hydrate, tube), flash, results table reading, component setup, composite calculation, separator calculation, saturation pressure, black oil export. Main tools: `pvtp_open_file`, `pvtp_calculate`, `pvtp_get_black_oil_results`, `pvtp_get_calc_results`, `pvtp_get_analysis`, `pvtp_set_stream_composition`, `pvtp_recombine`, `pvtp_saturation_pressure`. ### REVEAL—Reservoir Simulation (28 tools) Open/save/new, simulation control (initialize, run, step, stop, pause, restart), well results, average reservoir results, well/region enumeration, well control (rate/BHP/THP for producers and injectors), script data writing, simulation time tracking. Main tools: `reveal_open_file`, `reveal_initialize`, `reveal_one_step`, `reveal_get_well_results`, `reveal_get_avg_reservoir_results`, `reveal_get_well_names`, `reveal_set_well_control`, `reveal_set_injection_well`, `reveal_get_sim_time`. ### RESOLVE—Integrated Forecasting (23 tools) Open/save/new (`.rsl` project files, not `.rsa` archives), run integrated forecasting, step-wise control, scheduling management, module listing and linking, driver listing, broadcast saving, module loading. Main tools: `resolve_open_file`, `resolve_run`, `resolve_run_one_step`, `resolve_get_module_list`, `resolve_get_driver_list`, `resolve_get_schedule`, `resolve_set_schedule`, `resolve_create_module`, `resolve_link_items`, `resolve_load_module`. ## Tests The test suite `tests/test_workflows.py` performs end-to-end validation with IPM 10's bundled sample files, with each assertion reading actual calculation values from the real-time API. ```bash python -m pytest tests/test_workflows.py -v ``` 39 tests, all passed: ``` TestProsperWorkflow ........ 4 passed (PVT input re-read, PVT calculation, system calculation, sample opening) TestGapWorkflow ...... 6 passed (opening, equipment list, solving, forecasting info, running forecast, reading results) TestMbalWorkflow ...... 6 passed (opening, tank data, PVT tag, running simulation, forecasting input, running forecast) TestTagSignatures .... 4 passed (SOLVENETWORK/PREDDOSTEP single-parameter, RUNSIMULATION, SOL tag formatting) TestPvtpWorkflow ..... 5 passed (opening, fluid info, black oil calculation, results table, OPTIONS tag) TestRevealWorkflow ...... 6 passed (opening, initializing + stepping, Master tag, WellRes producer/injector, AveRes) TestResolveWorkflow ........ 8 passed (opening .rsl, module collection, filename/driver fallback, tag-based access, driver collection, scheduling start/stop, ModLink/Connection) ============================== 39 passed =============================== ``` The sample files referenced in the tests are located in `<IPM installation directory>\IPM Samples-10\`. If this folder is not in the default location, specify it with the `IPM_SAMPLES` environment variable: ```powershell setx IPM_SAMPLES "Your_path\IPM Samples-10" ``` Each product (PROSPER, GAP, MBAL, PVTP, REVEAL, RESOLVE) is automatically launched by the test fixtures; the entire test suite takes about one minute to run. ## IPM 10 OpenServer Known Gotchas The OpenServer PDF documentation is not fully synchronized with the IPM 10 managed wrapper. The codebase has hardcoded, validated tag/command strings; notable discrepancies are listed below: | PDF Documentation | Actual Availability | Description | |----------|-------------------|-------------| | `PROSPER.PVT.INPUT.MAXPRES` | `PROSPER.PVT.CALC.PRESMAX` | PVT table range is under `.CALC`, not `.INPUT` | | `MBAL.MB.PVT.INPUT.API` | `MBAL.MB.PVT.INPUT.OILGRAV` | Tag renamed in IPM 10 | | `MBAL.PREDINP.CALCTYPE = "RES_PRESS"` | `RESPRESS` (no underscore) | PDF spelling rejected | | `PVT.BLACKOIL_OIL[i]` | `PVT.CALC_BLACKOIL_OIL` (no index) | Black oil calculation doesn't need stream index | | `REVEAL.WellRes[{Well Results}][{W1}][0].Var` | `REVEAL.WellRes[0][1][0].Var` | IPM 10 tag syntax `{{}}` unavailable | | `REVEAL.Run[i].NX/NY/NZ/P/S/POR` | (not exposed) | Runtime tags removed from wrapper | | `RESOLVE.OpenFile("file.rsa")` | Use `.rsl` instead | `.rsa` is a compressed archive, needs decompression | | `RESOLVE.Schedule.EndDate.DateStr` | `RESOLVE.ScheduleList[0].EndDate.DateStr` | EndDate is on subscripted collection | Certain operations trigger IPM application crashes in error states—notably **`REVEAL.Stop()`**, which closes the application when invoked without a running simulation. The `reveal_initialize` tool only calls `Stop()` if initialization fails with error 5064 ("a simulation is running"). ## Project Structure ``` ipm-mcp/ ├── README.md ← Current file ├── LICENSE ← MIT ├── pyproject.toml ← Build + Dependencies + Command-line scripts ├── run_server.py ← stdio Launch Entry ├── src/ipm_mcp/ │ ├── server.py ← FastMCP Application + Tool Registration │ ├── ipm_client.py ← OpenServer .NET Wrapper (64-bit) │ └── tools/ │ ├── connection.py ← connect/status/launch/get/set/do_command │ ├── prosper.py ← PROSPER Well Performance Tool │ ├── gap.py ← GAP Network Optimization Tool │ ├── mbal.py ← MBAL Material Balance Tool │ ├── pvtp.py ← PVTP Fluid Property Tool │ ├── reveal.py ← REVEAL Reservoir Simulation Tool │ └── resolve.py ← RESOLVE Integrated Forecasting Tool ├── examples/ │ └── prosper_pvt_workflow.py ← End-to-end PROSPER PVT Example └── tests/ └── test_workflows.py ← 39 End-to-end Tests against IPM 10 Samples ``` --- ## Architecture ``` MCP Client (Claude Desktop, Cursor, etc.) │ │ stdio JSON-RPC ▼ ┌────────────────────┐ │ ipm-mcp server │ ← FastMCP, Registers 143 Tools └─────────┬──────────┘ │ │ Python Call ▼ ┌────────────────────┐ │ IPMClient │ ← Lightweight Wrapper, Asynchronous Polling │ (ipm_client.py) │ Error Code Translation └─────────┬──────────┘ │ │ pythonnet (clr) ▼ ┌────────────────────┐ │ PxServerManaged │ ← .NET Managed Wrapper │ .dll │ (Petex.IPM.PxServer.PxServer) └─────────┬──────────┘ │ │ COM Interop ▼ ┌────────────────────┐ │ IPM 10 Apps │ ← PROSPER.exe, GAP.exe, │ │ MBAL.exe, PvtP.exe, │ │ reveal.exe, Resolve.exe └────────────────────┘ ``` Long-running operations (PREDINIT, RUNSIMULATION, One_Step, Run) use `do_command_async`, polling `IsBusy` with exponential backoff and respecting a configurable timeout — so the MCP server will never block indefinitely due to a stuck computation. --- ## Contributing Feel free to submit Pull Requests. Please: 1. Update tests in `tests/test_workflows.py` for any tag changes. 2. Run `python -m pytest tests/test_workflows.py -v` — all 39 tests must pass. 3. Document newly discovered OpenServer quirks in the tool's module docstring (see `reveal.py` and `resolve.py` for examples). When adding a new tool, use a small script to probe the live API if discovery tags are needed — the PDF documentation is not always reliable. --- ## Disclaimer This project has **no affiliation, endorsement, or sponsorship from Petroleum Experts Limited**. "IPM", "PROSPER", "GAP", "MBAL", "PVTP", "REVEAL", "RESOLVE", and "OpenServer" are trademarks of Petroleum Experts Limited. Using this software with IPM modules requires a valid IPM license from Petroleum Experts. The OpenServer tag strings used here were discovered by probing the live IPM 10 API; these tags are also documented in the official OpenServer User's Manual, but the actual behavior is the de facto basis for this codebase.