zemax-mcp-server
Allows interaction with Ansys Zemax OpticStudio via the ZOS-API, enabling AI agents to manage optical systems, run analyses, optimize designs, and control lens data editors and non-sequential components.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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."
Related MCP server: DiffBeam MCP Server
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_evalTwo official connection modes, both supported:
Mode | Call | Use it for |
Interactive Extension |
| Attach to a running GUI so edits appear live. Enable Programming ▸ Interactive Extension first. |
Standalone / Headless |
| Launch a headless OpticStudio for batch/automation (needs Pro/Premium tier). |
⚠️ WSL note:
pythonnetloads Windows .NET, so the server runs under Windows Python (python.exe), invoked from Claude Code in WSL. Seesetup/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):
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.
Click the
Programmingtab in the ribbon at the top.In that tab, click
Interactive Extension.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):
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.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_fileto 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 workedThings that trip people up
One arm per click. Interactive Extension accepts a single
ConnectAsExtensionand 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-clickInteractive Extensionbefore 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/.zosuntil you callzemax_save_file(which can Save-As to a path). Save before closing.Standalone/headless mode (
zemax_connectwithmode="standalone") is the no-GUI alternative, but it needs a Professional/Premium/Enterprise API license; on this installCreateNewApplication()reports an invalid API license, so use extension mode.
Repository layout
Path | What |
| Non-invasive dual-mode connector (extension + standalone) via |
| The MCP server — every ZOS-API feature exposed as a described tool. |
| Playbook for sequential imaging design (aperture/fields/wavelengths → variables/solves → merit function → local/hammer/global optimization → aberration control), step by step with the MCP tools. |
| Playbook for non-sequential work (illumination, stray light, scatter, sources/detectors, ray splitting, importance sampling). |
| Live end-to-end check of the MCP tools (build, optimize, undo, analyses, review, tolerancing); PASS/FAIL per step. |
| Closed-loop 2-FSM aimpoint stabilization on a real reflective telescope (converts it to NSC, senses the return, drives two FSMs). See |
| 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 |
| 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. |
| Python deps to install under Windows Python: |
| 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.serverThen 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)
Optimize: zemax_optimize (local/hammer/global, cycles, run time) · zemax_quick_focus
Analyze: zemax_run_analysis (grid stats + data, or x/y curves for ray fans /
MTF) · zemax_analysis_text (full text output of any analysis) · zemax_spot_rms —
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: anything not wrapped yet is reachable
through zemax_eval, and a pattern used often there is a candidate for a new tool.
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 isSpotData.GetRMSSpotSizeFor(field, 0)(polychromatic), the wavefront analysis IDM isWavefrontMap(notWavefront). Tool output is JSON-sanitized so non-finite values (e.g. a planar surface'sradius = Infinity) serialize safely.
Session health. Many rapid
connect → New() → disconnectcycles can wedge the OpticStudio session (New_AnalysisreturnsNone; 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
ConnectAsExtensionthen 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 butIsValidLicenseForAPIis 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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Create and manage AI agents that collaborate and solve problems through natural language interacti…
Connect your AI agent to 300+ methods and 100+ live tools
LLM Orchestration Agent (Openai)
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables natural-language-driven automation of Ansys Lumerical photonic simulations (FDTD, MODE, DEVICE, INTERCONNECT) with 40+ tools for geometry, materials, sources, monitors, solvers, results, optimization, and documentation.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents and engineering tools to validate and simulate Gaussian beam optical systems, search component catalogs, and create immutable design links for optical design workflows.Apache 2.0
- FlicenseNot gradedqualityDmaintenanceSafety-first MCP server enabling AI assistants to drive Zemax OpticStudio sequential-mode optical design workflows, including a mock backend for validation.1-
- AlicenseCqualityBmaintenanceA Windows-only MCP server that enables AI assistants to automate Ansys Zemax OpticStudio through the ZOS-API, exposing sequential and non-sequential mode, analysis, optimization, glass, tolerancing, configuration, and lifecycle operations. It supports stdio, SSE, and Streamable HTTP transports, with per-tool capability statuses distinguishing live-verified, offline-implemented, and scaffolded functionality.1432MIT