Zemax

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:

Mode	Call	Use it for
Interactive Extension	ConnectAsExtension(0)	Attach to a running GUI so edits appear live. Enable Programming ▸ Interactive Extension first.
Standalone / Headless	CreateNewApplication()	Launch a headless OpticStudio for batch/automation (needs Pro/Premium tier).

⚠️ 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

Path	What
zemax_mcp/connection.py	Non-invasive dual-mode connector (extension + standalone) via ZOSAPI_NetHelper.
zemax_mcp/server.py	The MCP server — every ZOS-API feature exposed as a described tool.
docs/function-to-feature-catalog.md	Master map: GUI feature ↔ ZOS-API member ↔ what it does ↔ AI use-case.
skills/sequential-design.md	Playbook for sequential imaging design (aperture/fields/wavelengths → variables/solves → merit function → local/hammer/global optimization → aberration control), with runnable ZOS-API snippets.
skills/non-sequential-design.md	Playbook for non-sequential work (illumination, stray light, scatter, sources/detectors, ray splitting, importance sampling).
examples/smoke_test.py	End-to-end: build a singlet, optimize, print RMS spot.
examples/beam_stabilization.py	Closed-loop 2-FSM aimpoint stabilization on a real reflective telescope (converts it to NSC, senses the return, drives two FSMs). See docs/beam-stabilization-demo.md.
examples/atmosphere_1080nm_2km.py	Atmospheric channel for the 1.08 µm beam over 2 km — absorption (link budget) + scintillation (aperture averaging, fade) + turbulence tilt feeding the FSM loop, plus delivered_power() with first-order thermal blooming. See docs/atmosphere-1080nm-2km.md.
examples/blooming_split_step.py	Wave-optics split-step (BPM) thermal-blooming model — propagates the complex field to the 2 km target with a nonlinear thermal phase; the trustworthy blooming Strehl / beam-bending numbers. Validated vs diffraction theory + the link budget.
requirements.txt	Python deps to install under Windows Python: pythonnet, mcp[cli] (optional zospy).
setup/INSTALL.md	Full setup + troubleshooting.

---

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.