Lumerical MCP Server (v241) 配置与排障总结

1. 项目概述

lumerical-mcp-main 是一个 MCP (Model Context Protocol) 服务器，通过 Python API (lumapi.py) 控制 Ansys Lumerical 系列产品（FDTD、MODE、INTERCONNECT、DEVICE）。

项目	路径/版本
Lumerical 版本	v241
Lumerical 安装路径	`D:\Program Files\Lumerical\v241`
MCP 项目路径	`D:\Compilers\MCP_SERVERS\lumerical-mcp-main`
MCP 客户端	Kimi Code CLI
Python 虚拟环境	`.venv`（位于项目目录下）

2. 安装与配置

2.1 创建 `.env` 文件

在项目根目录 lumerical-mcp-main 下创建 .env，指定 Lumerical v241 路径：

ini 复制代码

LUMERICAL_ROOT=D:\Program Files\Lumerical\v241
LUMERICAL_LAUNCHER=D:\Program Files\Lumerical\v241\bin\launcher.exe
LUMERICAL_FDTD_EXE=D:\Program Files\Lumerical\v241\bin\fdtd-solutions.exe
LUMERICAL_MODE_EXE=D:\Program Files\Lumerical\v241\bin\mode-solutions.exe
LUMERICAL_INTERCONNECT_EXE=D:\Program Files\Lumerical\v241\bin\interconnect.exe
LUMERICAL_DEVICE_EXE=D:\Program Files\Lumerical\v241\bin\device.exe

# Ansys 许可证环境变量（必须同时写入 mcp.json）
ANSYSLMD_LICENSE_FILE=1055@localhost
ANSYSLIC_DIR=C:\Program Files\ANSYS Inc\Shared Files\Licensing
ANSYS241_DIR=D:\Program Files\ANSYS Inc\v241\ANSYS
LSTC_LICENSE=Ansys

2.2 安装 Python 依赖

在项目目录下执行：

powershell 复制代码

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

2.3 Kimi Code CLI MCP 配置

配置文件路径 ：C:\Users\XXXXX\.kimi\mcp.json

json 复制代码

{
  "mcpServers": {
    "lumerical": {
      "command": "D:\\Compilers\\MCP_SERVERS\\lumerical-mcp-main\\.venv\\Scripts\\python.exe",
      "args": [
        "D:\\Compilers\\MCP_SERVERS\\lumerical-mcp-main\\server.py"
      ],
      "env": {
        "LUMERICAL_ROOT": "D:\\Program Files\\Lumerical\\v241",
        "LUMERICAL_LAUNCHER": "D:\\Program Files\\Lumerical\\v241\\bin\\launcher.exe",
        "LUMERICAL_FDTD_EXE": "D:\\Program Files\\Lumerical\\v241\\bin\\fdtd-solutions.exe",
        "LUMERICAL_MODE_EXE": "D:\\Program Files\\Lumerical\\v241\\bin\\mode-solutions.exe",
        "LUMERICAL_INTERCONNECT_EXE": "D:\\Program Files\\Lumerical\\v241\\bin\\interconnect.exe",
        "LUMERICAL_DEVICE_EXE": "D:\\Program Files\\Lumerical\\v241\\bin\\device.exe",
        "PYTHONWARNINGS": "ignore",
        "PYTHONIOENCODING": "utf-8",
        "ANSYSLMD_LICENSE_FILE": "1055@localhost",
        "ANSYSLIC_DIR": "C:\\Program Files\\ANSYS Inc\\Shared Files\\Licensing",
        "ANSYS241_DIR": "D:\\Program Files\\ANSYS Inc\\v241\\ANSYS",
        "LSTC_LICENSE": "Ansys"
      }
    }
  }
}

注意：command 与 args 中的路径必须与本地实际文件夹名完全一致（当前为 lumerical-mcp-main）。

为什么必须同时配置 .env 和 mcp.json 的 env？

server.py 启动时会调用 load_dotenv() 读取 .env，但该调用依赖启动时的工作目录 （即你运行 kimi 时所在的目录），并不总是指向 MCP 项目根目录。
mcp.json 中的 env 字段由 Kimi CLI 在创建子进程时显式注入，不受工作目录影响，是确保环境变量生效的可靠方式。
因此，两处都必须填写相同的许可证和路径变量，缺一不可。

3. 常见故障排查

故障 1：MCP 连接失败 / 路径错误

现象：启动 Kimi Code CLI 后，MCP 状态显示 lumerical (failed) 或 0/1 connected。

原因：mcp.json 中的路径写错（例如写成 lumerical_mcp_server 而非实际的 lumerical-mcp-main），导致找不到 python.exe 或 server.py。

解决：核对 mcp.json 中的 command 和 args 路径与实际文件夹名一致。

故障 2：重启电脑后 MCP 消失 / 无法使用

现象：电脑重启前 MCP 可用，重启后 Kimi CLI 中找不到 lumerical 工具。

原因：之前仅通过临时参数（如 kimi --mcp-config ...）加载 MCP，没有创建持久化配置文件 ~/.kimi/mcp.json。临时配置仅存于当前会话，重启后自然丢失。

解决：确保 C:\Users\XXXXX\.kimi\mcp.json 存在且内容正确（见 2.3 节）。Kimi CLI 每次启动会自动读取该文件。

故障 3：新对话中 FDTD 无法连接 / 许可证错误

现象：在当前 Kimi Code CLI 会话中可以打开 FDTD 会话，但新开一个对话窗口 后调用 fdtd_open_session_tool 失败，提示 "Session not found" 或许可证连接错误。

原因：Ansys 许可证环境变量（ANSYSLMD_LICENSE_FILE、ANSYSLIC_DIR 等）只在当前 Kimi CLI 父进程中生效，而 MCP Server 的 worker 子进程没有继承 这些变量，导致 lumapi.FDTD() 无法连接到许可证服务器。

解决：将这些许可证环境变量同时写入 .env 文件和 mcp.json 的 env 字段（见 2.1 和 2.3 节）。这样无论工作目录如何，MCP Server 都能获取正确的许可证配置。

4. 验证步骤

配置完成后，按以下顺序验证 FDTD 是否可用：

4.1 检测环境

复制代码

lumerical_detect_tool

预期返回：lumapi_importable: true，各产品 ok: true。

4.2 打开会话

复制代码

lumerical_open_session_tool(product=fdtd, hide=true)

4.3 执行脚本验证

复制代码

lumerical_eval_script_get_tool(code: mcp_x=2+3;, return_var: mcp_x)

预期返回：mcp_x = 5.0

4.4 常用 FDTD 工作流

建模：Si 波导（0.5 × 0.22 μm）+ SiO₂ 基底
仿真区域：3 × 3 × 1.5 μm
Mesh 精度：1（或根据需求调整）
运行 run; 后保存到文件：verification_waveguide.fsp

5. 注意事项

v241 没有 launcher.exe ：Ansys 新版 Lumerical 已不附带 launcher.exe，这不影响 FDTD/MODE/INTERCONNECT/DEVICE 的独立使用。
.env 与 mcp.json 的关系 ：server.py 运行时通过 python-dotenv 加载 .env，同时 mcp.json 中的 env 字段也向 server 注入环境变量。两者互为冗余，确保任何场景下变量都可获取。
许可证服务器必须运行 ：如果 ANSYSLMD_LICENSE_FILE=1055@localhost 指向本地许可证服务器，请确保 ANSYS License Manager 服务已启动并设置为开机自启，否则 Lumerical API 无法初始化。
文档位置：本文档位于桌面，可随 MCP 配置一起作为参考。

Lumerical MCP Server (v241) 配置与排障总结