Skip to main content
Glama

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/manifest

  • zemax://catalog/capabilities

  • zemax://session/status

And these workflow prompts:

  • zemax_analyze_system

  • zemax_optimize_system

  • zemax_build_nsc_system

Inspect the source-of-truth report with:

uv run zemax-mcp manifest
uv run zemax-mcp report --check

See 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 --version

Live 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_Server

If 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 --frozen

Option 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 --check

Start the default stdio server with:

uv run zemax-mcp serve

The 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 --dev

Optional direct executable

After uv sync, the checkout contains a console executable at:

C:\path\to\Zemax_MCP_Server\.venv\Scripts\zemax-mcp.exe

This 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 doctor

What 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 serve

Calling zemax-mcp without a subcommand also starts the stdio server.

Transports

Transport

Example

Intended use

stdio

uv run zemax-mcp serve

Default and recommended for Cherry Studio, Claude Desktop, and Claude Code.

SSE

uv run zemax-mcp serve --transport sse --host 127.0.0.1 --port 8000

Local clients that specifically require the legacy SSE transport.

Streamable HTTP

uv run zemax-mcp serve --transport streamable-http --host 127.0.0.1 --port 8000

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: zemax

  • Type/transport: stdio or local command

  • Command: uv

  • Arguments: --directory, C:\path\to\Zemax_MCP_Server, run, zemax-mcp, serve

  • Environment: 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_DIR and ZEMAX_MCP_ZOSAPI_PATH are 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.

Cherry Studio MCP server settings example

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

Add 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_DIR and ZEMAX_MCP_ZOSAPI_PATH are 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 list

Or register the direct executable:

claude mcp add --transport stdio zemax -- C:\path\to\Zemax_MCP_Server\.venv\Scripts\zemax-mcp.exe serve
claude mcp list

For 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 serve

or:

C:\path\to\Zemax_MCP_Server\.venv\Scripts\zemax-mcp.exe serve

Map 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

ZEMAX_MCP_INSTALL_DIR

OpticStudio installation root

auto-discover

ZEMAX_MCP_ZOSAPI_PATH

ZOS-API directory or full path to ZOSAPI.dll

auto-discover

ZEMAX_MCP_CONNECTION_MODE

standalone or extension

standalone

ZEMAX_MCP_INSTANCE_ID

Interactive Extension instance ID

0

ZEMAX_MCP_WORKER_NAME

Internal serialized ZOS worker name

zemax-zos-worker

ZEMAX_MCP_GLASSCAT_DIR

Explicit Glasscat search root(s), separated by the Windows path separator

unset

ZEMAX_MCP_ZEMAX_ROOT

Zemax root whose Glasscat subdirectory should be searched

unset

ZEMAX_MCP_ALLOW_DESTRUCTIVE

Must be 1 in addition to explicit tool confirmation for destructive Design Lockdown

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

standalone

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.

extension

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 assemblies

Key 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 dist

Live 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_zemax

Review 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 --check

See 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 tools
zemax_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_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

    C2.7/5.0

    Scored across 143 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Safety-first MCP server enabling AI assistants to drive Zemax OpticStudio sequential-mode optical design workflows, including a mock backend for validation.
      1
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      MCP 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.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      An 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.
      -
    • A
      license
      C
      quality
      F
      maintenance
      This 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.
      114
      ISC