opm-mcp

A Model Context Protocol (MCP) server that gives Claude direct access to the Open Porous Media reservoir-simulation stack:

• OPM Flow — black-oil and compositional reservoir simulator (ECLIPSE-compatible), from OPM/opm-simulators.

• ResInsight — 3D viewer and post-processor.

• OPM utility binaries — opmpack, opmhash, summary, convertECL, compareECL.

• OPM upscaling (optional opm-upscaling package).

flow and its Python bindings (python3-opm-simulators) are built from the OPM/opm-simulators repository — see it for the simulator source, supported keywords, build instructions, and issue tracker.

On Windows the server runs natively (so Claude Code / Claude Desktop can spawn it) and delegates every Linux-only binary to an Ubuntu distro under WSL2. On native Linux the same package runs the OPM binaries directly — no WSL involved. Result files (UNSMRY / UNRST / EGRID / INIT / RFT) are parsed in-process via resdata either way.

Architecture

   +-------------------+              +----------------------+
   |     Windows       |              |   WSL2 Ubuntu-24.04  |
   |                   |              |                      |
   |  Claude  <----->  |   wsl.exe    |   flow               |
   |  opm-mcp (Py)     | -----------> |   ResInsight         |
   |     resdata       |              |   python3-opm-common |
   |     (UNSMRY etc.) |              |   convertECL/etc.    |
   +-------------------+              +----------------------+
            ^                                       |
            |     reads result files via UNC /      |
            +---  /mnt/c/... path translation  -----+

Related MCP server: mcp-openhexa

Prerequisites

On Windows:

• Python 3.11+ (tested with 3.13).

• WSL2 enabled, with an Ubuntu-24.04 distro available (wsl -l -v).

In the WSL distro, install OPM:

sudo apt-get update
sudo apt-get install flow resinsight python3-opm-common python3-opm-simulators
# Optional, for the upscaling tools:
sudo apt-get install opm-upscaling
# Optional, for fully headless ResInsight rendering without WSLg:
sudo apt-get install xvfb mesa-utils libgl1-mesa-dri

The flow simulator comes from OPM/opm-simulators. The apt packages above track upstream releases; to run a development build or a specific version, follow the build instructions there and point the server at it with OPM_MCP_FLOW_BIN (see Configuration).

Install

git clone https://github.com/ojaogezi/opm-mcp.git
cd opm-mcp
py -m pip install -e .

This installs the opm-mcp console script and pulls in mcp[cli], resdata, pydantic and numpy.

For development:

py -m pip install -e ".[dev]"
pytest

Register with Claude Code

claude mcp add opm --scope user -- py -m opm_mcp.server

Or, if you prefer a JSON config (Claude Desktop / cursor / etc.), add this to your mcpServers block:

{
  "mcpServers": {
    "opm": {
      "command": "py",
      "args": ["-m", "opm_mcp.server"],
      "env": {
        "OPM_MCP_WSL_DISTRO": "Ubuntu-24.04"
      }
    }
  }
}

Configuration (env vars)

Tool reference

Environment & paths

Deck inspection (uses python3-opm-common in WSL)

OPM Flow (background jobs)

Result readers (native Windows via resdata)

Native plotting (matplotlib — no ResInsight/OpenGL)

Plots return MCP image content, so they render directly in the chat.

Reservoir-engineering analytics

For PVT, SCAL/relative-permeability fitting and deck-physics validation, this server defers to the pyrestoolbox MCP if you have it connected, rather than duplicating those calculators.

Deck editing (sensitivities / history matching)

ResInsight automation (CLI command files)

If ResInsight fails with MESA: error: ZINK ..., pass force_software_gl: true or install xvfb and libgl1-mesa-dri in WSL.

OPM utility binaries

Bigger test cases

This repo only ships the tiny examples/SPE1_MINI.DATA. For real benchmark decks (Norne, SPE9, SPE10, Equinor gas-lift demos, etc.) use the upstream OPM/opm-tests repository — they're distributed under the Open Database License (ODbL 1.0) and shouldn't be re-vendored here. Clone alongside:

git clone https://github.com/OPM/opm-tests.git C:\models\opm-tests

Then point the MCP tools at any deck under that tree, e.g. C:\models\opm-tests\norne\NORNE_ATW2013.DATA.

Smoke test

# 1. Validate a small example deck
py -c "from opm_mcp.tools import deck; import json; print(json.dumps(deck.summarize_deck(r'C:\Users\ogezi\RCI\opm-mcp\examples\SPE1_MINI.DATA'), indent=2))"

# 2. Run Flow on it (completes in a couple of seconds)
py -c "from opm_mcp.tools import flow; import time, json; j = flow.run_flow(r'C:\Users\ogezi\RCI\opm-mcp\examples\SPE1_MINI.DATA'); print(j['job_id']);
import time
time.sleep(5)
print(json.dumps(flow.flow_status(j['job_id']), indent=2))"

# 3. Read summary vectors
py -c "from opm_mcp.tools import results as r; import json; print(json.dumps(r.field_summary(r'C:\Users\ogezi\.opm-mcp\jobs\<JOB_ID>\out\SPE1_MINI'), indent=2))"

Project layout

opm-mcp/
  pyproject.toml
  README.md
  examples/
    SPE1_MINI.DATA
  src/opm_mcp/
    __init__.py
    config.py            # env-var driven settings
    wsl.py               # WSL bridge + path translation (wslpath-aware)
    jobs.py              # background flow-job tracker (restart-safe)
    server.py            # FastMCP entry point (`opm-mcp` script)
    tools/
      deck.py            # validate / summarise / wells
      flow.py            # run, status, log_tail, cancel, jobs
      results.py         # resdata-backed summary/grid/restart readers (units + cache)
      plots.py           # native matplotlib plot_summary
      analysis.py        # material balance, convergence report, restart property
      edit.py            # clone_deck with safe overrides
      resinsight.py      # snapshot, well log, interactive open
      utils.py           # opmpack, opmhash, summary, compareECL, upscaling
    helpers/
      deck_inspect.py    # runs inside WSL — uses python3-opm-common

Notes

• Path handling. Every path argument can be Windows-style (C:\\foo) or WSL-style (/mnt/c/foo, /home/...); the server normalises both directions. Result-file tools accept either the bare case name (SPE1_MINI) or any of its known extensions (.DATA, .SMSPEC, .EGRID, .UNRST).

• Background simulations. run_flow returns immediately and writes its Linux PID + exit code under OPM_MCP_WORK_DIR/jobs/<id>/. Jobs are rehydrated on server restart, so you can still poll (and cancel, via wsl kill) a run that was started before Claude Desktop restarted. Runs also emit INFOSTEP/INFOITER by default for flow_convergence_report.

• Optional upscaling. The opm-upscaling Debian package is not a dependency of Flow; upscaling_status tells Claude whether it's available and prints the install command if not.

License

MIT — see LICENSE for the full text.

Acknowledgements

• Open Porous Media — the underlying reservoir-simulation stack.

• OPM/opm-simulators — OPM Flow, the reservoir simulator (and its Python bindings) this server drives.

• OPM/opm-common — deck parsing, ECL I/O, and the utility binaries (opmpack, convertECL, summary, …).

• Equinor resdata — open-source ECL result-file reader.

• Model Context Protocol and the official Python SDK.