# OpenFOAM MCP — a CFD co-pilot for any MCP client

`openfoam-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)
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.

## 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.

## Tools

| Tool | What it does |
|------|--------------|
| `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. |
| `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. |
| `check_case` | Validate a case: files present, turbulence fields consistent, patches match mesh. |
| `analyze_residuals` | Parse a solver log → 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`](https://docs.astral.sh/uv/):

```bash
uvx openfoam-mcp
```

or install it into an environment:

```bash
pip install openfoam-mcp
openfoam-mcp
```

### Claude Desktop configuration

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

```json
{
  "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

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT © 2026 Tanawat Manokieng