zemax-mcp
Automates Ansys Zemax OpticStudio through ZOS-API, exposing operations for sequential and non-sequential optical systems, analysis, optimization, glass, tolerancing, configuration, and lifecycle management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zemax-mcp optimize the current system for minimum spot size"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
zemax-mcp
A Windows-only Model Context Protocol (MCP) server for automating Ansys Zemax OpticStudio through ZOS-API.
zemax-mcp exposes sequential, non-sequential, analysis, optimization, glass, tolerancing, configuration, and lifecycle operations to MCP clients such as Cherry Studio, Claude Desktop, Claude Code, and other clients that can launch a local stdio server.
Project status: alpha and offline-first. Public schemas, catalog coverage, import safety, and fake-backend behavior are tested without OpticStudio. A registered tool is not necessarily live-verified against ZOS-API; consult the capability status before relying on it in production.
Contents
Related MCP server: SolidWorks MCP Bridge
What this project does
The package separates the public JSON/MCP surface from the proprietary .NET runtime. Source inspection, packaging, CI, catalog generation, and offline tests therefore remain redistributable and runnable without Ansys software. Live optical operations load Python.NET and the locally installed ZOS-API assemblies only when needed.
The public interface is maintained in the checked-in tool registry and capability manifest. Each tool has an explicit implementation and evidence status so users can distinguish live-verified behavior from offline-tested or scaffolded functionality.
Current MCP surface
The source-derived catalog currently contains:
Surface or status | Count |
Registered tools | 143 |
MCP resources | 3 |
MCP prompts | 3 |
Production handlers | 131 |
Live-verified tools | 34 |
Offline-implemented tools | 97 |
Scaffolded tools | 11 |
Unsupported tools | 1 |
The 131 production handlers consist of 34 tools with recorded live evidence and 97 tools implemented and tested offline. The intentionally unsupported tool is zemax_eval.
Capability statuses mean:
live-verified: exercised successfully against a documented OpticStudio/API environment.offline-implemented: implemented and tested with fakes or offline tests, but not proven against a live ZOS-API environment.scaffolded: its public name and contract are cataloged, but execution is not implemented.unsupported: intentionally unavailable, with the reason recorded in the catalog.
The server also provides these resources:
zemax://catalog/manifestzemax://catalog/capabilitieszemax://session/status
And these workflow prompts:
zemax_analyze_systemzemax_optimize_systemzemax_build_nsc_system
Inspect the source-of-truth report with:
uv run zemax-mcp manifest
uv run zemax-mcp report --checkSee Tool coverage, tool-coverage.json, and the curated live test report.
Prerequisites
Offline installation, development, and CI
Windows 10 or Windows 11, 64-bit.
CPython 3.11 or 3.12, 64-bit.
uv.A compatible .NET runtime for Python.NET, normally the Windows .NET Framework runtime available on supported OpticStudio workstations.
Git, if cloning the repository instead of downloading a ZIP archive.
Confirm that the commands are available:
python --version
git --version
uv --versionLive OpticStudio use
Live operations additionally require:
A locally installed, ZOS-API-capable version of Ansys Zemax OpticStudio.
A valid OpticStudio/API license and an available license seat.
Access to the ZOS-API assemblies installed with OpticStudio.
For Interactive Extension mode, a running OpticStudio instance configured to accept the extension connection.
Permission under your Ansys license and organizational policy to perform the requested automation.
This package does not include, grant, emulate, or bypass OpticStudio or ZOS-API licensing.
Download from GitHub
The GitHub repository is:
https://github.com/YonggangG/Zemax_MCP_Server
Option 1: Clone with Git
Install Git and uv first, then verify that both commands are available:
winget install --id Git.Git --exact --source winget
winget install --id astral-sh.uv --exact --source winget
git --version
uv --version
git clone https://github.com/YonggangG/Zemax_MCP_Server.git
cd Zemax_MCP_ServerIf either command is still unavailable after installation, close and reopen PowerShell before continuing.
To update an existing clone later:
git pull --ff-only
uv sync --frozenOption 2: Download the source ZIP
Download the current main branch from:
https://github.com/YonggangG/Zemax_MCP_Server/archive/refs/heads/main.zip
Extract the ZIP, open PowerShell in the extracted directory, and follow the installation instructions below.
Option 3: Use a GitHub Release
Audited wheels and source archives may be attached to:
https://github.com/YonggangG/Zemax_MCP_Server/releases
The repository source is the normal choice for development and for the checked-in MCP client examples. The dist/ folder is generated build output and is not the GitHub source repository. Do not upload an old local dist/ blindly; rebuild and inspect release artifacts before publishing them.
Install and validate
Minimal runtime installation from a checkout
From the repository root:
uv sync --frozen
uv run zemax-mcp version
uv run zemax-mcp doctor
uv run zemax-mcp report --checkStart the default stdio server with:
uv run zemax-mcp serveThe server waits for an MCP client on standard input/output. It may appear idle when started directly in a terminal; that is normal.
Development installation
Install all optional and development dependencies:
uv sync --frozen --all-extras --devOptional direct executable
After uv sync, the checkout contains a console executable at:
C:\path\to\Zemax_MCP_Server\.venv\Scripts\zemax-mcp.exeThis absolute executable path is useful when a GUI client cannot find uv through its inherited PATH. Validate it with:
.\.venv\Scripts\zemax-mcp.exe version
.\.venv\Scripts\zemax-mcp.exe doctorWhat doctor checks
zemax-mcp doctor checks the Python version, installed MCP SDK, expected MCP SDK API import, non-empty tool catalog, CLR-free session import, and host platform information.
It does not prove that:
ZOS-API assemblies can be loaded;
an OpticStudio license is available;
standalone or Interactive Extension connection succeeds;
a particular lens can be opened or modified;
every registered tool works in the installed OpticStudio version.
For an actual live connectivity test, start the server from an MCP client and call zemax_connect.
Run the server
CLI commands
uv run zemax-mcp version
uv run zemax-mcp doctor
uv run zemax-mcp doctor --json
uv run zemax-mcp manifest
uv run zemax-mcp manifest --compact
uv run zemax-mcp report
uv run zemax-mcp report --check
uv run zemax-mcp serveCalling zemax-mcp without a subcommand also starts the stdio server.
Transports
Transport | Example | Intended use |
stdio |
| Default and recommended for Cherry Studio, Claude Desktop, and Claude Code. |
SSE |
| Local clients that specifically require the legacy SSE transport. |
Streamable HTTP |
| Local HTTP MCP clients. |
The checked-in client examples use stdio. SSE and Streamable HTTP are supported by CLI routing but are not the primary live-evidence transport. They do not add authentication or TLS; keep them bound to 127.0.0.1 unless a reviewed gateway supplies access control, encryption, and auditing.
Configure MCP clients
Use absolute Windows paths. For stdio, MCP JSON-RPC owns standard input/output; diagnostics must not be inserted into stdout. Avoid wrapping the server in PowerShell, cmd /c, or a pipeline unless the client specifically requires a shell.
Ready-to-edit templates are in examples/:
Cherry Studio
In Settings → MCP Servers, add a local command/stdio server:
Name:
zemaxType/transport:
stdioor local commandCommand:
uvArguments:
--directory,C:\path\to\Zemax_MCP_Server,run,zemax-mcp,serveEnvironment: at minimum, choose the intended connection mode
Equivalent JSON-shaped configuration:
{
"mcpServers": {
"zemax": {
"command": "uv",
"args": [
"--directory",
"C:\\path\\to\\Zemax_MCP_Server",
"run",
"zemax-mcp",
"serve"
],
"env": {
"ZEMAX_MCP_CONNECTION_MODE": "standalone",
"ZEMAX_MCP_INSTALL_DIR": "C:\\Program Files\\Ansys Zemax OpticStudio 2025 R1.01",
"ZEMAX_MCP_ZOSAPI_PATH": "C:\\Users\\yonggang\\Documents\\Zemax\\ZOS-API\\Libraries\\ZOSAPI_NetHelper.dll"
}
}
}
}If Cherry Studio cannot resolve uv, set command to the absolute C:\\path\\to\\Zemax_MCP_Server\\.venv\\Scripts\\zemax-mcp.exe path and set args to ["serve"].
Verify the paths before saving:
ZEMAX_MCP_INSTALL_DIRandZEMAX_MCP_ZOSAPI_PATHare examples for one workstation. Confirm the OpticStudio version, Windows user name, and DLL location on your computer, then replace these values as needed.
Cherry Studio settings example
The screenshot below shows a connected local stdio configuration. Replace the project, OpticStudio, and ZOS-API paths with locations on your own Windows workstation.

Save the entry, enable it, and review the server log if the connection indicator does not become ready.
Claude Desktop
On Windows, edit the per-user configuration file, normally:
%APPDATA%\Claude\claude_desktop_config.jsonAdd the server under mcpServers:
{
"mcpServers": {
"zemax": {
"command": "uv",
"args": [
"--directory",
"C:\\path\\to\\Zemax_MCP_Server",
"run",
"zemax-mcp",
"serve"
],
"env": {
"ZEMAX_MCP_CONNECTION_MODE": "standalone",
"ZEMAX_MCP_INSTALL_DIR": "C:\\Program Files\\Ansys Zemax OpticStudio 2025 R1.01",
"ZEMAX_MCP_ZOSAPI_PATH": "C:\\Users\\yonggang\\Documents\\Zemax\\ZOS-API\\Libraries\\ZOSAPI_NetHelper.dll"
}
}
}
}Verify the paths before saving:
ZEMAX_MCP_INSTALL_DIRandZEMAX_MCP_ZOSAPI_PATHare examples for one workstation. Confirm the OpticStudio version, Windows user name, and DLL location on your computer, then replace these values as needed.
Alternatively, set command to the absolute .venv\Scripts\zemax-mcp.exe path and set args to ["serve"].
Restart Claude Desktop completely after changing the configuration. If uv works in PowerShell but not in Claude Desktop, use where.exe uv and place the returned absolute uv.exe path in command, or use the direct executable pattern above.
Claude Code
Register the checkout as a local stdio server:
claude mcp add --transport stdio zemax -- uv --directory C:\path\to\Zemax_MCP_Server run zemax-mcp serve
claude mcp listOr register the direct executable:
claude mcp add --transport stdio zemax -- C:\path\to\Zemax_MCP_Server\.venv\Scripts\zemax-mcp.exe serve
claude mcp listFor a project-shared .mcp.json, start with examples/claude-code.mcp.json. Do not commit user-specific absolute paths, license information, customer paths, or secrets.
Other stdio MCP clients
Use one of these equivalent launch patterns:
uv --directory C:\path\to\Zemax_MCP_Server run zemax-mcp serveor:
C:\path\to\Zemax_MCP_Server\.venv\Scripts\zemax-mcp.exe serveMap the command, argument list, and environment variables into the client’s local-process/stdio MCP configuration format.
Runtime configuration
Environment variables are the stable way to configure desktop stdio clients:
Variable | Meaning | Default |
| OpticStudio installation root | auto-discover |
| ZOS-API directory or full path to | auto-discover |
|
|
|
| Interactive Extension instance ID |
|
| Internal serialized ZOS worker name |
|
| Explicit Glasscat search root(s), separated by the Windows path separator | unset |
| Zemax root whose | unset |
| Must be | unset |
Discovery checks explicit configuration first, followed by common Windows registry entries and known Program Files locations. If discovery fails, set ZEMAX_MCP_ZOSAPI_PATH explicitly.
Standalone versus Interactive Extension
Mode | Behavior | Recommended use |
| Starts and owns a headless OpticStudio application through ZOS-API. The server may close the application it created. | Reproducible automation jobs and isolated MCP sessions. |
| Borrows a user-started OpticStudio application through Interactive Extension. The server must not close the borrowed application by default. | Inspecting or modifying a system already open in the OpticStudio UI. |
For extension mode, enable Interactive Extension in OpticStudio before the MCP server connects, then use:
{
"ZEMAX_MCP_CONNECTION_MODE": "extension",
"ZEMAX_MCP_INSTANCE_ID": "0"
}Instance IDs are installation/session specific. 0 selects the first or default available instance.
Architecture
MCP transport / CLI
|
Tool registry + source-derived manifest
|
Pydantic contracts and service layer
|
Process-wide serialized ZOS executor
|
ZOS backend protocol
/ \
Fake backend Python.NET + local ZOS-API assembliesKey design rules:
Public modules and catalog inspection remain importable without loading OpticStudio or initializing Python.NET.
Proprietary assembly loading occurs only in the dedicated ZOS execution path.
ZOS-API calls are serialized because automation objects are stateful and thread-sensitive.
Standalone applications are owned; Interactive Extension applications are borrowed.
Handles prevent raw .NET objects from leaking into JSON/MCP contracts.
Fake backends support deterministic offline contract and lifecycle tests.
See Architecture.
Testing and development
Run the public offline checks from the repository root:
uv sync --frozen --all-extras --dev
uv run zemax-mcp report --check
uv run ruff format --check .
uv run ruff check .
uv run mypy src tests
uv run pytest -m "not live_zemax" --cov=zemax_mcp --cov-report=term-missing --cov-report=xml
uv build
uv run python scripts/verify_dist_contents.py distLive tests require both the marker and an explicit opt-in on a licensed workstation; they never run in public CI:
$env:ZEMAX_MCP_LIVE = '1'
uv run pytest -m live_zemaxReview live tests before running them. They may launch OpticStudio, consume a license seat, create output, or modify the active disposable system. See Testing.
Security and proprietary files
This server can open, modify, optimize, and save optical systems. Treat MCP access as local automation authority over the connected OpticStudio environment. Do not enable the server for untrusted users or prompts without suitable process, filesystem, network, and client controls.
This repository and its Python distributions do not include or redistribute ZOS-API DLLs, OpticStudio executables, glass catalogs, sample lens files, license material, or other Ansys/Zemax assets. At runtime the package discovers assemblies from the user’s licensed local installation.
Do not copy proprietary files into the repository, wheels, source archives, CI artifacts, examples, or bug reports. See SECURITY.md and THIRD_PARTY_NOTICES.md.
Troubleshooting
Start with:
uv run zemax-mcp doctor
uv run zemax-mcp doctor --json
uv run zemax-mcp report --checkSee Troubleshooting for uv path resolution, missing assemblies, Python/.NET bitness mismatches, unavailable licenses, Interactive Extension setup, stdio contamination, and stale client processes.
Roadmap
See Roadmap. Registration and offline implementation are not substitutes for expanding repeatable live-verification coverage across supported OpticStudio versions and connection modes.
License
MIT. See LICENSE.
Ansys, Zemax, OpticStudio, ZOS-API, Claude, and Cherry Studio are trademarks or products of their respective owners. This project is not endorsed by or affiliated with those vendors unless explicitly stated.
Available Tools
143 toolszemax_add_configuration_operandAdd Configuration OperandD
Add an MCE operand.
Inputs: operandType (required), param1, param2, param3, +1 more.
zemax_add_material_catalogAdd Material CatalogB
Add a material catalog to the current optical system.
Inputs: catalogName (required).
zemax_add_operandAdd OperandC
Add an optimization operand to the merit function.
Inputs: operandType (required), int1, int2, data1, +8 more.
zemax_add_surfaceAdd SurfaceC
Insert a new sequential surface.
Inputs: radius, comment, insertAt, material, +1 more.
zemax_analysis_seriesAnalysis SeriesC
Run an arbitrary series analysis and return decimated curves.
Inputs: analysisType (required), maxPoints.
zemax_batch_ray_traceBatch Ray TraceC
Trace a batch of normalized sequential rays.
Inputs: rays (required), rayType, toSurface, wavelength.
zemax_cardinal_pointsCardinal PointsC
Calculate focal lengths, principal planes, and other cardinal points.
Inputs: wavelength.
zemax_chromatic_focal_shiftChromatic Focal ShiftB
Calculate longitudinal chromatic focal shift versus wavelength.
Inputs: no named parameters.
zemax_close_fileClose FileA
Close the current optical system while retaining the application connection.
Inputs: save (required).
zemax_connectConnectC
Connect to OpticStudio in standalone or interactive-extension mode.
Inputs: mode, instanceId.
zemax_constrained_optimizeConstrained OptimizeC
Run the custom bound-constrained Levenberg-Marquardt optimizer.
Inputs: delta, initialMu, maxRestarts, maxIterations, +1 more.
zemax_delete_configuration_operandDelete Configuration OperandC
Delete an MCE operand row.
Inputs: row (required).
zemax_design_lockdownDesign LockdownC
Apply destructive Design Lockdown to an owned disposable sequential system.
Inputs: confirmDestructive (required), excludePickups, timeoutSeconds, fixModelGlasses, +3 more.
zemax_diffraction_encircled_energyDiffraction Encircled EnergyC
Calculate FFT diffraction encircled energy versus radius.
Inputs: sampling, useDashes.
zemax_disconnectDisconnectC
Disconnect cleanly and close an owned OpticStudio application.
Inputs: save.
zemax_evalEvalC
Advanced backend-defined diagnostic/evaluation escape hatch; disabled unless explicitly allowed.
Inputs: code (required).
zemax_export_analysisExport AnalysisB
Export an analysis result as text, bitmap, or structured data.
Inputs: filePath (required), analysisType (required), format.
zemax_export_glass_catalogExport Glass CatalogC
Export filtered glasses to a new AGF catalog.
Inputs: catalogName (required), sourceCatalogs (required), outputDirectory (required), wa, +20 more.
zemax_fft_mtfFft MtfC
Calculate diffraction FFT MTF curves for all fields.
Inputs: frequency (required), sampling, wavelength.
zemax_fft_mtf_vs_fieldFft Mtf Vs FieldB
Calculate polychromatic FFT MTF versus Y field for up to six frequencies.
Inputs: sampling, frequency1, frequency2, frequency3, +3 more.
zemax_fft_psfFft PsfC
Calculate a diffraction FFT point-spread function.
Inputs: field, sampling, wavelength, imageSampling.
zemax_field_curvature_distortionField Curvature DistortionC
Calculate tangential/sagittal field curvature and distortion.
Inputs: distortionType.
zemax_filter_glassesFilter GlassesC
Filter glasses by preferred state, optical coordinates, cost, TCE, coverage, and melt frequency.
Inputs: catalogs (required), wa, wn, wp, +17 more.
zemax_forbes_merit_functionForbes Merit FunctionC
Build explicit OPD operands using Forbes 1988 Gaussian quadrature sampling.
Inputs: arms, rings, wavelength, addComments, +6 more.
zemax_geometric_encircled_energyGeometric Encircled EnergyB
Calculate ray-based geometric encircled energy versus radius.
Inputs: sampling, useDashes, scatterRays, showDiffractionLimit, +1 more.
zemax_geometric_image_analysisGeometric Image AnalysisC
Run geometric image analysis and return/export the image grid.
Inputs: field, showAs, filePath, raysX1000, +1 more.
zemax_geometric_mtfGeometric MtfC
Calculate geometric MTF curves for all fields.
Inputs: wavelength, maxFrequency, multiplyByDiffractionLimit.
zemax_geometric_mtf_vs_fieldGeometric Mtf Vs FieldC
Calculate geometric MTF versus field for up to six frequencies.
Inputs: frequency1, frequency2, frequency3, frequency4, +2 more.
zemax_get_afocal_modeGet Afocal ModeB
Get the sequential afocal-mode setting.
Inputs: no named parameters.
zemax_get_apodizationGet ApodizationB
Get aperture apodization settings.
Inputs: no named parameters.
zemax_get_aspheric_surfaceGet Aspheric SurfaceC
Get Even Asphere conic and alpha1-alpha8 coefficients.
Inputs: surfaceNumber (required).
zemax_get_clear_semi_diameter_marginGet Clear Semi Diameter MarginC
Get the clear semi-diameter margin.
Inputs: no named parameters.
zemax_get_configurationGet ConfigurationA
Get number of configurations and current configuration.
Inputs: no named parameters.
zemax_get_configuration_operandsGet Configuration OperandsB
Get MCE operands and values across configurations.
Inputs: endRow, startRow.
zemax_get_extra_dataGet Extra DataC
Read surface Extra Data (XDAT) values.
Inputs: surfaceNumber (required), endParameter, startParameter.
zemax_get_glass_catalogsGet Glass CatalogsB
List glass catalog names installed in Glasscat.
Inputs: no named parameters.
zemax_get_glassesGet GlassesB
List glasses and optical/manufacturing properties from catalogs.
Inputs: catalogs (required).
zemax_get_merit_functionGet Merit FunctionC
Retrieve merit-function operands and optional calculated values.
Inputs: endRow, startRow, includeValues.
zemax_get_mtf_unitsGet Mtf UnitsB
Get MTF spatial-frequency units.
Inputs: no named parameters.
zemax_get_polarizationGet PolarizationB
Get the current optical system's default input polarization settings.
Inputs: no named parameters.
zemax_get_ray_aimingGet Ray AimingB
Get the ray-aiming setting.
Inputs: no named parameters.
zemax_get_surfaceGet SurfaceC
Get detailed data for a sequential surface.
Inputs: surfaceNumber (required).
zemax_get_surface_solvesGet Surface SolvesB
Get solve, pickup, and variable states for all surface properties.
Inputs: surfaceNumber (required).
zemax_get_systemGet SystemC
Get optical-system data, optionally including surfaces, fields, and wavelengths.
Inputs: includeFields, includeSurfaces, includeWavelengths.
zemax_get_system_unitsGet System UnitsB
Get the current optical system's lens units.
Inputs: no named parameters.
zemax_get_title_notesGet Title NotesA
Get the current optical system's title, notes, and author.
Inputs: no named parameters.
zemax_get_variablesGet VariablesB
Scan the system for optimization variables and constraint states.
Inputs: no named parameters.
zemax_global_searchGlobal SearchC
Run native global optimization with optional glass substitution.
Inputs: cores, algorithm, timeoutSeconds, solutionsToSave.
zemax_hammerHammerC
Run native Hammer optimization.
Inputs: cores, algorithm, automatic, timeoutSeconds, +1 more.
zemax_huygens_mtfHuygens MtfC
Calculate Huygens MTF by direct pupil integration.
Inputs: maximumFrequency (required), field, useDashes, imageDelta, +5 more.
zemax_huygens_psfHuygens PsfC
Calculate a Huygens point-spread function.
Inputs: field, wavelength, imageSampling, pupilSampling.
zemax_infoInfoC
Report the current session and optical-system information.
Inputs: no named parameters.
zemax_lateral_colorLateral ColorB
Calculate lateral color versus field.
Inputs: no named parameters.
zemax_lde_insert_surfaceLde Insert SurfaceC
Insert a surface at a zero-based LDE position.
Inputs: position (required).
zemax_lde_set_surfaceLde Set SurfaceC
Legacy wrapper for editing common surface properties.
Inputs: surface (required), radius, comment, material, +2 more.
zemax_lde_summaryLde SummaryA
Return a compact sequential Lens Data Editor prescription.
Inputs: no named parameters.
zemax_list_surface_typesList Surface TypesB
List surface types supported by the installed OpticStudio build.
Inputs: no named parameters.
zemax_load_merit_function_fileLoad Merit Function FileC
Load a .MF merit-function file.
Inputs: filePath (required).
zemax_longitudinal_aberrationLongitudinal AberrationB
Calculate longitudinal aberration versus pupil position.
Inputs: no named parameters.
zemax_mce_add_configMce Add ConfigC
Legacy wrapper to append a configuration.
Inputs: withPickups.
zemax_mce_add_operandMce Add OperandC
Legacy wrapper to append an MCE operand.
Inputs: operandType (required), param1, values.
zemax_mce_summaryMce SummaryD
Legacy compact MCE summary.
Inputs: no named parameters.
zemax_merit_valueMerit ValueB
Calculate the current merit-function value.
Inputs: no named parameters.
zemax_merit_wizardMerit WizardC
Legacy merit-function wizard wrapper.
Inputs: optimizationGoal.
zemax_multistart_optimizeMultistart OptimizeB
Start non-blocking randomized multistart constrained optimization.
Inputs: delta, resume, initialMu, maxTrials, +8 more.
zemax_multistart_statusMultistart StatusB
Poll multistart progress without blocking.
Inputs: no named parameters.
zemax_multistart_stopMultistart StopB
Request graceful stop of multistart optimization.
Inputs: no named parameters.
zemax_new_systemNew SystemB
Create a blank sequential or non-sequential optical system.
Inputs: sequential.
zemax_nsc_add_objectNsc Add ObjectC
Append a non-sequential object.
Inputs: comment, objectType.
zemax_nsc_clear_detectorsNsc Clear DetectorsA
Clear all or one non-sequential detector.
Inputs: objectNumber.
zemax_nsc_convert_to_nonsequentialNsc Convert To NonsequentialB
Convert or make the current optical system non-sequential.
Inputs: no named parameters.
zemax_nsc_convert_to_sequentialNsc Convert To SequentialC
Convert an eligible NSC group to sequential mode.
Inputs: lastObject, firstObject.
zemax_nsc_detector_dataNsc Detector DataC
Read full detector data and aggregate statistics.
Inputs: objectNumber (required), dataType, quantity, maxValues.
zemax_nsc_detector_pixelNsc Detector PixelC
Read one detector pixel or aggregate index.
Inputs: pixel (required), objectNumber (required), dataType, quantity.
zemax_nsc_detector_viewerNsc Detector ViewerC
Run bounded Detector Viewer extraction for scalar or RGB data.
Inputs: objectNumber (required), scale, filter, showAs, +3 more.
zemax_nsc_get_objectNsc Get ObjectB
Get a non-sequential object and its common/type-specific data.
Inputs: objectNumber (required).
zemax_nsc_get_object_parameterNsc Get Object ParameterC
Get a type-specific NSC object parameter.
Inputs: parameter (required), objectNumber (required).
zemax_nsc_get_source_spectrumNsc Get Source SpectrumC
Get typed spectrum settings for an NSC source object.
Inputs: objectNumber (required).
zemax_nsc_insert_objectNsc Insert ObjectC
Insert a non-sequential object.
Inputs: objectNumber (required), objectType.
zemax_nsc_load_detectorNsc Load DetectorC
Load detector data from a type-compatible detector data file.
Inputs: filePath (required), objectNumber (required), appendData.
zemax_nsc_polar_detector_dataNsc Polar Detector DataC
Read bounded full Detector Polar data.
Inputs: quantity (required), objectNumber (required), maxValues.
zemax_nsc_polar_detector_pixelNsc Polar Detector PixelC
Read one Detector Polar pixel or aggregate value.
Inputs: pixel (required), quantity (required), objectNumber (required).
zemax_nsc_ray_traceNsc Ray TraceC
Run a non-sequential ray trace.
Inputs: rays, split, saveZrd, scatter, +5 more.
zemax_nsc_remove_objectNsc Remove ObjectC
Remove a non-sequential object.
Inputs: objectNumber (required).
zemax_nsc_save_detectorNsc Save DetectorC
Save detector data to a type-compatible detector data file.
Inputs: filePath (required), objectNumber (required), overwrite.
zemax_nsc_set_objectNsc Set ObjectC
Set common placement, material, comment, and reference properties of an NSC object.
Inputs: objectNumber (required), comment, material, refObject, +7 more.
zemax_nsc_set_object_parameterNsc Set Object ParameterC
Set a type-specific NSC object parameter.
Inputs: value (required), parameter (required), objectNumber (required).
zemax_nsc_set_source_spectrumNsc Set Source SpectrumC
Set typed spectrum settings for an NSC source object.
Inputs: mode (required), settings (required), objectNumber (required).
zemax_nsc_summaryNsc SummaryB
List non-sequential objects and common properties.
Inputs: no named parameters.
zemax_opd_fanOpd FanB
Calculate optical-path-difference fans for all fields and wavelengths.
Inputs: no named parameters.
zemax_open_fileOpen FileC
Open a Zemax .zmx or .zos lens file.
Inputs: path, filePath.
zemax_operand_helpOperand HelpC
Get detailed documentation for an optimization operand.
Inputs: operandType (required).
zemax_optimization_wizardOptimization WizardC
Construct a merit function using Optimization Wizard criteria.
Inputs: arms, rings, gridSize, criterion, +9 more.
zemax_optimizeOptimizeC
Run native local optimization.
Inputs: cores, cycles, method, algorithm.
zemax_popPopC
Run Physical Optics Propagation (POP).
Inputs: endSurface (required), startSurface (required), field, beamType, +6 more.
zemax_pupil_aberration_fanPupil Aberration FanB
Calculate entrance-pupil aberration fans.
Inputs: no named parameters.
zemax_quick_focusQuick FocusC
Run Quick Focus to adjust back focal distance.
Inputs: criterion, useCentroid.
zemax_ray_fanRay FanB
Calculate transverse ray aberration fans for all fields and wavelengths.
Inputs: no named parameters.
zemax_ray_traceRay TraceC
Trace one normalized sequential ray.
Inputs: hx, hy, px, py, +2 more.
zemax_relative_illuminationRelative IlluminationB
Calculate relative illumination and effective F-number versus field.
Inputs: no named parameters.
zemax_remove_material_catalogRemove Material CatalogC
Remove a material catalog from the current optical system.
Inputs: catalogName (required).
zemax_remove_operandRemove OperandB
Remove a merit-function operand.
Inputs: row (required).
zemax_remove_surfaceRemove SurfaceC
Remove a sequential surface.
Inputs: surfaceNumber (required).
zemax_restartRestartA
Restart the OpticStudio connection when the current session is unhealthy.
Inputs: no named parameters.
zemax_rms_spotRms SpotC
Calculate an RMS spot radius for a normalized field point.
Inputs: hx, hy, useGrid, sampling, +2 more.
zemax_run_analysisRun AnalysisC
Run an arbitrary AnalysisIDM by name and extract sample results.
Inputs: analysisType (required).
zemax_run_tolerancingRun TolerancingC
Run bounded Monte Carlo tolerancing.
Inputs: monteCarloRuns, timeoutSeconds.
zemax_save_fileSave FileB
Save the current lens, optionally using Save As.
Inputs: path, filePath.
zemax_save_merit_function_fileSave Merit Function FileC
Save the merit function to a .MF file.
Inputs: filePath (required).
zemax_scale_lensScale LensC
Scale a disposable lens by factor or convert it to another lens unit.
Inputs: mode (required), scaleFactor, scaleToUnit, lastComponent, +2 more.
zemax_search_operandsSearch OperandsB
Search operand names and descriptions.
Inputs: query (required), category, maxResults.
zemax_seidel_coefficientsSeidel CoefficientsC
Calculate third-order Seidel and chromatic aberration coefficients.
Inputs: wavelength.
zemax_set_afocal_modeSet Afocal ModeA
Enable or disable sequential afocal mode.
Inputs: afocalMode (required).
zemax_set_apertureSet ApertureC
Set the system aperture type and value.
Inputs: value (required), apertureType.
zemax_set_apodizationSet ApodizationC
Set aperture apodization type and factor.
Inputs: factor (required), apodizationType (required).
zemax_set_aspheric_surfaceSet Aspheric SurfaceC
Convert to Even Asphere and set conic and alpha coefficients.
Inputs: surfaceNumber (required), conic, alpha1, alpha2, +15 more.
zemax_set_clear_semi_diameter_marginSet Clear Semi Diameter MarginC
Set the clear semi-diameter margin.
Inputs: margin (required).
zemax_set_configuration_operand_valueSet Configuration Operand ValueC
Set a value or pickup solve for one configuration operand cell.
Inputs: operandRow (required), configurationNumber (required), value, offset, +2 more.
zemax_set_current_configurationSet Current ConfigurationC
Set the active configuration.
Inputs: configurationNumber (required).
zemax_set_extra_dataSet Extra DataC
Set one or more surface Extra Data (XDAT) values.
Inputs: values (required), surfaceNumber (required).
zemax_set_fieldsSet FieldsC
Set all field points and the field coordinate type.
Inputs: fields, points, fieldType.
zemax_set_mtf_unitsSet Mtf UnitsC
Set MTF spatial-frequency units.
Inputs: mtfUnits (required).
zemax_set_number_of_configurationsSet Number Of ConfigurationsC
Set the number of configurations.
Inputs: numberOfConfigurations (required).
zemax_set_number_of_fieldsSet Number Of FieldsC
Set the number of field rows.
Inputs: numberOfFields (required).
zemax_set_number_of_wavelengthsSet Number Of WavelengthsC
Set the number of wavelength rows.
Inputs: numberOfWavelengths (required).
zemax_set_polarizationSet PolarizationC
Update the current optical system's default input polarization settings.
Inputs: jx, jy, method, xPhase, +3 more.
zemax_set_ray_aimingSet Ray AimingB
Set ray aiming to Off, Paraxial, or Real.
Inputs: rayAiming (required).
zemax_set_surfaceSet SurfaceC
Modify common properties and variable states of a sequential surface.
Inputs: surfaceNumber (required), conic, isStop, radius, +9 more.
zemax_set_surface_parameterSet Surface ParameterC
Set a type-specific surface parameter.
Inputs: value (required), parameter (required), surfaceNumber (required).
zemax_set_surface_solveSet Surface SolveD
Set the solve type for a surface property.
Inputs: property (required), solveType (required), surfaceNumber (required), height, +13 more.
zemax_set_surface_typeSet Surface TypeC
Change a surface to a named Zemax surface type.
Inputs: surfaceType (required), surfaceNumber (required).
zemax_set_system_unitsSet System UnitsC
Set the current optical system's lens units.
Inputs: lensUnits (required).
zemax_set_title_notesSet Title NotesC
Update the current optical system's title, notes, and author.
Inputs: notes, title, author.
zemax_set_variableSet VariableC
Legacy wrapper to make a surface cell variable.
Inputs: surface (required), cell.
zemax_set_variable_constraintsSet Variable ConstraintsC
Set hard min/max constraints on optimization variables.
Inputs: constraints (required).
zemax_set_wavelengthsSet WavelengthsB
Replace wavelength definitions and select the primary wavelength.
Inputs: primary, wavelengths, wavelengthsUm, primaryWavelength.
zemax_spot_diagramSpot DiagramC
Calculate spot-size analysis for one field.
Inputs: field, rings, wavelength.
zemax_spot_rmsSpot RmsB
Legacy RMS spot radius analysis for every field.
Inputs: no named parameters.
zemax_statusStatusA
Return connection, ownership, license, and current-system status.
Inputs: no named parameters.
zemax_tde_summaryTde SummaryB
Return tolerance operands and bounds.
Inputs: no named parameters.
zemax_tolerance_wizardTolerance WizardC
Populate default sequential tolerances.
Inputs: no named parameters.
zemax_zrd_readZrd ReadC
Read a bounded nested ray and segment sample from a ZRD.
Inputs: filePath (required), filter, maxRays, maxSegments.
zemax_zrd_summaryZrd SummaryB
Stream an existing ZRD and return bounded aggregate metadata.
Inputs: filePath (required), filter, maxRaysToScan, maxSegmentsToScan.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 143 tools
Many tools overlap heavily, including legacy wrappers alongside modern equivalents (e.g., zemax_set_surface vs zemax_lde_set_surface, zemax_optimization_wizard vs zemax_merit_wizard) and multiple spot/MTF/detector variants. Descriptions sometimes clarify legacy status, but the boundaries remain unclear and misselection is likely.
Almost all tools use a consistent zemax_ prefix and snake_case, and getter/setter pairs follow predictable verb_noun patterns. However, many analysis tools use noun phrases (e.g., zemax_fft_mtf, zemax_ray_fan) and legacy wrappers introduce minor naming deviations.
With 143 tools, this server is far beyond any reasonable MCP tool surface, even for a complex optical design domain. The set includes many legacy wrappers and overlapping analysis/detector variants, making it an extreme mismatch rather than a well-scoped collection.
The surface covers sequential and non-sequential systems, surface/object CRUD, optimization, tolerancing, numerous analyses, file lifecycle, and configuration handling. No obvious core gaps are apparent for the stated optical design purpose.
Maintenance
Related MCP Connectors
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceSafety-first MCP server enabling AI assistants to drive Zemax OpticStudio sequential-mode optical design workflows, including a mock backend for validation.1-
- FlicenseNot gradedqualityCmaintenanceMCP server that integrates local LLMs (via Ollama) with SolidWorks through its COM API, enabling read-only inspection of features, dimensions, equations, mass properties, and file exports. It supports models like Qwen3 and plans future expansion to editing and generation.-
- FlicenseNot gradedqualityCmaintenanceAn MCP server that lets supported AI clients like ChatGPT and Claude use locally authorised Windows tools, files, project tasks, commands, and local state, with configurable per-client authority and global access modes.-
- AlicenseCqualityFmaintenanceThis MCP server gives an AI coding host controlled, client-agnostic access to a local machine's developer capabilities: transactional file edits, shell and PTY execution, Git and project inspection, language-server operations, isolated browser automation, Windows UI automation, VS Code state, durable jobs, and checkpoints, all bounded by filesystem root allowlisting and resource admission controls. It speaks standard MCP over stdio, Streamable HTTP, and legacy HTTP+SSE, and can also run headless as a long-lived job runner without any hosted model vendor.114ISC