ANSYS Workbench MCP

中文说明

A clean, GitHub-ready MCP server and ACT extension for controlling ANSYS Workbench and ANSYS Mechanical from Kimi, Claude, Codex, or any other MCP client.

The package exposes MCP tools that can:

• detect the ANSYS Workbench/Mechanical environment,
• launch Workbench journals,
• launch Mechanical Python scripts via ansys-mechanical,
• track asynchronous jobs,
• submit Python requests to a running Mechanical session through a file queue,
• execute Python inside Mechanical through a localhost socket timer bridge.

Note: This package does not include ANSYS binaries or solver licenses. It only provides the glue between an MCP client and a locally installed ANSYS product.

---

Prerequisites

• Windows (Workbench/Mechanical and the ACT extension are Windows-only).
• ANSYS Workbench / Mechanical 2024 R2 or later (paths in this repo use v242 as the default).
• The WorkbenchMCP ACT extension enabled inside Mechanical.
• Python 3.10+ (the py launcher is used by setup.ps1).
• A local ANSYS license and, for Mechanical scripting, a running Mechanical GUI.

---

Quick Install

Open a PowerShell window in the package root and run:

.\setup.ps1

The script will:

1. Detect the ANSYS install root from ANSYS_ROOT, AWP_ROOT*, or common paths.
2. Create a Python virtual environment at .venv and install this package in editable mode with the mechanical extras.
3. Copy workbench_plugin\* into %APPDATA%\Ansys\<v242>\ACT\extensions\WorkbenchMCP.
4. Register the MCP server in both ~\.kimi\mcp.json and ~\.claude\settings.json.

If the auto-detected version is wrong, override it:

.\setup.ps1 -Version 251

Restart your MCP client after the script finishes.

---

Manual ACT Extension Installation

If you prefer not to run setup.ps1, or you are on a version that the script did not detect, install the ACT extension manually:

1. Copy the files in workbench_plugin\ to:

   %APPDATA%\Ansys\v242\ACT\extensions\WorkbenchMCP\
   

   Replace v242 with your actual ANSYS version folder.

2. The extension directory should contain:

   WorkbenchMCP.xml
   main.py
   mechanical_queue_processor.py
   mechanical_socket_timer_v7.py
   

3. Open ANSYS Workbench, start a project, and open Mechanical.

4. In Mechanical, enable the Workbench MCP toolbar from Automation > ACT Extensions if it is not already visible.

---

Using the MCP Tools

Once the server is registered and Mechanical is open with the ACT extension loaded, the following tool categories are available:

1. Detection

• workbench_detect_tool — finds RunWB2.exe, the PyMechanical CLI, the ANSYS root, and job directories.

2. Launch Workbench Journals

• workbench_run_journal_tool — runs a Workbench journal (.py or .wbjn) asynchronously.
• workbench_job_status_tool — checks whether a launched job is still running.
• workbench_job_log_tool — reads stdout or stderr for a job.
• workbench_list_jobs_tool — lists recent jobs.

3. Run Mechanical Scripts

• mechanical_run_script_tool — launches ansys-mechanical.exe with a Python script.

4. Mechanical File Queue

These tools talk to a file-based queue that Mechanical processes through the ACT extension:

• workbench_queue_install_info_tool — shows the queue folder paths and instructions.
• workbench_queue_submit_tool — submits a raw JSON request to the queue.
• workbench_queue_list_tool — lists pending requests and responses.
• workbench_queue_response_tool — reads a response by request ID.
• workbench_queue_ping_tool — sends a ping and waits for Mechanical to process it.
• workbench_queue_state_tool — reads the current Mechanical state.
• workbench_queue_execute_python_tool — executes Python inside the open Mechanical session.
• workbench_queue_process_with_socket_timer_tool — asks the socket timer bridge to process the pending queue.

5. Mechanical Socket Timer Bridge

The socket timer runs inside Mechanical on 127.0.0.1:9885 and provides the fastest round-trip execution:

• workbench_socket_timer_ping_tool — ping the bridge.
• workbench_socket_timer_state_tool — read the bridge state.
• workbench_socket_timer_execute_python_tool — execute Python in Mechanical.
• workbench_socket_timer_stop_tool — stop the bridge.

You can start the bridge from the Workbench MCP toolbar in Mechanical (Socket Timer Start). With WORKBENCH_MCP_AUTO_START_SOCKET=1 (the default), the ACT extension attempts to start it automatically when Mechanical loads.

---

Example Prompts / Workflow

Verify the environment

Run workbench_detect_tool to make sure ANSYS Workbench and the PyMechanical CLI are found.

Open a project and launch Mechanical

Set ANSYS_PROJECT_PATH to the .wbpj file you want to open, then run the journal:

Use workbench_run_journal_tool with journals/open_project_and_edit_model.py to open the project at C:\Models\my_model.wbpj.

Set ANSYS_PROJECT_PATH in the MCP server environment or pass it to the journal process.

Execute Python inside the open Mechanical session

Use workbench_socket_timer_execute_python_tool to list the analyses in the open Mechanical model: print([a.Name for a in Model.Analyses])

Diagnose a project without opening the GUI

Run the diagnose_project.py journal against C:\Models\my_model.wbpj and show the output.

---

Boundaries and Limitations

Please read these carefully to set correct expectations:

• Mechanical must be open with the ACT extension loaded. The MCP tools cannot drive a fully headless, unattended batch FEA workflow on their own. The file queue and socket timer require an active Mechanical GUI session.
• Localhost-only transport. The file queue and socket timer bridge listen on 127.0.0.1:9885. They are not exposed to the network and are not secure for multi-user or remote use.
• Long solves require client polling. workbench_run_journal_tool and mechanical_run_script_tool launch jobs asynchronously. The MCP client must call workbench_job_status_tool or workbench_job_log_tool to wait for completion.
• Workbench project locks can block saves. If a .wbpj project is already open in another Workbench process, the lock files may prevent save_project.py from overwriting the project. The journals include best-effort lock cleanup, but this is not a guarantee.
• No ANSYS binaries or licenses are included. You must provide a licensed ANSYS installation and a valid Python environment. The mechanical extras install ansys-mechanical-core; the actual solver remains ANSYS-owned.
• The ACT extension lives in the user profile. setup.ps1 copies it to %APPDATA%\Ansys\<version>\ACT\extensions\WorkbenchMCP. This is per-user, per-version, and may need to be repeated after a major ANSYS upgrade.

---

Repository Layout

ansys-workbench-mcp/
├── server.py                          # FastMCP server exposing all tools
├── pyproject.toml                     # Package metadata and dependencies
├── .env.example                       # Environment variables template
├── .gitignore                         # Ignores runtime outputs
├── setup.ps1                          # One-click install script
├── install_mcp_config.py              # JSON merge helper for MCP configs
├── README.md                          # This file
├── examples/
│   └── codex_config.example.toml      # Example Codex MCP config shape
├── journals/                          # Reusable Workbench journal scripts
│   ├── open_project_and_edit_model.py
│   ├── update_model2.py
│   ├── save_project.py
│   ├── diagnose_project.py
│   └── workbench_lock_utils.py
├── tools/                             # Python-side MCP helpers
│   ├── workbench_bridge.py
│   ├── workbench_file_queue.py
│   └── workbench_socket_timer.py
└── workbench_plugin/                  # ACT extension for Mechanical
    ├── WorkbenchMCP.xml
    ├── main.py
    ├── mechanical_queue_processor.py
    └── mechanical_socket_timer_v7.py

---

License and Legal

This is an independent integration package. It is not affiliated with or endorsed by ANSYS, Inc. ANSYS, Workbench, Mechanical, and related trademarks are property of ANSYS, Inc. or its subsidiaries.