OpticStudio MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to interact with Zemax OpticStudio for optical design tasks. Works with Claude Desktop, Claude Code, and Ollama (local LLMs).

Table of Contents

• Prerequisites
• Quick Start
• Step 1: Build the Solution
• Step 2: Fix Binaries (Configure ZOS-API Path)
• Step 3: Configure Your AI Client
  • Claude Desktop Setup
  • Claude Code Setup
  • Ollama Setup (Local LLMs)
• Connection Modes
• Non-Sequential (NSC) Mode
• Tool Reference
  • System Tools
  • Lens Data Tools
  • Analysis Tools
  • Optimization Tools
  • Constrained Optimization Tools
  • Configuration Tools
  • System Settings Tools
  • Glass Catalog Tools
  • Non-Sequential Tools
• Resources
• Prompts
• Example Workflow
• Project Structure
• Troubleshooting
• License

---

Prerequisites

• Windows (required - OpticStudio is Windows-only)
• .NET Framework 4.8 (included with Windows 10/11)
• Zemax OpticStudio with a valid license (any recent version)
• One of the following AI clients:
  • Claude Code (recommended for most users) - see Installation Guide
  • Claude Desktop (GUI alternative) - see Installation Guide
  • Ollama (for local/offline LLM usage)

---

Quick Start

1. Build the solution in Visual Studio or via command line
2. Run FixBinaries to point the project at your OpticStudio installation
3. Run ConfigureClaudeMCP to automatically set up Claude Desktop and/or Claude Code
4. Start using OpticStudio through your AI assistant

---

Step 1: Build the Solution

Open a Developer Command Prompt or terminal and run:

cd C:\GIT\OpticStudioMCPServer
dotnet build

Or open OpticStudioMCPServer.sln in Visual Studio and build the solution (Ctrl+Shift+B).

This builds all projects:

• ZemaxMCP.Server - The MCP server (main executable)
• ZemaxMCP.Core - Core library (session management, models)
• ZemaxMCP.Documentation - Operand reference database
• FixBinaries - ZOS-API path configuration tool
• ConfigureClaudeMCP - Claude Desktop/Code setup tool
• ConfigureOllama - Ollama bridge setup tool
• ZemaxMCP.OllamaBridge - Ollama-to-MCP bridge

---

Step 2: Fix Binaries (Configure ZOS-API Path)

The MCP server needs to reference three DLLs from your OpticStudio installation: ZOSAPI.dll, ZOSAPI_Interfaces.dll, and ZOSAPI_NetHelper.dll. The FixBinaries tool configures this automatically.

Using the FixBinaries GUI

1. Run FixBinaries.exe from src\FixBinaries\bin\Debug\ (or Release)
2. The tool automatically scans for OpticStudio installations in:
   • C:\Program Files\Ansys Zemax OpticStudio*
   • C:\Program Files\Zemax OpticStudio*
   • C:\Program Files\OpticStudio*
3. Select your installation from the list (or click Browse to locate it manually)
4. Verify all three DLLs show green checkmarks:
   • ZOSAPI.dll
   • ZOSAPI_Interfaces.dll
   • ZOSAPI_NetHelper.dll
5. Click Generate ZemaxPaths.props

This creates a ZemaxPaths.props file at the repository root that tells MSBuild where to find the ZOS-API DLLs. After generating, rebuild the solution so the references resolve correctly.

Manual Alternative

If you prefer, create ZemaxPaths.props in the repository root manually:

  
    C:\Program Files\Ansys Zemax OpticStudio 2024 R1\
  

Replace the path with your actual OpticStudio installation directory (include trailing backslash).

Building distributable .exe file

To build a distributable .exe file using Costura that packs all of the .dll files (except OpticStudio’s and .NET itself) into the .exe for easy distribution, build in release mode (after generating ZemaxPaths.props):

dotnet build -c Release

The file src/ZemaxMCP.Server/bin/Release/net48/ZemaxMCP.Server.exe will run as-is on any machine with OpticStudio and .NET installed.

---

Step 3: Configure Your AI Client

Claude Desktop Setup

New to Claude Desktop? See the full Claude Desktop Installation Guide for step-by-step instructions including account creation, downloading, and installation.

Using the ConfigureClaudeMCP GUI (Recommended)

1. Run ConfigureClaudeMCP.exe from src\ConfigureClaudeMCP\bin\Debug\
2. The tool auto-detects ZemaxMCP.Server.exe (or click Browse to locate it)
3. Click Configure Claude Desktop
4. Restart Claude Desktop

The tool edits %APPDATA%\Claude\claude_desktop_config.json to add the zemax-mcp server entry.

Manual Configuration

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "zemax-mcp": {
      "command": "C:\\GIT\\OpticStudioMCPServer\\src\\ZemaxMCP.Server\\bin\\Debug\\net48\\ZemaxMCP.Server.exe",
      "args": []
    }
  }
}

Restart Claude Desktop after saving.

---

Claude Code Setup

New to Claude Code? See the full Claude Code Installation Guide for step-by-step instructions including installing Node.js, setting up Claude Code, and signing in.

Using the ConfigureClaudeMCP GUI (Recommended)

1. Run ConfigureClaudeMCP.exe from src\ConfigureClaudeMCP\bin\Debug\
2. Click Configure Claude Code
3. The tool runs: claude mcp add --transport stdio --scope user zemax-mcp -- "path\to\ZemaxMCP.Server.exe"

Manual Configuration (CLI)

claude mcp add --transport stdio --scope user zemax-mcp -- "C:\GIT\OpticStudioMCPServer\src\ZemaxMCP.Server\bin\Debug\net48\ZemaxMCP.Server.exe"

To verify the server is registered:

claude mcp list

To remove:

claude mcp remove --scope user zemax-mcp

Skipping Tool Permissions

By default, Claude Code will prompt you to approve each MCP tool call. To skip these prompts and allow all tool calls automatically, start Claude Code with:

claude --dangerously-skip-permissions

Warning: This bypasses all permission checks. Only use this in trusted environments where you are comfortable with the AI calling OpticStudio tools without confirmation.

---

Ollama Setup (Local LLMs)

The Ollama Bridge lets you use OpticStudio with local LLMs running on your machine via Ollama. No cloud API keys needed.

Prerequisites

1. Install Ollama
2. Pull a model with tool-calling support:

   ollama pull llama3.1
   

   Other recommended models: mistral, qwen2.5-coder
3. Make sure Ollama is running: ollama serve

Using the ConfigureOllama GUI (Recommended)

1. Run ConfigureOllama.exe from src\ConfigureOllama\bin\Debug\
2. The tool auto-detects:
   • ZemaxMCP.Server.exe path
   • ZemaxMCP.OllamaBridge.exe path
   • Running Ollama instance and available models
3. Select a model from the dropdown (or pull a new one)
4. Choose an action:
   • Launch Bridge - Start an interactive chat session immediately
   • Create Desktop Shortcut - Make a shortcut for quick access
   • Create Batch File - Save a .bat file to launch later

Manual Launch (CLI)

Set environment variables and run the bridge:

set OLLAMA_MODEL=llama3.1
set OLLAMA_URL=http://localhost:11434
ZemaxMCP.OllamaBridge.exe "path\to\ZemaxMCP.Server.exe"

Or pass the server path as a command line argument:

ZemaxMCP.OllamaBridge.exe C:\GIT\OpticStudioMCPServer\src\ZemaxMCP.Server\bin\Debug\net48\ZemaxMCP.Server.exe

If no model is specified, the bridge will list available models and let you pick one interactively.

How the Ollama Bridge Works

The bridge acts as an intermediary:

1. Starts the MCP server as a subprocess (stdio transport)
2. Discovers all available tools from the MCP server
3. Auto-connects to OpticStudio in standalone mode
4. Converts MCP tools to Ollama’s tool-calling format
5. Provides an interactive chat loop where the LLM can call OpticStudio tools

Type tools during a chat session to list all available tools, or quit to exit.

---

Connection Modes

The MCP server supports two connection modes:

To use Extension mode:

1. Open OpticStudio
2. Go to Programming > Interactive Extension
3. Tell the AI to connect in extension mode: “Connect to OpticStudio in extension mode”

The AI defaults to standalone mode unless you explicitly request extension mode.

---

Non-Sequential (NSC) Mode

In addition to classic sequential ray tracing, the MCP server supports non-sequential simulation through the Non-sequential Component Editor (NCE). Non-sequential mode is used for problems where rays can hit objects in any order and may split, scatter, or reflect — such as illumination design, photometry, stray-light analysis, light pipes, and other non-imaging optics.

The system operates in one of two modes:

Switch modes by telling the AI, e.g. “Switch to non-sequential mode”, which calls zemax_set_system_mode. Once in non-sequential mode you build the system from objects (sources, detectors, lenses, reflectors, etc.) rather than surfaces, run a non-sequential ray trace, and read results back from detector objects.

To discover the exact object type names available in your OpticStudio installation, ask the AI to list them (zemax_nsc_list_object_types) and use the returned names verbatim when adding objects.

A typical non-sequential interaction with the AI assistant looks like:

1. Connect: “Connect to OpticStudio” (uses standalone mode by default)
2. Switch mode: “Switch to non-sequential mode”
3. Discover types: “List the available source and detector object types”
4. Add a source: “Add a Source Point at z = 0”
5. Add a detector: “Add a Detector Rectangle 50mm downstream”
6. Configure: “Set the source to 1,000,000 analysis rays”
7. Trace: “Run a non-sequential ray trace with 4 cores”
8. Read results: “Show me the total flux and irradiance on the detector”
9. Save: “Save the file”

See the Non-Sequential Tools table below for the full list of available tools and their parameters.

---

Tool Reference

System Tools

Lens Data Tools

Analysis Tools

Optimization Tools

Constrained Optimization Tools

Custom MCP-implemented optimization algorithms that run entirely in the MCP server. These are not built-in Zemax optimizers — they use ZOSAPI only to get/set variable values and evaluate the merit function, while the optimization logic (Levenberg-Marquardt with bound constraints) runs server-side.

Workflow

1. Identify variables — Use zemax_get_variables to scan the system for all Variable solves and get their variable numbers.
2. Set constraints — Use zemax_set_variable_constraints to define min/max bounds on variables. Constraints are persisted alongside the .zmx file in a sidecar .constraints file and are automatically reloaded when the file is opened.
3. Optimize — Run either:
   • zemax_constrained_optimize for a single local optimization (blocking), or
   • zemax_multistart_optimize for a randomized multistart search (non-blocking).
4. Monitor (multistart only) — Poll with zemax_multistart_status and cancel with zemax_multistart_stop.

Tool Reference

Local Optimization (zemax_constrained_optimize)

Runs a bound-constrained Levenberg-Marquardt (LM) optimizer. Variables are clamped to their min/max bounds at each iteration. Optionally uses Broyden rank-1 Jacobian updates to reduce the number of merit function evaluations. When Broyden converges early, the optimizer can auto-restart with a fresh Jacobian (controlled by maxRestarts).

Key features:

• Finite-difference Jacobian with configurable step size (delta)
• Broyden rank-1 updates between full Jacobian rebuilds
• Automatic restarts when convergence stalls
• Bound clamping at every iteration

Multistart Optimization (zemax_multistart_optimize)

Launches a non-blocking multistart search that returns immediately. Each trial randomizes continuous variables within their bound ranges (by randomizationPercent of the bound width), optionally substitutes glasses on surfaces with Material Substitute solves, then runs a short LM optimization. The best result across all trials is kept.

Key features:

• Non-blocking — returns immediately; use zemax_multistart_status to poll progress
• Initial LM phase — runs a full LM optimization from the current starting point before trials begin
• Auto-save — saves improving solutions to a _multistart/ folder alongside the original file
• Constrained-only mode (constrainedOnly) — only randomize variables that have constraints, leaving unconstrained variables at their current best values
• Glass substitution — randomly swaps glasses on surfaces with Material Substitute solves at a configurable probability
• Resume — continue accumulating trials from a previous run, skipping the initial LM phase
• Cancellation — use zemax_multistart_stop to gracefully cancel; the optimizer finishes the current trial and restores the best state

Configuration Tools

System Settings Tools

Glass Catalog Tools

Non-Sequential Tools

Tools for building and simulating non-sequential systems via the Non-sequential Component Editor (NCE) — illumination, photometry, stray light, and non-imaging optics. Switch the system to non-sequential mode first with zemax_set_system_mode.

---

Resources

MCP resources provide read-only access to system state:

---

Prompts

Built-in prompt templates for common workflows:

---

Example Workflow

Here is a typical interaction with the AI assistant:

1. Connect: “Connect to OpticStudio” (uses standalone mode by default)
2. Open a file: “Open C:\Lenses\MyDoublet.zmx”
3. Review: “Show me the system data”
4. Analyze: “Run a spot diagram” or “Calculate the MTF at 100 cycles/mm”
5. Modify: “Set surface 2 radius to 50mm and make it variable”
6. Optimize: “Build an RMS spot merit function and optimize”
7. Evaluate: “Show me Seidel coefficients and spot size”
8. Save: “Save the file”

Screenshots

Connecting to OpticStudio from Claude Code:

Opening a Zemax file and querying the merit function:

Hammer optimization results:

---

Project Structure

OpticStudioMCPServer/
|-- src/
|   |-- ZemaxMCP.Server/          # MCP server (main executable)
|   |-- ZemaxMCP.Core/            # Core library (session, models, services)
|   |-- ZemaxMCP.Documentation/   # Operand reference database
|   |-- FixBinaries/              # GUI tool to configure ZOS-API DLL paths
|   |-- ConfigureClaudeMCP/       # GUI tool to set up Claude Desktop/Code
|   |-- ConfigureOllama/          # GUI tool to set up Ollama bridge
|   |-- ZemaxMCP.OllamaBridge/    # Ollama-to-MCP bridge (console app)
|-- Directory.Build.props         # Shared build properties
|-- ZemaxPaths.props              # ZOS-API path (generated by FixBinaries)
|-- OpticStudioMCPServer.sln      # Visual Studio solution
|-- README.md

---

Troubleshooting

“ZOSAPI.dll not found” or build errors

Run FixBinaries to generate ZemaxPaths.props, then rebuild the solution.

Tools not loading in Claude

1. Verify the server is registered: claude mcp list (for Claude Code)
2. Check %APPDATA%\Claude\claude_desktop_config.json (for Claude Desktop)
3. Restart your AI client after configuration changes
4. Check the server log at src\ZemaxMCP.Server\bin\Debug\net48\logs\

“Connection failed” when connecting to OpticStudio

• Standalone mode: Make sure OpticStudio is installed and licensed
• Extension mode: Open OpticStudio first, then go to Programming > Interactive Extension before connecting

Ollama bridge cannot find the MCP server

Set the MCP_SERVER_PATH environment variable to the full path of ZemaxMCP.Server.exe, or pass it as the first command-line argument.

Known Issues

• zemax_optimization_wizard: May not work correctly in all cases. Use zemax_forbes_merit_function or zemax_add_operand as alternatives.

---

License

MIT License - Copyright © 2026 Javier A Ruiz. See LICENSE for details. Note: A valid Zemax OpticStudio license is required for operation.