Ansys Workbench MCP

一个用于连接 Codex / MCP 客户端 和 Ansys Workbench / ICEM CFD 的本地桥接项目。它通过文件队列 IPC 让外部 AI 助手向 Workbench 或 ICEM CFD 发送命令，并在 Ansys 进程内执行脚本和返回结果。

本项目不是 Ansys 官方项目，也不依赖鼠标点击 GUI。它封装的是 Ansys 已支持的自动化入口：Workbench journal、Workbench scripting、ICEM Tcl/Replay、MAPDL batch、Fluent journal 和 CFX solver batch。

最新更新

• ICEM CFD 常驻桥：启动 GUI 或无界面 ICEM 会话，并直接执行 Tcl/Replay 命令
• ICEM CFD 批处理：通过 run_icem_replay 运行一次性网格脚本，无需脚本自行添加 exit
• ICEM 命令发现：查询当前会话信息，并按模式列出 ic_*、ic_hex_* 等命令
• 通用 Workbench 分析系统创建：通过 create_workbench_analysis_system_live 创建指定模板的分析系统
• 分析模板探测：通过 probe_workbench_analysis_templates_live 检查当前 Ansys 安装中可用的 Workbench 模板
• 热分析封装：支持稳态热和瞬态热系统创建
• 结构和动力学封装：支持静力、瞬态结构、模态、谐响应、响应谱、随机振动系统创建
• CFX 封装：支持 Workbench CFX 系统创建，也支持直接运行 CFX .def
• Fluent 封装：支持直接运行 Fluent journal；如果本机 Workbench 有 Fluent 模板，也可以用模板名覆盖方式创建系统
• 安装检查增强：check_ansys_installation 会同时检查 Workbench、Mechanical、MAPDL、Fluent、CFX 路径
• README 重构：按安装、连接、使用、工具、协议和排错的顺序组织

架构

+--------------+     MCP stdio      +---------------+      file IPC       +--------------------+
| MCP Client   |  ----------------> | mcp_server.py |  ----------------> | Ansys Workbench    |
| Codex        |  <---------------- | FastMCP       |  <---------------- | bridge journal     |
+--------------+                    +---------------+                     +--------------------+
                                           |
                                           v
                                  commands/*.json  ->  Workbench reads
                                  results/*.json   <-  Workbench writes
                                  status.json      <-  bridge heartbeat

Workbench 侧由 ansys_workbench_bridge.wbjn 轮询 commands/ 目录。MCP server 写入命令文件，Workbench 执行后把结果写入 results/，Codex 再读取结果并返回给用户。

ICEM CFD 侧由 icem_cfd_bridge.tcl 轮询 icem/commands/。每条命令引用一个独立 Tcl/Replay 脚本，执行结果、错误堆栈和心跳分别写入 icem/results/、icem/status.json 和 icem/icem_bridge.log。

功能

• 检查本机 Ansys Workbench、Mechanical、MAPDL、Fluent、CFX、ICEM CFD 路径
• 启动、停止和检查 Workbench bridge
• 启动、停止和检查 ICEM CFD 常驻桥
• 在当前 ICEM CFD 会话中直接执行 Tcl/Replay 命令
• 查询 ICEM 会话和可用命令，或运行一次性 Replay 批处理
• 在正在运行的 Workbench 会话中执行脚本
• 读取当前 Workbench 项目的系统和组件信息
• 打开、保存、更新 Workbench 项目
• 探测 Workbench 分析模板
• 创建 Workbench 分析系统
• 创建稳态热、瞬态热、静力、瞬态结构、模态、谐响应、响应谱、随机振动、CFX 系统
• 尝试创建 Fluent Workbench 系统
• 直接运行任意 Workbench journal
• 直接运行 MAPDL 输入文件
• 直接运行 Fluent journal
• 直接运行 CFX solver input
• 创建并求解一个简单稳态热示例

安装

1. 克隆项目

推荐安装到 D:\ansys-workbench-mcp：

cd D:\
git clone https://github.com/hongwenwang36-eng/ANSYS-Workbench-mcp.git ansys-workbench-mcp
cd D:\ansys-workbench-mcp

也可以在 GitHub 页面下载 ZIP，然后解压到：

D:\ansys-workbench-mcp

2. 安装 Python 依赖

推荐使用虚拟环境：

cd D:\ansys-workbench-mcp
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

如果没有 Python 3.13，先查看本机 Python：

py -0p

然后把 py -3.13 换成实际版本，例如 py -3.11。

3. 确认 Ansys 路径

默认按 Ansys 2025 R1 配置：

Workbench:  D:\Program Files\ANSYS Inc\v251\Framework\bin\Win64\RunWB2.exe
Mechanical: D:\Program Files\ANSYS Inc\v251\aisol\bin\winx64\AnsysWBU.exe
MAPDL:      D:\Program Files\ANSYS Inc\v251\ansys\bin\winx64\ANSYS251.exe
Fluent:     D:\Program Files\ANSYS Inc\v251\fluent\ntbin\win64\fluent.exe
CFX solve:  D:\Program Files\ANSYS Inc\v251\CFX\bin\cfx5solve.exe
CFX pre:    D:\Program Files\ANSYS Inc\v251\CFX\bin\cfx5pre.exe
ICEM CFD:   D:\Program Files\ANSYS Inc\v251\icemcfd\win64_amd\bin\icemcfd.bat

如果你的安装路径不同，后续在 Codex MCP 配置里改对应环境变量。

4. 配置 Codex MCP

打开 Codex 配置文件：

%USERPROFILE%\.codex\config.toml

加入：

[mcp_servers.ansys-workbench]
command = 'D:\ansys-workbench-mcp\.venv\Scripts\python.exe'
args = ['D:\ansys-workbench-mcp\mcp_server.py']
cwd = 'D:\ansys-workbench-mcp'
startup_timeout_sec = 30
tool_timeout_sec = 600
enabled = true

[mcp_servers.ansys-workbench.env]
ANSYS_WORKBENCH_MCP_HOME = 'D:\ansys-workbench-mcp'
ANSYS_RUNWB2 = 'D:\Program Files\ANSYS Inc\v251\Framework\bin\Win64\RunWB2.exe'
ANSYS_MECHANICAL = 'D:\Program Files\ANSYS Inc\v251\aisol\bin\winx64\AnsysWBU.exe'
ANSYS_MAPDL = 'D:\Program Files\ANSYS Inc\v251\ansys\bin\winx64\ANSYS251.exe'
ANSYS_FLUENT = 'D:\Program Files\ANSYS Inc\v251\fluent\ntbin\win64\fluent.exe'
ANSYS_CFX_SOLVE = 'D:\Program Files\ANSYS Inc\v251\CFX\bin\cfx5solve.exe'
ANSYS_CFX_PRE = 'D:\Program Files\ANSYS Inc\v251\CFX\bin\cfx5pre.exe'
ANSYS_ICEM_CFD = 'D:\Program Files\ANSYS Inc\v251\icemcfd\win64_amd\bin\icemcfd.bat'

修改后重启 Codex，让 MCP server 重新加载。

使用

检查安装

在 Codex 中调用：

check_ansys_installation

该工具会检查 Workbench、Mechanical、MAPDL、Fluent、CFX、ICEM CFD 和两个 bridge 脚本是否存在。

启动 Workbench bridge

在 Codex 中调用：

start_workbench_bridge

它会用 RunWB2.exe 加载：

D:\ansys-workbench-mcp\ansys_workbench_bridge.wbjn

然后 Workbench bridge 开始轮询 commands/。

检查连接状态

check_workbench_connection

如果连接正常，会返回 Workbench bridge 版本、状态、PID 和命令计数。

手动加载 bridge

也可以先打开 Workbench，然后手动运行：

File -> Run Script... -> D:\ansys-workbench-mcp\ansys_workbench_bridge.wbjn

该 journal 会进入 mcp_loop() 并监听 MCP 命令。

停止 bridge

方式一，在 Codex 中调用：

stop_workbench_bridge

方式二，在 PowerShell 中运行：

cd D:\ansys-workbench-mcp
.\.venv\Scripts\python.exe .\stop_mcp.py

使用 ICEM CFD 常驻桥

启动带界面的 ICEM CFD：

start_icem_bridge

启动无界面的常驻会话：

start_icem_bridge(batch=true)

连接后可直接执行 ICEM Tcl/Replay 命令：

execute_icem_script(script="ic_load_tetin {D:/cases/model.tin}")

查询会话或 Blocking 命令：

get_icem_session_info
list_icem_commands(pattern="ic_hex_*", limit=300)

运行现有 Replay 文件作为一次性批处理：

run_icem_replay(replay_file="D:/cases/mesh.rpl", workdir="D:/cases")

停止常驻会话并关闭由桥启动的 ICEM 进程：

stop_icem_bridge

execute_icem_script 在 ICEM 自身的 Tcl 解释器中执行，能够调用当前安装中实际存在的 ic_* 命令。对于建几何、Blocking、网格质量和导出流程，推荐先在 ICEM 的 Replay Control 中录制一小段命令，再通过该工具参数化和复用。

工作模式

MCP 工具

这些工具由 mcp_server.py 暴露给 Codex 或其他 MCP 客户端。

MCP 资源

分析系统类型

create_workbench_analysis_system_live 和 create_workbench_analysis_system 支持：

如果本机模板名不同，可以用 template_name 和 solver 参数覆盖。

Fluent 和 CFX 说明

在当前测试机器上：

• CFX 的 Workbench 模板可用：Fluid Flow (CFX)
• Fluent 的 fluent.exe 可用
• 常见 Workbench Fluent 模板名 Fluid Flow (Fluent) 和 Fluent 没有被当前 Workbench 模板接口找到

因此：

• CFX 可以通过 Workbench 系统创建，也可以通过 run_cfx_solver 直接运行 .def
• Fluent 推荐先通过 run_fluent_journal 运行 journal/TUI 自动化
• 如果你的 Workbench 安装中 Fluent 模板名不同，可以用 create_workbench_analysis_system_live 的 template_name 参数覆盖

文件 IPC 协议

MCP server 会向 commands/ 写入 JSON 命令文件：

import json
import time
from pathlib import Path

command = {
    "id": "my_command",
    "type": "execute_script",
    "script": "print('Hello from Workbench')",
    "timestamp": time.time(),
}

cmd_path = Path(r"D:\ansys-workbench-mcp\commands\cmd_my_command.json")
cmd_path.write_text(json.dumps(command, indent=2), encoding="utf-8")

Workbench bridge 执行后，会把结果写入：

D:\ansys-workbench-mcp\results\my_command.json

命令类型

目录结构

D:\ansys-workbench-mcp\
├── mcp_server.py                  # MCP server，运行在 Codex 外部进程中
├── ansys_workbench_bridge.wbjn    # Workbench 侧 bridge journal
├── icem_cfd_bridge.tcl            # ICEM CFD 侧常驻 Tcl bridge
├── stop_mcp.py                    # 发送停止信号
├── requirements.txt               # Python 依赖
├── .mcp.json                      # MCP 客户端配置示例
├── commands\                      # MCP server 写入命令
├── results\                       # Workbench bridge 写回结果
├── scripts\                       # bridge 执行临时脚本
├── icem\                          # ICEM 命令、结果、状态和日志（运行时生成）
├── runs\                          # 示例工程和求解输出
├── tests\                         # Python IPC 和工具注册测试
├── status.json                    # bridge heartbeat 状态
├── mcp.log                        # bridge 日志
└── stop.flag                      # 停止信号文件

运行时目录和文件可能会随使用增加。mcp.log 和 status.json 是状态文件，不建议作为业务代码改动提交。

故障排查

• Codex 看不到工具

  • 检查 %USERPROFILE%\.codex\config.toml 是否配置了 mcp_servers.ansys-workbench
  • 确认 command 指向 .venv\Scripts\python.exe
  • 重启 Codex

• check_ansys_installation 显示路径不存在

  • 检查 Ansys 实际安装路径
  • 修改 ANSYS_RUNWB2、ANSYS_MECHANICAL、ANSYS_MAPDL、ANSYS_FLUENT、ANSYS_CFX_SOLVE、ANSYS_CFX_PRE、ANSYS_ICEM_CFD

• bridge 状态是 running 但命令超时

  • 调用 stop_workbench_bridge
  • 再调用 start_workbench_bridge
  • 查看 D:\ansys-workbench-mcp\status.json 的时间戳是否更新
  • 查看 D:\ansys-workbench-mcp\mcp.log

• Workbench 启动了但没有响应

  • 手动在 Workbench 中运行 File -> Run Script... -> ansys_workbench_bridge.wbjn
  • 确认没有旧的 stop.flag
  • 确认 ANSYS_WORKBENCH_MCP_HOME 指向项目目录

• ICEM 启动了但 check_icem_connection 超时

  • 不要连接一个普通方式启动的旧 ICEM 窗口；调用 start_icem_bridge 启动带 Tcl bridge 的新会话
  • 查看 D:\ansys-workbench-mcp\icem\icem_bridge.log
  • 确认 icem_cfd_bridge.tcl 存在，并检查许可证是否成功签出
  • 如果 GUI 环境有问题，先用 start_icem_bridge(batch=true) 验证无界面连接

• Fluent Workbench 模板找不到

  • 先使用 run_fluent_journal
  • 或调用 probe_workbench_analysis_templates_live 查看本机模板名
  • 如果知道实际模板名，用 template_name 参数覆盖

• 直接批处理运行时间很长

  • 增大工具的 timeout_seconds
  • 对 Fluent/CFX/MAPDL 先用小模型验证 journal 或输入文件

已验证

在本机已经验证：

• MCP stdio 可以列出工具
• Ansys 2025 R1 路径检查正常
• ICEM CFD 2025 R1 GUI 和 batch 常驻桥均可 ping、执行 Tcl 并正常停止
• ICEM Tcl 8.4.11 会话中可发现 ic_* 和 ic_hex_* 命令
• run_icem_replay 可执行不含 exit 的 Replay 文件并返回结果
• Workbench bridge 可以启动并通过 ping 响应
• Workbench 会话内脚本可以执行并返回输出
• 可探测 Workbench 分析模板
• 可创建稳态热、瞬态热、静力、瞬态结构、模态、谐响应、响应谱、随机振动和 CFX 系统
• Fluent 可执行文件存在，推荐通过 journal/TUI 自动化
• CFX solver 可执行文件存在，可通过 .def 直接运行
• 稳态热 demo 可以创建并求解

许可证

本项目使用 MIT License，详见 LICENSE。