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

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

Related MCP server: OpenFOAM MCP Server

Install and verify

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:

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:

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:

{
  "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.

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:

$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:

$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:

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

Knowledge cache

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

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:

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