lumerical-mcp

An MCP server that lets an AI assistant drive ANSYS Lumerical FDTD: build scenes, run simulations, and read results back — with a correctness layer that catches simulation settings which would silently produce wrong physics.

Built on the official Python lumapi. 88 async tools cover geometry, sources, monitors, materials (including anisotropic and magneto-optic tensors), mesh control, boundaries, ports/S-parameters, parametric sweeps, field visualisation, and ready-made figure-of-merit extractors (Q-factor, Purcell factor, cross-sections, grating orders, far-field, bandstructure, χ² harmonics). A benchmark suite rebuilds Lumerical Application Gallery examples through the tools and scores them against the gallery's own references.

What this is for

You ask the assistant something like "set up Mie scattering from a 100 nm sphere across 300–1000 nm and find the resonances", and it builds the project through the tools, validates the setup, runs it, and reports the numbers — or you debug an existing .fsp interactively without switching to the GUI.

This is not a remote service. It runs locally, talks to your local Lumerical install over Lumerical's own Python API, and uses your license seat.

Interactive work vs. batch pipelines. The tools shine for interactive work — assemble a scene, validate it, run it, look at the result, iterate. For long unattended pipelines (many-hour parameter sweeps), a script written directly against lumapi is often the more comfortable fit, and the two do not compete: the examples/ are exactly that pattern. When a result is large, prefer save_results (server-side reduction to a .npz) over pulling raw arrays back through the tool channel.

Why a correctness layer

FDTD fails quietly: a mesh too coarse for the in-material wavelength, a monitor inside the near field, a symmetry boundary that contradicts the source polarisation, or a tilted beam launched in the wrong medium all produce plausible-looking, wrong numbers. The server treats this as a first-class problem:

Findings are advisory — the assistant decides — but they are the difference between "the run finished" and "the number is right".

Requirements

• Windows 10/11, Linux, or macOS. Standard install paths for Lumerical v241/v242/v251 are probed at import; set LUMAPI_PATH to override.
• ANSYS Lumerical FDTD installed (developed against 2024 R1 / v241; other versions are expected to work through lumapi's compatibility).
• Python 3.10+.
• An MCP-capable client (tested with Claude Code).

Installation

From the latest release (no cloning needed):

pip install https://github.com/davydov-nikita/lumerical-mcp/releases/download/v0.4.1/lumerical_mcp-0.4.1-py3-none-any.whl

or straight from the repository:

pip install git+https://github.com/davydov-nikita/lumerical-mcp

For development, clone and install editable:

git clone https://github.com/davydov-nikita/lumerical-mcp
cd lumerical-mcp
pip install -e .

Any of these installs the lumerical-mcp console script and the dependencies (mcp[cli], numpy, matplotlib).

Configuration

Register the server with your MCP client. For Claude Code, create .mcp.json in the project you work from:

{
  "mcpServers": {
    "lumerical-fdtd": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "lumerical_mcp.server"],
      "env": {
        "LUMAPI_PATH": "C:\\Program Files\\Lumerical\\v241\\api\\python"
      }
    }
  }
}

(env is only needed when Lumerical is not in a standard location.) The tools appear as mcp__lumerical-fdtd__*. Any other MCP client works the same way with its own registration mechanism.

Tool overview

Units are Lumerical's internal SI: metres, seconds, hertz.

Benchmarks

benchmarks/ measures the server's generality: each task takes a Lumerical Application Gallery example, rebuilds it through the tools from a written spec, runs it, and scores named quantities against the gallery's own reference scene. Verdicts are computed by the scoring script, never judged by the solver. Tasks that expose a missing capability become fixes or new tools; tasks whose oracle cannot be reproduced from a text spec (reference-embedded material fits, construction-script geometry) are documented as such rather than force-passed. See the status table.

Examples

Worked scripts live in examples/: a magneto-optic grating built entirely through the tool surface, grating R/T/A sweeps over angle and wavelength, end-to-end Mie scattering with cross-section analysis, a convergence-certified dielectric Purcell factor, and post-processing / plotting helpers. Outputs go to a results/ directory next to the repo (override with LUMERICAL_MCP_RESULTS).

Transport notes (Windows)

Three startup measures make the stdio transport reliable, particularly on Windows:

• File descriptors 0/1 are duplicated to private handles and the originals are redirected to NUL. The Lumerical engine writes diagnostics directly to fd 1 at the C level; if it inherits the MCP pipe, the JSON-RPC stream is corrupted and the engine handshake can deadlock.
• sys.stdout is re-wrapped with write_through=True to avoid a buffering issue that can hold MCP responses on Windows pipes.
• Every tool is async and dispatches lumapi calls to a worker thread, so the event loop stays responsive during long simulations.

Testing

python -m unittest discover -s tests

The unit tests mock the lumapi session and run without a Lumerical install or license, including an MCP tool-surface check that spawns the server over stdio. On a machine with Lumerical, python check_physics.py additionally runs a small live physics panel (vacuum transmission, validation rules firing on a deliberately bad scene, a known resonator Q) as a pre-release check.

Limitations

• One license seat, one engine handle per process; simulations run serially.
• eval_script loses return values from script-level calls such as addmaterial(...); prefer the typed wrappers, or script_get for expression values.
• Known workarounds for remaining sharp edges (grating-analysis result access, fibre-beam injection for couplers) are documented in CLAUDE.md, which also serves as the field guide an MCP-driving assistant loads automatically.

License

MIT.