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

• Current MCP surface

• Prerequisites

• Download from GitHub

• Install and validate

• Run the server

• Configure MCP clients

• Runtime configuration

• Testing and development

• Security and proprietary files

Related MCP server: mcp-opentym

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:

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

git clone https://github.com/YonggangG/Zemax_MCP_Server.git
cd Zemax_MCP_Server

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

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

• examples/cherry-studio.json

• examples/claude-desktop.json

• examples/claude-code.mcp.json

• examples/extension-env.json

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:

{
  "name": "zemax",
  "type": "stdio",
  "command": "uv",
  "args": [
    "--directory",
    "C:\\path\\to\\Zemax_MCP_Server",
    "run",
    "zemax-mcp",
    "serve"
  ],
  "env": {
    "ZEMAX_MCP_CONNECTION_MODE": "standalone"
  }
}

If Cherry Studio cannot resolve uv, use the checkout executable instead:

{
  "name": "zemax",
  "type": "stdio",
  "command": "C:\\path\\to\\Zemax_MCP_Server\\.venv\\Scripts\\zemax-mcp.exe",
  "args": ["serve"],
  "env": {
    "ZEMAX_MCP_CONNECTION_MODE": "standalone"
  }
}

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.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"
      }
    }
  }
}

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:

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

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.