Skip to main content
Glama

opm-mcp

CI License: MIT Python 3.11+ 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: SCAL Digital Assistant Suite MCP Server

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)

Variable

Default

Purpose

OPM_MCP_WSL_DISTRO

Ubuntu-24.04

Name of the WSL distro to run OPM in.

OPM_MCP_FLOW_BIN

flow

Binary name / absolute WSL path for Flow.

OPM_MCP_RESINSIGHT_BIN

ResInsight

Binary name / absolute WSL path for ResInsight.

OPM_MCP_WORK_DIR

~/.opm-mcp (Win)

Where job logs and artefacts go.

OPM_MCP_FLOW_THREADS

0 (auto)

--threads-per-process default for runs.

OPM_MCP_JOB_HISTORY

50

How many recent jobs to remember in-memory.

OPM_MCP_LOG_TAIL

200

Default line count for flow_log_tail.

OPM_MCP_MAX_PARALLEL

2

Max concurrent Flow runs; extra submissions queue.

Tool reference

Environment & paths

Tool

Purpose

opm_environment

Probe backend mode (WSL / native Linux), flow, ResInsight, OPM Python bindings.

list_cases

Scan a directory tree for decks/results — the session opener.

to_wsl_path

Translate C:\foo\bar to /mnt/c/foo/bar.

to_windows_path

Reverse translation.

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

Tool

Purpose

validate_deck

Parse a DATA deck, report keyword counts.

summarize_deck

Title, phases, units, grid dims, well/group names, schedule length.

list_wells

Per-well info at schedule step 0.

deck_text

Numbered text slice of the deck or any include file (host-native, no WSL).

deck_grep

Regex search across the deck and its INCLUDE tree (resolves PATHS $ALIASes).

OPM Flow (background jobs)

Tool

Purpose

run_flow

Start a Flow job; returns a job_id immediately. Queues (state="queued") past OPM_MCP_MAX_PARALLEL; mpi_processes=N runs mpirun -np N.

flow_status

Current state, queue position, last progress line, provenance (flow version + deck SHA-256).

flow_log_tail

Tail of combined stdout/stderr; grep= regex-filters the whole log (e.g. "will be shut|Error:").

flow_cancel

Cancel a running or queued job (works across server restarts).

flow_jobs

List recent jobs (most recent first).

Result readers (native Windows via resdata)

Tool

Purpose

list_summary_vectors

All summary keys (FOPR, WBHP:, GOPR:, ...).

read_summary

Time series for one or more keys, with per-vector units + elapsed days, downsampled.

field_summary

Cumulative production/injection, FPR, final rates (with units).

well_summary

Per-well WOPR/WGPR/WWPR/WBHP/WOPT/etc. min/max/last.

grid_info

EGRID dims, active count, INIT property stats.

restart_info

UNRST report step list + keywords.

compare_summaries

Diff field totals between two cases.

Native plotting (matplotlib — no ResInsight/OpenGL)

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

Tool

Purpose

plot_summary

Summary vectors to PNG; wildcards (WWCT:*), auto twin-axis by unit, date or days x-axis.

plot_property_map

I–J areal map of a layer property — dynamic (PRESSURE/SWAT/SGAS/SOIL from UNRST) or static (PORO/PERMX/NTG from INIT).

Reservoir-engineering analytics

Tool

Purpose

material_balance_check

OOIP, recovery factor, exact oil mass-balance drift, surface VRR.

flow_convergence_report

Parse INFOSTEP/INFOITER: wall time by stage, wasted (cut) steps, worst timesteps, residuals.

restart_property

Per-layer stats (PV-weighted, also on grids with inactive cells) for PRESSURE/SWAT/SGAS/SOIL at a report step, plus histogram.

compare_to_observed

History-match QC: RMSE/bias/MAE/NRMSE of sim vs an observations CSV, with overlay plot.

rft_data

RFT pressure-vs-depth surveys per well/date (needs WRFTPLT in the deck).

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)

Tool

Purpose

clone_deck

Write a NEW deck with safe overrides (append_before_end, replace_regex, set_title, insert_after_keyword), reporting per-op substitution counts and re-validating. Enables clone → run → compare loops.

ResInsight automation (CLI command files)

Tool

Purpose

resinsight_snapshot

Open a case, render the default 3D view, save PNG.

resinsight_well_log

Export an LAS well log for one well.

resinsight_open

Launch interactive ResInsight (uses WSLg on Windows 11).

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

OPM utility binaries

Tool

Purpose

convert_ecl

Toggle formatted/unformatted ECL output files.

compare_ecl

Diff two result files within tolerances.

make_restart_deck

History→prediction deck via rst_deck (auto-adds UNIFIN for unified restarts).

pack_deck

Flatten a deck + INCLUDEs into one file (opmpack).

hash_deck

Keyword-level deterministic hash (opmhash).

summary_tool

Text summary table via the OPM summary CLI.

upscaling_status

Detect whether opm-upscaling is installed in WSL.

run_upscaling

Generic passthrough to upscale_perm, upscale_relperm, ...

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

Available Tools

40 tools
clone_deckA

Clone a deck with safe text overrides (append_before_end / replace_regex / set_title / insert_after_keyword).

Writes a NEW deck, reports per-op substitution counts, and re-validates. Idiomatic rate/BHP change: append a new WCONPROD/WCONINJE via append_before_end (last control in SCHEDULE wins).

Inputs: deck_path (required), validate, overrides, output_path, +1 more. Returns: object

compare_eclC

Compare two ECL result files within tolerances using compareECL.

Inputs: case_a (required), case_b (required), abs_tol, rel_tol, +1 more. Returns: object

compare_summariesA

Compare two cases on field totals (or supplied keys). Default = FOPT/FGPT/FWPT/FPR.

Inputs: case_a (required), case_b (required), keys. Returns: object

compare_to_observedB

History-match QC: misfit (RMSE/bias/MAE/NRMSE) of simulated vs observed data.

CSV: first column date (ISO), remaining headers are summary keys (WBHP:PROD, FOPR, ...); blank cells = no observation. Returns per-key stats and an inline sim-vs-obs overlay plot.

Inputs: case_path (required), observed_csv (required), keys, plot, +1 more.

convert_eclB

Convert between formatted (F*) and unformatted ECL result files.

Inputs: input_path (required), mode, output_path. Returns: object

deck_grepA

Regex search across a deck AND its resolved INCLUDE tree (PATHS-aware).

The deck-QC workhorse: deck_grep(deck, "^WCONPROD|^LIFTOPT", context=8) returns file, line number, and context for every keyword hit — including keywords that live in include files referenced via $ALIAS paths. Files larger than ~8 MB (bulk GRDECL arrays) are skipped and reported.

Inputs: pattern (required), deck_path (required), context, ignore_case, +2 more. Returns: object

deck_textA

Numbered text slice of a deck (or one of its include files) — no WSL needed.

Decks are plain ASCII; use this instead of host-shell head/sed when a client misdetects .DATA as binary. file selects an include file by path or bare name (matched against the resolved INCLUDE tree).

Inputs: deck_path (required), file, n_lines, start_line. Returns: object

field_summaryB

Field-level KPIs: cumulative production/injection, pressure, final rates.

Inputs: case_path (required). Returns: object

flow_cancelB

Cancel a running Flow job.

Inputs: job_id (required). Returns: object

flow_convergence_reportC

Solver performance from INFOSTEP/INFOITER: time by stage, wasted steps, worst steps.

Inputs: case_path (required), worst_n. Returns: object

flow_jobsA

List recent Flow jobs known to this server.

Inputs: no named parameters. Returns: object

flow_log_tailA

Return the tail of a Flow job's combined stdout/stderr log.

grep (case-insensitive regex) filters the WHOLE log first and returns the last lines matching lines with line numbers — e.g. grep="will be shut|Problem:|Error:" extracts well-shut and solver events from a long run.

Inputs: job_id (required), grep, lines. Returns: object

flow_statusB

Check whether a Flow job is still running, with the latest progress line.

Inputs: job_id (required). Returns: object

grid_infoB

Static grid info: dimensions, active count, porosity/permeability stats.

Inputs: case_path (required). Returns: object

hash_deckA

Compute a deterministic hash of a deck using opmhash.

Inputs: deck_path (required). Returns: object

list_casesA

Scan a directory tree for simulation cases (.DATA decks and .SMSPEC results).

The session opener: returns case names, deck paths, whether results exist, and modification times (newest first).

Inputs: directory (required), limit, max_depth. Returns: object

list_summary_vectorsB

List summary vector keys in a case. Optional glob pattern (case-insensitive).

Inputs: case_path (required), limit, pattern. Returns: object

list_wellsB

List wells declared in the deck at the first schedule step.

Inputs: deck_path (required). Returns: object

make_restart_deckA

Generate a restart (history -> prediction) deck via OPM's rst_deck.

Restarts base_deck from restart_case:report_step (see restart_info for available steps). Default mode "inline" produces one self-contained deck. Validate and run_flow the result for predictions.

Inputs: base_deck (required), report_step (required), restart_case (required), mode, +2 more. Returns: object

material_balance_checkC

Field MB QC: OOIP, recovery factor, exact oil mass-balance drift, surface VRR.

Inputs: case_path (required). Returns: object

opm_environmentA

Report which OPM binaries and Python bindings the server can reach.

Use this first when troubleshooting — it tells you whether wsl.exe is reachable, whether flow and ResInsight respond, and whether the python3-opm-common bindings import successfully inside the distro.

Inputs: no named parameters. Returns: object

pack_deckB

Flatten a deck and all its INCLUDEs into a single file using opmpack.

Inputs: deck_path (required), output_dir. Returns: object

plot_property_mapA

I–J areal map of a grid property for one K layer, rendered inline.

Dynamic (PRESSURE/SWAT/SGAS/SOIL from UNRST at a report step, default last) or static (PORO/PERMX/NTG/PORV from INIT). Inactive cells blank; axes are 1-based I/J. The no-GL alternative to a ResInsight view for sweep/depletion QC.

Inputs: case_path (required), vmax, vmin, k_layer, +3 more.

plot_summaryA

Plot summary vectors to a PNG, rendered inline in the chat.

Keys accept wildcards (WWCT:*, GOPR:*) as a JSON array; a comma/space separated string also works. Twin y-axis groups by engineering unit; x_axis is "date" or "days". No ResInsight/OpenGL needed — the fast path for rate/pressure/cumulative plots.

Inputs: keys (required), case_path (required), end, start, +5 more.

read_summaryB

Read one or more summary vectors as time series, downsampled to max_points.

keys is a JSON array (["FOPR", "WBHP:B-1H"]); a comma/space separated string is also accepted.

Inputs: keys (required), case_path (required), end, start, +1 more. Returns: object

resinsight_openA

Open ResInsight as an interactive GUI (relies on WSLg). Returns immediately.

Inputs: case_path. Returns: object

resinsight_snapshotB

Render the default 3D view of a case in ResInsight and save a PNG snapshot.

Inputs: case_path (required), view_size, output_dir, extra_commands, +1 more. Returns: object

resinsight_well_logC

Export an LAS well log for one well using ResInsight.

Inputs: well (required), case_path (required), output_dir, properties, +1 more. Returns: object

restart_infoB

List report steps available in a UNRST file plus the keywords it contains.

Inputs: case_path (required). Returns: object

restart_propertyC

Per-layer stats for a dynamic property (PRESSURE/SWAT/SGAS/SOIL) at a report step.

Inputs: case_path (required), keyword, report_step, n_histogram_bins. Returns: object

rft_dataA

RFT surveys (pressure vs depth at well connections) from CASE.RFT.

For perforation-pressure / gradient QC. Requires WRFTPLT in the deck's SCHEDULE section. Cell i/j/k are 1-based.

Inputs: case_path (required), date, well. Returns: object

run_flowA

Start an OPM Flow simulation in the background; returns a job id immediately.

extra_args is a JSON array of flow flags, e.g. ["--enable-tuning=true"] — a plain string is also accepted and split shell-style. At most OPM_MCP_MAX_PARALLEL jobs run at once — extra submissions are state="queued" and launch automatically as slots free. By default writes INFOSTEP/INFOITER diagnostics so flow_convergence_report works (convergence_info="none" to skip). mpi_processes=N runs mpirun -np N for distributed solves.

Inputs: deck_path (required), threads, extra_args, output_dir, +2 more. Returns: object

run_upscalingB

Run an opm-upscaling binary (upscale_perm, upscale_relperm, etc.) passthrough.

args is a JSON array; a plain string is also accepted and split shell-style.

Inputs: args (required), tool (required), cwd. Returns: object

summarize_deckC

High-level deck summary: phases, units, grid dimensions, wells, schedule length.

Inputs: deck_path (required). Returns: object

summary_toolC

Run the OPM summary CLI on a case (alternative summary reader).

Inputs: case_path (required), keys. Returns: object

to_windows_pathA

Translate a WSL path back to its Windows form.

Inputs: wsl_path (required). Returns: object

to_wsl_pathA

Translate a Windows path to its WSL equivalent (C:\x → /mnt/c/x).

Inputs: windows_path (required). Returns: object

upscaling_statusA

Detect whether the optional opm-upscaling binaries are available.

Inputs: no named parameters. Returns: object

validate_deckB

Parse an ECLIPSE/Flow DATA deck and report keyword counts + parser issues.

Inputs: deck_path (required). Returns: object

well_summaryC

Per-well KPIs: oil/gas/water rates, BHP, cumulative production.

Inputs: well (required), case_path (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 40 tools

    Disambiguation4/5

    Most tools have a clear resource-action separation: deck tools, flow job tools, summary tools, and ResInsight tools are easy to tell apart. The main ambiguity is summary_tool vs read_summary/list_summary_vectors, and the cluster of result-reading/plotting tools could occasionally be confused.

    Naming Consistency3/5

    There are strong consistent clusters like flow_*, list_*, plot_*, compare_*, and resinsight_*, but the overall naming is mixed: validate_deck/summarize_deck/deck_text/deck_grep place deck inconsistently, and summary_tool/flow_convergence_report break the verb_noun pattern. The style is readable but not fully predictable.

    Tool Count2/5

    At 40 tools, the surface is well beyond the 25+ threshold for a heavy MCP server, even though the domain spans deck prep, simulation control, results analysis, plotting, restart, and upscaling. Many tools are individually useful, but the overall count creates a steep learning curve and likely too broad an API surface.

    Completeness4/5

    The set covers the core OPM workflow well: environment checks, path translation, deck validation/editing, simulation launch and monitoring, summary/grid/RFT access, history-match comparison, restart deck generation, and upscaling. Minor gaps include no direct case deletion/rename, limited schedule editing beyond clone_deck overrides, and no explicit cleanup/management of generated files or jobs.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables natural language interaction with OpenStudio building energy simulation, allowing creation, querying, and modification of models, running EnergyPlus simulations, and analyzing results.
      58
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides tools for generating, quality-controlling, and exporting relative permeability and capillary pressure curves for reservoir simulation, with integration for Claude Desktop and LangGraph agent.
      -
    • A
      license
      C
      quality
      C
      maintenance
      Enables AI agents to read and write .mph model files, control the COMSOL desktop GUI in real time, and run complete modeling, meshing, solving, and post-processing workflows.
      23
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to run engineering simulations on cloudHPC, including inspecting cases, getting resource advice, uploading, launching, monitoring, diagnosing errors, and downloading results.
      19
      Apache 2.0