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_lde_* · zemax_mfe_* · zemax_operand · zemax_optimize · zemax_analysis_* · zemax_snapshot · 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):

1. 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.
2. 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

Connection: zemax_connect · zemax_disconnect · zemax_info ·
zemax_cleanup (recover a stuck session without restarting OpticStudio)
System: zemax_new_system · zemax_open_file · zemax_save_file ·
zemax_set_aperture · zemax_set_wavelengths · zemax_set_fields
Undo: zemax_snapshot · zemax_restore · zemax_diff — optimize / wizard /
restore snapshot automatically to <Zemax data>\MCP\snapshots
Lens Data Editor: zemax_lde_summary (types, conics, solves, parameters) ·
zemax_lde_insert_surface · zemax_lde_remove_surface · zemax_lde_set_surface
(surface type, conic, stop, parameters) · zemax_set_variable (any cell, glass
substitution) · zemax_set_solve (marginal-ray focus, F/#, pickups, …)
Merit function: zemax_operand (evaluate any operand: EFFL, TOTR, RWRE, FICL, …) ·
zemax_mfe_summary (with % contribution) · zemax_mfe_set_operand · zemax_mfe_remove ·
zemax_merit_wizard (with glass/air boundaries) · zemax_merit_value
Optimize: zemax_optimize (local/hammer/global, cycles, run time) · zemax_quick_focus
Analyze: zemax_run_analysis (grid stats + data; RayFan, FftPsf, WavefrontMap, …) ·
zemax_analysis_text (full text output of any analysis) · zemax_spot_rms ·
zemax_analysis_series (x/y curves for ray fans / MTF) — all take MODIFYSETTINGS
settings · zemax_layout_image (PNG of the layout) ·
zemax_batch_ray_trace (fast normalized ray trace)
Review: zemax_performance_summary ("is it good?": first-order data, WFE/Strehl,
spot, distortion, MTF, vignetting) · zemax_design_audit ("is it right?": defocus,
afocal output, edge thickness, aspect ratio, steep surfaces, angles of incidence,
ray failures) · zemax_verify_spec ("does it meet my spec?", JSON) · prompt
/mcp__zemax__zemax_review (full expert review)
Multi-config: zemax_mce_summary · zemax_mce_add_config · zemax_mce_add_operand
Tolerancing: zemax_tde_summary · zemax_tolerance_wizard (with settings) ·
zemax_run_tolerancing (sensitivity + Monte Carlo → worst offenders, yield
percentiles, yield at a threshold, compensator range) · zemax_tolerance_results
(re-read a .ZTD)
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.