# ANSYS Workbench MCP

[中文说明](README.zh-CN.md)

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:

```powershell
.\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:

```powershell
.\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:

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

   Replace `v242` with your actual ANSYS version folder.

2. The extension directory should contain:

   ```text
   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

```text
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:

```text
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

```text
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

```text
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

```text
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.