OpenFOAM MCP by iLab — a CFD co-pilot for any MCP client

openfoam-mcp is a Model Context Protocol server that turns an AI assistant (Claude Desktop, and any other MCP client) into an OpenFOAM setup and debugging co-pilot. It scaffolds runnable cases, edits dictionaries safely, sizes your near-wall mesh, computes inlet turbulence values, and reads solver logs to tell you whether a run converged or blew up — all without you leaving the chat.

Most of the tools are pure Python and need no OpenFOAM installation, so they work anywhere. The few that call OpenFOAM utilities (e.g. blockMesh, checkMesh) detect the environment and degrade gracefully when it is absent.

Validated end-to-end on real OpenFOAM (ESI v1912). Generated cases run through blockMesh and the solvers — simpleFoam converges, all four mesh presets produce valid meshes, and the real logs are read back correctly by the residual and mesh-quality parsers. See VALIDATION.md.

OpenFOAM version support

scaffold_case takes an openfoam_flavor:

• classic (default) — application <solver>; with transportProperties. Validated on ESI v1912; works on ESI v2006+ and Foundation v8–v10.
• foundation-v12 — application foamRun; + solver incompressibleFluid; with physicalProperties, for OpenFOAM Foundation v11/v12. Run foamRun instead of the solver name.

Why it's useful

Setting up a CFD case is fiddly bookkeeping: the right y+, matching boundary patches between the mesh and every 0/ field, consistent turbulence fields for the chosen model, a stable Courant number, and reading pages of residual output to see if it converged. This server does that bookkeeping through natural language.

Make the hard part simple

Two tools do the work most people find fiddly:

• recommend_setup — tell it your goal in plain words ("flow through a pipe", "drag on a car") and it returns the solver, turbulence model, target y+, mesh preset, per-patch boundary conditions and a numbered plan — asking you for only the numbers it still needs.
• generate_blockmesh — auto-writes a valid, boundary-layer-graded blockMeshDict from a geometry preset. Give it your target first-cell height and it computes the wall grading for you. No hand-writing vertices or blocks.

Tools (20)

Tool	What it does
recommend_setup	Start here. Goal to solver, model, mesh preset, BCs, plan (asks for missing inputs).
generate_blockmesh	Auto blockMesh with wall grading auto-sized to your y+ (presets: channel, flatplate, step, box).
list_mesh_presets	List the blockMesh geometry presets.
list_solvers	List scaffold-able solver templates (simpleFoam, pimpleFoam, icoFoam).
flow_regime	Reynolds number, laminar/turbulent verdict, turbulence-model recommendation.
first_cell_height	First-cell height for a target y+ (flat-plate correlation).
y_plus_from_height	Inverse: predicted y+ from a cell height, with regime warning.
inlet_turbulence	Inlet k, epsilon, omega, nut from intensity + length scale.
time_step_from_cfl	Transient time step from a target Courant number.
pipe_pressure_drop	Colebrook-White friction factor + Darcy-Weisbach pressure drop / head loss.
heat_transfer_pipe	Convective h for internal flow (Dittus-Boelter Nusselt).
scaffold_case	Write a runnable case tree (system/, constant/, 0/) for a solver.
read_dict	Read a dictionary file or a single entry (via foamDictionary).
set_dict_entry	Set a dictionary keyword (nested via foamDictionary; text fallback).
set_boundary_condition	Set/insert a patch's boundaryField entry in a 0/ field.
analyze_stl	STL watertight/manifold check, bbox, area, volume, snappyHexMesh prep.
mesh_quality_report	Parse a checkMesh log into a non-ortho/skewness/aspect verdict + scheme advice.
check_case	Validate a case: files present, turbulence fields consistent, patches match mesh.
analyze_residuals	Parse a solver log into per-field residual drop + convergence verdict.
run_openfoam_command	Run a whitelisted OpenFOAM utility inside a case (if installed).

Install & run

The server ships as a PyPI package with a console entry point, so the usual zero-install runner is uvx:

uvx openfoam-mcp

or install it into an environment:

pip install openfoam-mcp
openfoam-mcp

Claude Desktop configuration

Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "openfoam": {
      "command": "uvx",
      "args": ["openfoam-mcp"]
    }
  }
}

Restart Claude Desktop; the OpenFOAM tools appear under the tools menu.

Example prompts

• "I have air at 30 m/s over a 0.5 m chord. What Reynolds number is that, and what first-cell height do I need for y+ = 1?"
• "Scaffold a steady simpleFoam case in ./duct at 12 m/s and check it."
• "Set endTime to 3000 in ./duct/system/controlDict."
• "Read ./duct/log.simpleFoam and tell me if it converged."

Solver templates

Template	Physics	Typical use
simpleFoam	Steady incompressible RANS (k-ω SST)	Ducts, external aero, general steady flow
pimpleFoam	Transient incompressible RANS (k-ω SST)	Vortex shedding, unsteady flows
icoFoam	Transient incompressible laminar	Low-Re teaching cases (cavity, low-Re pipe)

Templates follow the OpenFOAM foundation v9–v12 / ESI v2306+ tutorial style (transportProperties + momentumTransport). The generated box mesh has patches inlet, outlet, walls, frontAndBack.

Development

pip install -e ".[dev]"
pytest

License

MIT © 2026 iLab (Tanawat Manokieng)