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: Windows-MCP

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.

Repository layout

Quick start

# 1. Install deps under Windows Python (3.11–3.13 recommended)
python -m 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, Spot, FftPsf, FftMtf, Wavefront, …) · zemax_spot_rms Non-sequential: zemax_nsc_summary · zemax_nsc_ray_trace 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 foundation. The connection module and MCP tools follow the canonical Ansys Python templates and the verified ZOS-API object model, but need a live run against OpticStudio to confirm every exact member name. Members flagged [confirm] / # VERIFY in the docs should be checked against ZOS-API.chm.

• 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.