# Gmsh MCP Server

A local Model Context Protocol server for creating, grading, inspecting, viewing, and exporting Gmsh meshes. Native Gmsh state runs in isolated worker processes, while an owned Gmsh GUI displays immutable geometry and mesh checkpoints.

The server favors structured meshes. It includes transfinite box meshing, a conformal external-cylinder O-H template, a five-block straight-pipe template, and user-described connected quadrilateral blocks extruded along `+z`. Tetrahedral meshing is available when explicitly selected. It does not automatically decompose arbitrary CAD into structured blocks.

## Requirements

- Python 3.12 or newer
- [`uv`](https://docs.astral.sh/uv/)
- An interactive desktop for the optional native viewer
- OpenFOAM only if OpenFOAM conversion is required

The default runtime is the `gmsh==4.15.2` Python wheel pinned by this project. A separately installed, matching Gmsh 5 SDK can be selected explicitly as described below.

## Install and verify

```powershell
git clone https://github.com/OFFTECH/gmsh-mcp-server.git
cd gmsh-mcp-server
uv sync
uv run gmsh-mcp doctor
```

Run the included structured-duct demonstration:

```powershell
uv run gmsh-mcp --workspace .gmsh-mcp-workspace/demo demo
```

Add `--gui --hold-seconds 10` to display the checkpoints and capture the final view. The GUI requires an interactive desktop. On Linux, the Gmsh wheel also requires the system OpenGL/GLU libraries.

## Configure an MCP client

Start the stdio server directly with:

```powershell
uv run gmsh-mcp --workspace .gmsh-mcp-workspace/mcp serve
```

An MCP client can launch the virtual-environment Python executable without going through a shell. Replace the paths with absolute paths for your checkout:

```json
{
  "mcpServers": {
    "gmsh": {
      "command": "C:\\path\\to\\gmsh-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "gmsh_mcp",
        "--workspace",
        "C:\\path\\to\\gmsh-mcp-server\\.gmsh-mcp-workspace\\mcp",
        "serve"
      ]
    }
  }
}
```

On Linux or macOS, use `.venv/bin/python`. Standard output is reserved for MCP protocol messages.

## Workflow and capabilities

The server exposes 36 tools. Call `system_capabilities` and use MCP tool discovery for the installed schemas.

| Area | Capabilities |
| --- | --- |
| Sessions | Isolated sessions, optimistic revision guards, idempotent request keys, asynchronous mesh jobs, cancellation and deterministic recovery |
| Geometry | OCC operation batches, entity inspection, named surface patches and fluid volumes |
| Structured templates | Box, external-cylinder O-H, straight filled-bore pipe, and connected XY quadrilateral blocks extruded along `+z` |
| Grading | One-sided geometric grading, two-sided grading, and structured layer planning |
| Mesh diagnostics | Bounded node and element inventory, `minSICN` and `minDetJac` quality histograms, threshold failures |
| Viewer | Explicit checkpoints, six axis presets plus isometric, analytical fit, axis-aligned clipping, PNG capture |
| Export | MSH 2.2 export with checksummed manifests and optional OpenFOAM conversion and `checkMesh` validation |
| Knowledge | Versioned Gmsh documentation cache, authored structured-meshing guidance, search, resources, and prompts |

Geometry, classification, and mesh mutations require the current `expected_revision` and a unique `request_key`. Operations that use native entity tags also require the current `worker_epoch`; inspect entities again after worker recovery. `mesh_generate` returns a job ID that is polled with `job_get`.

Template builders require a fresh session and own their structured controls. A configured first radial edge height constrains that edge sequence; it is not a general guarantee of uniform wall-normal height over arbitrary curved geometry.

The broker process never imports the native Gmsh module. Each model worker owns its native state, and the viewer uses a separate process. This keeps stdio handling responsive and prevents native global state from leaking between model sessions.

## Select a Gmsh runtime

### Wheel baseline: Gmsh 4.15.2

No runtime file is needed for the supported wheel baseline. It is selected whenever `.gmsh-runtime.json` is absent. It can also be selected explicitly:

```powershell
$env:GMSH_MCP_RUNTIME_CONFIG = "wheel"
uv run gmsh-mcp doctor
```

### Explicit Gmsh 5 SDK

The Gmsh Python wrapper and native shared library must come from the same SDK and must be placed side by side. Never combine a wrapper and library from different builds. For the pinned Gmsh 5 reference in `upstream/gmsh5.json`:

1. Obtain the matching official SDK or build the pinned source with `scripts/build_gmsh.ps1`.
2. Put `gmsh.py` and the native library in a local directory. On Windows the expected library name for API 5.0 is `gmsh-5.0.dll`.
3. Copy `gmsh-runtime.example.json` to `.gmsh-runtime.json` and adjust its relative paths.
4. Keep the matching source checkout available at `source_dir` when synchronizing source-backed knowledge.
5. Set `GMSH_MCP_RUNTIME_CONFIG` to the absolute path of that configuration file.
6. Run `uv run gmsh-mcp doctor` before starting the server.

For example, from PowerShell:

```powershell
$env:GMSH_MCP_RUNTIME_CONFIG = (Resolve-Path .gmsh-runtime.json).Path
uv run gmsh-mcp doctor
```

A configured SDK that is missing or mismatched is an error; the server will not silently fall back to the wheel.

The official development SDK URL in `upstream/gmsh5.json` is a rolling artifact. Its contents can change while the URL stays the same, so verify the recorded SHA-256 before use. A checksum failure means the SDK is a different snapshot: do not combine it with the pinned wrapper, library, source revision, or knowledge cache.

Building from source requires CMake, Ninja, C and C++ compilers, plus compatible OpenCASCADE and FLTK development packages. The script does not download those dependencies. It enables the shared library, meshing, OpenCASCADE, and FLTK, and stops if any required feature is absent:

```powershell
./scripts/build_gmsh.ps1 -SourceDir external/gmsh5-source -BuildDir external/build-gmsh5
```

## Knowledge cache

Populate the upstream manual, API, options, and source references explicitly:

```powershell
uv run gmsh-mcp --workspace .gmsh-mcp-workspace/mcp knowledge-sync
```

For a matching local Gmsh checkout, add `--source-checkout PATH`. Set `GMSH_MCP_KNOWLEDGE_DIR` to share a cache between workspaces. The cache version and revision must match the selected runtime; ordinary tool calls do not download documentation.

## OpenFOAM

OpenFOAM conversion is optional. `GMSH_MCP_OPENFOAM_ENV` must contain the descriptor as JSON text, rather than a path to a JSON file. For example, in PowerShell:

```powershell
$env:GMSH_MCP_OPENFOAM_ENV = '{"mode":"wsl","distribution":"Ubuntu-24.04","bashrc":"/opt/openfoam13/etc/bashrc"}'
```

Conversion stages a new case, runs `gmshToFoam`, applies the declared patch types, audits `polyMesh`, and requires `checkMesh -allGeometry -allTopology` to report success. Foundation OpenFOAM 13 under WSL Ubuntu 24.04 is the initially validated target.

## Scope

Current scope includes metre coordinates, first-order meshes, MSH 2.2 ASCII export, basic OCC primitives and booleans, conservative box meshing, fixed structured templates, and explicit connected-block extrusion. Arbitrary CAD import, automatic block decomposition, general 3D layer inflation, wakes, optimization, and quality coloring are not implemented.

## License

This project is licensed under the GNU General Public License v3.0 only. See `LICENSE`. Gmsh and other dependencies remain under their own licenses; see `THIRD_PARTY_NOTICES.md`.