zemax-mcp-server

Drive Ansys Zemax OpticStudio from Claude Code — live, via the ZOS-API — without touching Zemax's source or binaries.

This project turns a locally-installed Ansys Zemax OpticStudio into a set of named, self-describing tools that Claude Code (or any MCP client) can call. Each tool couples one ZOS-API operation with a plain description, so an AI agent can go from intent → optical-design action → numeric result.

It is non-invasive: it only loads the three public ZOS-API .NET assemblies that ship with OpticStudio (ZOSAPI.dll, ZOSAPI_Interfaces.dll, ZOSAPI_NetHelper.dll) through pythonnet. Nothing in the Zemax install is modified.

Verified against Ansys Zemax OpticStudio 2025 R2.02.

Why this exists

Optical design in OpticStudio is a GUI-heavy, expertise-heavy loop. The ZOS-API exposes almost the entire object model — editors, analyses, optimizers, ray tracing — to external code. This repo wraps that surface for an AI agent so you can converse your way through a design:

"Connect in extension mode, set the aperture to F/4, add visible wavelengths, build a singlet, make the radii variables, run the wizard, then hammer-optimize and tell me the RMS spot."

Architecture

┌─────────────────┐   MCP (stdio)   ┌──────────────────────┐   pythonnet/.NET   ┌───────────────────────┐
│  Claude Code     │◄──────────────►│  zemax_mcp.server    │◄─────────────────►│  OpticStudio (ZOS-API) │
│  (WSL / Linux)   │  python.exe     │  (Windows Python)    │   ZOSAPI.dll etc.  │  GUI or headless       │
└─────────────────┘                 └──────────────────────┘                    └───────────────────────┘
        tools:  zemax_connect · zemax_set_aperture · zemax_lde_* · zemax_optimize · zemax_run_analysis · zemax_nsc_* · zemax_eval

Two official connection modes, both supported:

⚠️ WSL note: pythonnet loads Windows .NET, so the server runs under Windows Python (python.exe), invoked from Claude Code in WSL. See setup/INSTALL.md.

Connecting to OpticStudio (step by step)

Extension mode attaches the MCP server to your already-running OpticStudio GUI, so every edit Claude makes appears live in the Lens Data Editor. This is the mode to use (standalone/headless needs a license tier this install doesn't grant — see caveats).

In OpticStudio (the GUI):

1. Launch OpticStudio and open the system you want to work on (or start a new one). Any lens file is fine — the bridge attaches to whatever is open.

2. Click the Programming tab in the ribbon at the top.

3. In that tab, click Interactive Extension.

4. A small dialog appears — "Zemax is listening for the ZOS-API client to connect…" (it shows a status like Not Connected / Waiting). Leave this dialog open. OpticStudio is now listening for exactly one connection.

In Claude Code (this session):

5. Ask Claude to connect — e.g. "connect to zemax" — which calls zemax_connect (mode="extension", the default). On success it returns the license edition, serial, samples dir, and the currently open file, and the OpticStudio dialog flips to Connected.

6. That's it — now ask Claude to open a file, edit surfaces, trace rays, optimize, etc. Changes show up live in the GUI. Use zemax_save_file to write the result back to disk.

Quick self-test instead of step 5 (from WSL, optional):

python.exe -m zemax_mcp.connection extension   # prints edition/serial if the arm worked

Things that trip people up

• One arm per click. Interactive Extension accepts a single ConnectAsExtension and then stops listening. The long-lived MCP server grabs it once and holds it for the whole session, so you normally click once. If the connection drops (or you ran a one-shot script), re-click Interactive Extension before reconnecting.

• "License is not valid for ZOS-API use" on connect almost always means the dialog isn't armed — go back to Programming ▸ Interactive Extension and click it, then retry zemax_connect.

• Don't close the dialog while you want the live link; closing it drops the connection.

• Edits are live and unsaved. Nothing is written to .zmx/.zos until you call zemax_save_file (which can Save-As to a path). Save before closing.

• Standalone/headless mode (zemax_connect with mode="standalone") is the no-GUI alternative, but it needs a Professional/Premium/Enterprise API license; on this install CreateNewApplication() reports an invalid API license, so use extension mode.

Repository layout

Quick start

# 1. Install deps under Windows Python (3.11–3.13 recommended)
python -m pip install -r requirements.txt      # or: pip install pythonnet "mcp[cli]"

# 2. Smoke-test the connection (open OpticStudio + Programming ▸ Interactive Extension first)
python -m zemax_mcp.connection extension

# 3. Register with Claude Code (from WSL)
claude mcp add zemax -- python.exe -m zemax_mcp.server

Then just talk to Claude about your optical system.

Tool surface (v0.1)

Connection: zemax_connect · zemax_disconnect · zemax_info System: zemax_new_system · zemax_open_file · zemax_save_file · zemax_set_aperture · zemax_set_wavelengths · zemax_set_fields Lens Data Editor: zemax_lde_summary · zemax_lde_insert_surface · zemax_lde_set_surface · zemax_set_variable Optimize: zemax_merit_wizard · zemax_merit_value · zemax_optimize (local/hammer/global) · zemax_quick_focus Analyze: zemax_run_analysis (RayFan, StandardSpot, FftPsf, FftMtf, WavefrontMap, …) · zemax_spot_rms · zemax_analysis_series (x/y curves for ray fans / MTF) · zemax_batch_ray_trace (fast normalized ray trace) Multi-config: zemax_mce_summary · zemax_mce_add_config · zemax_mce_add_operand Tolerancing: zemax_tde_summary · zemax_tolerance_wizard · zemax_run_tolerancing Non-sequential: zemax_nsc_summary · zemax_nsc_ray_trace · zemax_nsc_detector_data Advanced: zemax_eval (gated escape hatch for un-wrapped calls)

The tool set is intentionally extensible — the function-to-feature catalog is the roadmap for wrapping the rest of the API.

Status & caveats

• v0.1 — verified live. All 31 MCP tools were run end-to-end against OpticStudio 2025 R2.02 (Enterprise) in extension mode — including a full build→optimize loop (merit 1.03→0.08, RMS spot 1453→56 µm), batch ray tracing, ray-fan/MTF curve extraction, multi-config edits, a 21-operand tolerance wizard

  • Monte-Carlo run, and NSC detector readout on the Diode sample (50×50, total flux 15625). A member-name probe confirmed 33/35 members on the first pass; the two misses were fixed and re-verified: RMS spot is SpotData.GetRMSSpotSizeFor(field, 0) (polychromatic), the wavefront analysis IDM is WavefrontMap (not Wavefront). Tool output is JSON-sanitized so non-finite values (e.g. a planar surface's radius = Infinity) serialize safely.

• Session health. Many rapid connect → New() → disconnect cycles can wedge the OpticStudio session (New_Analysis returns None; on-axis rays report spurious errors). The long-lived MCP server does one connection and holds it, so it won't hit this; the analysis tools now raise a clear "restart & reconnect" message if they detect the wedged state.

• Extension mode arms one connection per click. Programming ▸ Interactive Extension accepts a single ConnectAsExtension then stops listening; the long-lived MCP server grabs it once and holds it, so this only matters if you run multiple one-shot scripts (re-click between each).

• Standalone/headless was not available on this license despite the Enterprise edition — CreateNewApplication() succeeds but IsValidLicenseForAPI is false. Use extension mode.

• Third-party wrappers exist and are worth knowing: ZOSPy (MIT, pythonnet, actively maintained — recommended for heavier use) and the older COM-based PyZOS (largely unmaintained since ~2016).

License

MIT (see project owner).

Built with a cited deep-research pass over the official Ansys/Zemax ZOS-API documentation and Knowledgebase. Non-invasive by construction.