openfoam-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., "@openfoam-mcp run the motorBike tutorial with 6 cores and plot the drag coefficient"
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.
openfoam-mcp
An MCP server that lets AI coding agents drive OpenFOAM end to end — clone a tutorial, edit dictionaries, mesh, run solvers in the background, watch convergence, and look at the flow — from Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code, Windsurf, Claude Desktop or opencode.
The motorBike tutorial, driven entirely through the server's tools: create_case → import_file (geometry) → run surfaceFeatures / blockMesh → run snappyHexMesh np=6 → check_mesh → run foamRun np=6 → solver_progress → read_postprocessing (forceCoeffs) → render.
Surface pressure ( | Wake slice ( |
|
|
Drag/lift history ( | pitzDaily recirculation ( |
|
|
Why another OpenFOAM MCP?
Existing servers wrap a handful of hard-coded scenarios. This one exposes general, composable primitives and lets the model do the engineering, with guard-rails that make long-running CFD practical from a chat:
openfoam-mcp | |
Works with any case | Clone any of the ~260 tutorials (or your own case) and edit it; no canned geometries |
OpenFOAM versions | openfoam.org 11+ ( |
Long runs | Detached jobs that survive client/server restarts; live progress, ETA, graceful write-and-stop |
Convergence intelligence | Incremental log parsing: residual trends, Courant, continuity, converged / diverging / failed / crashed verdicts, plateau detection, ETA, extracted FOAM FATAL ERROR blocks |
Sees the flow | Headless ParaView renders (slices, patches, streamlines, iso-surfaces such as Q-criterion, mesh) framed on any patch, plus residual/force plots — returned as images |
Safe edits | Dictionary edits go through OpenFOAM's own |
Parallel |
|
Results | Field statistics straight from ASCII or binary field files; postProcessing tables with text and vector columns |
Discoverability |
|
Every client |
|
Token-frugal | Compact JSON, elided field lists, sampled tables, grouped outputs; 25 tools |
Related MCP server: Kratos MCP Server
Install
Requirements: Python ≥ 3.10 and OpenFOAM reachable in one of the ways below. Optional: ParaView with Python for images, OpenMPI for parallel runs.
uv tool install git+https://github.com/0xFFD/openfoam-mcp # or: pipx install git+https://…
openfoam-mcp doctor # checks OpenFOAM, MPI, ParaView, workspace
openfoam-mcp install # registers the server with every MCP client it findsPlatforms
The server runs on the machine (or VM) that can launch OpenFOAM, and finds it automatically:
Platform | How OpenFOAM is reached | Notes |
Linux (native) |
| ParaView: |
macOS (native) | OpenFOAM.app ( | ParaView: the official |
macOS / any OS (container) |
| The way to run openfoam.org releases on a Mac. Tutorials are mirrored to |
Windows | Install inside WSL2; | Native Windows OpenFOAM builds are not supported |
# macOS with OpenFOAM.app
brew install gerlero/openfoam/openfoam && openfoam-mcp doctor
# any OS with Docker (example images: opencfd/openfoam-default for openfoam.com,
# or an openfoam.org image); bake the choice into every client config:
openfoam-mcp install --container-image opencfd/openfoam-defaultinstall detects clients on the Linux side and, when run in WSL, on the Windows side (launching the server via wsl.exe -d <distro> --exec …). Restrict it with --client codex,claude-code, preview with --dry-run, undo with openfoam-mcp uninstall. Every modified config gets a one-time .bak-openfoam-mcp backup.
openfoam-mcp config prints a snippet for each client (--windows for Windows clients using WSL). Examples:
Codex CLI — ~/.codex/config.toml
[mcp_servers.openfoam]
command = "wsl.exe" # or the Linux python path when Codex runs inside Linux
args = ["-d", "Ubuntu-22.04", "--exec", "/home/me/.local/share/uv/tools/openfoam-mcp/bin/python", "-m", "openfoam_mcp", "serve"]
startup_timeout_sec = 30
tool_timeout_sec = 600Claude Code
claude mcp add --scope user openfoam -- wsl.exe -d Ubuntu-22.04 --exec /home/me/.local/share/uv/tools/openfoam-mcp/bin/python -m openfoam_mcp serveCursor / Gemini CLI / Windsurf / Claude Desktop — mcpServers JSON
{ "mcpServers": { "openfoam": { "command": "wsl.exe", "args": ["-d", "Ubuntu-22.04", "--exec", "/home/me/…/python", "-m", "openfoam_mcp", "serve"] } } }Tools
Area | Tools |
Environment |
|
Cases |
|
Files & dictionaries |
|
Running |
|
Mesh |
|
Results |
|
Videos & GPU |
|
Typical loop the agent follows: list_tutorials → create_case → case_summary → set_dict → run blockMesh/snappyHexMesh → check_mesh → run solver → solver_progress → render / post_process.
render modes
auto (whole 2-D domain, mid-plane slice in 3-D) · slice · surface · patches (e.g. pressure on a body) · mesh · contour (iso-surface, e.g. Q-criterion after post_process("Q")) · streamlines — with camera presets, focus on a patch or group, zoom, component, colour range and colormap.
GPU wind tunnel (optional)
gpu_simulate runs a transient lattice Boltzmann simulation (XLB, Apache-2.0) on an NVIDIA GPU around any STL/OBJ, renders every frame on the GPU (a glowing vorticity "smoke" view and a velocity slice) and encodes MP4 videos. It is built for what OpenFOAM on a CPU is slow at: watching unsteady wakes and vortex shedding, in minutes.
openfoam-mcp gpu-setup # one-time: dedicated env with XLB, JAX (CUDA 12) and NVIDIA WarpThen ask your agent something like "put drone.stl in a 15 m/s wind on the GPU and make a video". The grid is sized automatically to the free GPU memory (about 18 M cells on a 6 GB card), and animate turns frames into MP4 or GIF.
Honest limits:
Forces are indicative. The force calculation is verified: on the same simulation it agrees within 2-3 % with an independent control-volume momentum balance. The simulated flow is the approximation: the tunnel walls are no-slip (XLB 0.3.1's far-field conditions were not stable), so blockage raises drag (every run reports its
blockage_ratio), and thin parts such as rotor blades become blunter on the grid. For NASA's Ingenuity the GPU run gave about 21 N of drag where OpenFOAM gave 4.8 N.The simulated Reynolds number is capped. Stability needs a cell Reynolds number of about 100 or less, so a drone at Re 10^5-10^6 is simulated at Re of a few thousand to ten thousand (reported as
reynolds_simulatednext toreynolds_physical). Wakes look right qualitatively; use the OpenFOAM tools for engineering numbers.NVIDIA only (CUDA on Linux or WSL2).
gpu-setuppins Warp 1.8.1 and JAX 0.10.2: newer Warp versions silently mis-voxelize STL bodies with XLB 0.3.1.The stability cap (
max_cell_reynolds, default 100) comes from tests on spheres, boxes and Ingenuity; lower it if a run diverges.mode="fast"(D3Q19 + Smagorinsky) is about 2x faster; both modes,ground=Trueand arbitrary wind directions are covered by the GPU tests. Rendering a time-dependent OpenFOAM case withanimatecosts about 3-4 s per frame (one ParaView render each).
Tested with
OpenFOAM 14 (openfoam.org) on Ubuntu 22.04 / WSL2: pitzDaily (2-D, serial and parallel) and motorBike (3-D,
snappyHexMeshand solver on 6 MPI ranks, 355 k cells).Clients: Claude Code (agent session through
wsl.exe) and Codex CLI (configuration and health check).GPU engine: NVIDIA RTX 2060 (6 GB) under WSL2: sphere, floor-mounted bar with wind from -y, and Ingenuity (18.9 M cells, 18 min).
Python 3.10 and 3.13.
Not yet verified on real hardware: macOS (OpenFOAM.app), Docker/Podman, openfoam.com (ESI) builds — reports welcome.
Configuration
Flag | Env var | Default |
|
|
|
|
| — extra directories tools may access |
|
| auto-detected ( |
|
| auto-detected ( |
|
| — run OpenFOAM in a container started from IMAGE |
|
| — use an existing container (must mount the workspace at the same path) |
|
|
|
|
| auto-detected ( |
|
| the |
|
| scripts allowed |
|
| 45 — how long a tool waits before returning a job id |
| stdio |
Safety model
File access is confined to the workspace (plus
--rootdirectories);..and absolute-path escapes are rejected.runonly executes OpenFOAM applications from the installation's bin directories, or case-localAll*scripts. There is no general shell tool.This is not a sandbox. Case scripts and OpenFOAM's
#codeStream/coded boundary conditions can run arbitrary code by design. Use--no-scriptsand review cases from untrusted sources; run the server under a dedicated user or container if you need isolation.Tools carry MCP annotations (
readOnlyHint,destructiveHint) so clients can auto-approve reads and confirm deletions.
Development
git clone https://github.com/0xFFD/openfoam-mcp && cd openfoam-mcp
uv sync
uv run pytest # unit tests run anywhere; integration tests run when OpenFOAM is found
uv run ruff check src tests
uv run openfoam-mcp serve --workspace /tmp/ws # or point an MCP inspector at itCI runs the unit tests on Linux and macOS. Container mode is tested with a stand-in docker executable (see tests/test_backends.py) that runs the real pitzDaily case through the container code path; reports from real Docker/Podman and OpenFOAM.app setups are very welcome.
Project layout: server.py (tool definitions) · foam.py (installation discovery; native, launcher and container runners; app allow-list) · jobs.py (persistent background jobs) · logs.py (incremental solver-log parser and convergence verdicts) · mesh.py · fields.py · postproc.py · dictparse.py (fast read-only dictionary parser) · render.py + _pv_render.py (ParaView) · gpu.py + _gpu_lbm.py (GPU engine, video encoding) · install.py (client configuration).
License
MIT. OpenFOAM is a registered trademark of OpenCFD Ltd; this project is not affiliated with or endorsed by OpenCFD or the OpenFOAM Foundation.
Available Tools
25 toolscase_summaryARead-only
One-call overview of a case: solver, run control, mesh & patches, initial/boundary conditions, physics, numerics, results.
Inputs: case (required), include_fields.
check_meshBRead-only
Run checkMesh and return structured mesh statistics, failed checks and practical advice.
Inputs: case (required), run, args, wait_seconds.
clean_caseBDestructive
Remove results: time directories after the first, postProcessing, logs, processor dirs and optionally the mesh.
Inputs: case (required), keep_logs, keep_mesh, keep_processor.
create_caseA
Create a case by cloning a tutorial or copying an existing case (results are left behind unless include_results).
Inputs: name (required), source (required), overwrite, include_results.
delete_caseADestructive
Permanently delete a case directory from the workspace.
Inputs: case (required), confirm.
field_statsBRead-only
Min/max/mean of a field (internal and per patch) at a time, read directly from ASCII field files.
Inputs: case (required), field (required), time, region.
foam_infoARead-only
OpenFOAM installation, server configuration and resources (version, flavour, paths, cores, ParaView).
Inputs: no named parameters.
foam_referenceARead-only
Look up what OpenFOAM supports: valid boundary-condition types, models, function objects, solvers, app options.
Inputs: topic (required), filter.
get_dictBRead-only
Read a dictionary or one entry through OpenFOAM's foamDictionary (authoritative parsing).
Inputs: case (required), file (required), entry, expand, +1 more.
import_fileB
Copy geometry (STL/OBJ), meshes or other files into a case, e.g. the surface for snappyHexMesh.
Inputs: case (required), dest (required), source (required).
job_statusARead-only
Status of a job (progress, residuals, errors, log tail) or a list of running and recent jobs.
Inputs: job_id, wait_seconds.
list_casesARead-only
List cases in the workspace with solver, mesh/result state and running jobs.
Inputs: no named parameters.
list_filesARead-only
List files in a case (sizes in bytes; long runs of time directories are collapsed).
Inputs: case (required), depth, subdir.
list_postprocessingBRead-only
List function-object output files under postProcessing/ with their column names.
Inputs: case (required).
list_tutorialsARead-only
Find OpenFOAM tutorial cases to start from (and working examples of any keyword or feature).
Inputs: limit, query, contains.
post_processB
Run a post-processing function object on saved results (writes fields and/or postProcessing/ data).
Inputs: case (required), func (required), args, time, +2 more.
read_fileBRead-only
Read a text file from a case (dictionaries, logs, scripts). Large value lists are elided by default.
Inputs: case (required), path (required), max_lines, start_line, +1 more.
read_logBRead-only
Read the tail of a log, or grep it (e.g. 'FOAM Warning|bounding|Courant').
Inputs: case (required), log, grep, tail.
read_postprocessingARead-only
Read a postProcessing table (forces, coefficients, probes, sampled lines...) with statistics and optional plot.
Inputs: case (required), path (required), plot, columns, +1 more.
renderBRead-only
Render a picture of the flow or mesh with ParaView (headless) and return it as an image plus metadata.
Inputs: case (required), mode, time, view, +17 more.
runA
Run an OpenFOAM application or case script as a background job; waits briefly and reports the outcome or progress.
Inputs: app (required), case (required), np, log, +3 more.
set_dictA
Edit dictionary entries safely via foamDictionary (set/add/remove), then read back the new values.
Inputs: case (required), file (required), set, remove.
solver_progressBRead-only
Convergence report from a solver log: state (converged/diverging/failed...), residuals and trends, Courant, continuity, ETA.
Inputs: case (required), log, plot.
stop_jobADestructive
Stop a running job, gracefully (results written) or forcibly.
Inputs: job_id (required), mode.
write_fileA
Create or overwrite a file in a case (new dictionaries, STL-free text inputs, scripts). Prefer set_dict for edits.
Inputs: case (required), path (required), content (required), append.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools target clearly distinct resources or actions (case creation, file I/O, dictionary editing, job control, post-processing). However, some overlap exists: read_file also reads dictionaries alongside get_dict, and job_status, solver_progress, and read_log all partially cover log/monitoring use cases. Descriptions help differentiate, but these boundaries are not perfectly crisp.
All names use snake_case, and the dominant pattern is verb_noun (e.g., create_case, list_files, read_log). Deviations are mostly conventional noun phrases for info/status tools (foam_info, job_status) and two bare verbs (run, render), which are readable but not perfectly uniform.
At 25 tools, the surface feels heavy for the domain, sitting at the upper end of the rubric's borderline range. While most tools are individually justified for a complex CFD workflow, some consolidation (e.g., monitoring/log tools, file/dict operations) could reduce the count without losing capability.
The surface covers the main OpenFOAM lifecycle: case setup, file/dictionary editing, running solvers, monitoring, mesh checking, post-processing, and rendering. Minor gaps exist, such as file-level delete/move/rename operations and dedicated mesh-generation tools (though run can invoke them), but these are workable for an agent.
Maintenance
Related MCP Connectors
Run FDS, OpenFOAM, CalculiX and other engineering simulations on cloudHPC from your AI assistant.
Parametric 3D CAD for AI agents: build print-ready parts, check them, export STL, 3MF or STEP.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Design, save, and run outcome-aligned AI workflows and verifiers, with reliable image output.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceAutomates OpenFOAM CFD simulations via MCP, enabling AI agents to mesh, run, and post-process cases from natural language prompts without any API keys.MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to drive Kratos Multiphysics finite element simulations end to end, including introspection, scaffolding, execution, and post-processing.1132MIT
- AlicenseAqualityCmaintenanceVoice-driven CFD MCP server that enables natural language setup, execution, and analysis of OpenFOAM simulations, with results exportable to ParaView.16MIT
- AlicenseNot gradedqualityCmaintenanceTurns an AI assistant into an OpenFOAM setup and debugging co-pilot, enabling case scaffolding, dictionary edits, mesh sizing, turbulence calculations, and solver log analysis through natural language.MIT



