opm-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@opm-mcp Run the SPE1 benchmark case and show the results"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-upscalingpackage).
flowand 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-driThe 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]"
pytestRegister with Claude Code
claude mcp add opm --scope user -- py -m opm_mcp.serverOr, 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 |
|
| Name of the WSL distro to run OPM in. |
|
| Binary name / absolute WSL path for Flow. |
|
| Binary name / absolute WSL path for ResInsight. |
|
| Where job logs and artefacts go. |
|
|
|
|
| How many recent jobs to remember in-memory. |
|
| Default line count for |
|
| Max concurrent Flow runs; extra submissions queue. |
Tool reference
Environment & paths
Tool | Purpose |
| Probe backend mode (WSL / native Linux), |
| Scan a directory tree for decks/results — the session opener. |
| Translate |
| Reverse translation. |
Deck inspection (uses python3-opm-common in WSL)
Tool | Purpose |
| Parse a DATA deck, report keyword counts. |
| Title, phases, units, grid dims, well/group names, schedule length. |
| Per-well info at schedule step 0. |
| Numbered text slice of the deck or any include file (host-native, no WSL). |
| Regex search across the deck and its INCLUDE tree (resolves |
OPM Flow (background jobs)
Tool | Purpose |
| Start a Flow job; returns a |
| Current state, queue position, last progress line, provenance (flow version + deck SHA-256). |
| Tail of combined stdout/stderr; |
| Cancel a running or queued job (works across server restarts). |
| List recent jobs (most recent first). |
Result readers (native Windows via resdata)
Tool | Purpose |
| All summary keys (FOPR, WBHP:, GOPR:, ...). |
| Time series for one or more keys, with per-vector units + elapsed days, downsampled. |
| Cumulative production/injection, FPR, final rates (with units). |
| Per-well WOPR/WGPR/WWPR/WBHP/WOPT/etc. min/max/last. |
| EGRID dims, active count, INIT property stats. |
| UNRST report step list + keywords. |
| 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 |
| Summary vectors to PNG; wildcards ( |
| 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 |
| OOIP, recovery factor, exact oil mass-balance drift, surface VRR. |
| Parse INFOSTEP/INFOITER: wall time by stage, wasted (cut) steps, worst timesteps, residuals. |
| Per-layer stats (PV-weighted, also on grids with inactive cells) for PRESSURE/SWAT/SGAS/SOIL at a report step, plus histogram. |
| History-match QC: RMSE/bias/MAE/NRMSE of sim vs an observations CSV, with overlay plot. |
| RFT pressure-vs-depth surveys per well/date (needs |
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 |
| Write a NEW deck with safe overrides ( |
ResInsight automation (CLI command files)
Tool | Purpose |
| Open a case, render the default 3D view, save PNG. |
| Export an LAS well log for one well. |
| 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 |
| Toggle formatted/unformatted ECL output files. |
| Diff two result files within tolerances. |
| History→prediction deck via |
| Flatten a deck + INCLUDEs into one file ( |
| Keyword-level deterministic hash ( |
| Text summary table via the OPM |
| Detect whether |
| Generic passthrough to |
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-testsThen 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-commonNotes
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_flowreturns immediately and writes its Linux PID + exit code underOPM_MCP_WORK_DIR/jobs/<id>/. Jobs are rehydrated on server restart, so you can still poll (and cancel, viawsl kill) a run that was started before Claude Desktop restarted. Runs also emit INFOSTEP/INFOITER by default forflow_convergence_report.Optional upscaling. The
opm-upscalingDebian package is not a dependency of Flow;upscaling_statustells 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, …).
Available Tools
40 toolsclone_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
Scored across 40 tools
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.
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.
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.
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
Related MCP Connectors
tri-train is a training platform for triathletes that syncs activities from Strava and Garmin and exposes them to Claude through a remote MCP server. Ask Claude how your last block went, why your run pace dropped, or whether you are fresh enough for Sunday's race, and it answers from your real data: activities with laps and grade-adjusted pace, weekly load and the performance management chart (CTL/ATL/TSB), sleep, HRV and resting heart rate, and your race calendar with predictions. Claude can also act: create and adjust planned workouts with structured intervals, push them to your Garmin watch, add races and write notes. Every change is journaled and can be undone. Read and write access are separate OAuth scopes, and the server enforces them on every call. Built and hosted in Switzerland by a triathlete; data stays on our own servers (Swiss revDSG / GDPR).
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables natural language interaction with OpenStudio building energy simulation, allowing creation, querying, and modification of models, running EnergyPlus simulations, and analyzing results.58-
- FlicenseNot gradedqualityCmaintenanceProvides tools for generating, quality-controlling, and exporting relative permeability and capillary pressure curves for reservoir simulation, with integration for Claude Desktop and LangGraph agent.-
- AlicenseCqualityCmaintenanceEnables 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.232MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to run engineering simulations on cloudHPC, including inspecting cases, getting resource advice, uploading, launching, monitoring, diagnosing errors, and downloading results.19Apache 2.0