Lumerical FDTD MCP

Control Ansys Lumerical FDTD from an MCP-capable AI client such as Codex.

This project exposes a small MCP server around Lumerical's bundled Python API, lumapi.py. It can detect a local Lumerical installation, launch the GUI, open persistent FDTD sessions, run Lumerical script, load/save .fsp projects, and retrieve variables back to the client.

Why

The goal is to make photonic simulation workflows easier to drive from an AI coding agent:

• Build and edit FDTD structures from natural-language instructions.
• Run Lumerical script snippets through MCP tools.
• Keep FDTD sessions alive across multiple tool calls.
• Extract variables and small numerical results back into the agent workflow.
• Support qBIC / metasurface iteration without manually copying scripts between windows.

Tools

The server exposes:

• fdtd_detect_tool: detect Lumerical paths, executables, and lumapi.py.
• fdtd_launch_gui_tool: launch the Lumerical launcher or FDTD Solutions GUI.
• fdtd_open_session_tool: open a persistent lumapi.FDTD() session.
• fdtd_eval_script_tool: run Lumerical script in that session.
• fdtd_eval_script_get_tool: run script and return a named variable.
• fdtd_get_variable_tool / fdtd_put_variable_tool: move variables between MCP client and FDTD.
• fdtd_load_project_tool / fdtd_save_project_tool: load and save .fsp projects.
• fdtd_run_script_file_tool: run an .lsf script file.
• fdtd_run_simulation_tool: call run;.
• fdtd_close_session_tool: close a session.
• fdtd_list_sessions_tool: list open server-side sessions.
• fdtd_command_docs_tool: search bundled command docs from Lumerical's docs.json.

Requirements

• Windows with Ansys Lumerical installed.
• Python 3.10 or newer.
• An MCP-capable client.

The default example path targets:

D:\Program Files\Lumerical\v202

Change the environment variables if your installation is elsewhere.

Install

From this folder:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e .

Copy .env.example to .env and edit paths if needed:

Copy-Item .env.example .env

Codex MCP Config

Add a server entry like this to your Codex MCP configuration:

[mcp_servers.lumerical_fdtd]
command = "C:\\path\\to\\lumerical-fdtd-mcp\\.venv\\Scripts\\python.exe"
args = ["C:\\path\\to\\lumerical-fdtd-mcp\\server.py"]
cwd = "C:\\path\\to\\lumerical-fdtd-mcp"

[mcp_servers.lumerical_fdtd.env]
LUMERICAL_ROOT = "D:\\Program Files\\Lumerical\\v202"
LUMERICAL_LAUNCHER = "D:\\Program Files\\Lumerical\\v202\\bin\\launcher.exe"
LUMERICAL_FDTD_EXE = "D:\\Program Files\\Lumerical\\v202\\bin\\fdtd-solutions.exe"
PYTHONWARNINGS = "ignore"

Restart the MCP client after changing the configuration.

Smoke Test

After the MCP server is available, run:

1. fdtd_detect_tool
2. fdtd_open_session_tool with hide=true
3. fdtd_eval_script_get_tool with:

code: mcp_x=2+3;
return_var: mcp_x

Expected returned value:

5

Then close the session with fdtd_close_session_tool.

Notes

This project does not include Ansys Lumerical binaries, licenses, simulation files, solver output, or private local configuration. It only provides the MCP bridge code.