# ANSYS Mechanical MCP

An independent MIT-licensed MCP bridge developed with Codex, using official PyMechanical dependencies. Connect an MCP-capable AI client to local Ansys tools on Windows. Ansys software and licenses are not included.

## Product support

| Product | What this bridge provides |
| --- | --- |
| Mechanical | Model inspection and bounded material, load, mesh, solve, result, and save operations through a running local gRPC session |
| Workbench | Read-only project inventory and Mechanical-system audits through Workbench batch journals; does not require a separately running Mechanical gRPC session |
| Fluent | Installation/version detection only. No Fluent session, mesh, CFD solver, or results tools are implemented |
| Other Ansys products | No product-specific tools currently implemented |

Workbench is a project environment: a Workbench project can contain multiple solver systems. Auditing a **Mechanical** system inside Workbench still requires Mechanical. Workbench project inventory does not turn Fluent systems into Mechanical systems.

## Install on another Windows computer

Requires Python 3.10–3.14, Git, and the separately installed/licensed Ansys products you intend to use.

```powershell
git clone https://github.com/mystify59/ansys-mechanical-mcp.git
cd ansys-mechanical-mcp
.\scripts\install.ps1
```

The installer finds a supported Python, creates a local virtual environment, installs dependencies, runs tests, inventories installed products, and prints client configuration. It does not modify your AI client's settings or start Ansys. Internet access is needed for dependencies. If your default Python is unsupported, provide its executable:

```powershell
.\scripts\install.ps1 -Python "C:\Python312\python.exe"
```

Re-run installation after moving the checkout or changing Python, and regenerate your client configuration: virtual environments and generated absolute paths are machine-specific. Do not copy another person's virtual environment.

## Version discovery and overrides

Discovery checks `AWP_ROOT###` environment variables, Ansys registry entries, and standard Windows installation directories. Only products with an existing executable are reported. Auto mode selects the newest detected release **for each product**, so Workbench can be selected even when Mechanical is absent.

For a custom installation, set `ANSYS_INSTALL_ROOT` to the Ansys parent directory or a version directory such as `F:\Engineering\Ansys\v261`.

```powershell
.\.venv\Scripts\python.exe -m ansys_mechanical_mcp.setup_cli detect
.\scripts\install.ps1 -Version 261 -WorkbenchVersion 252
```

Explicit versions never fall back to another release. A missing product is reported without preventing setup for other products. Detection is not a compatibility certification: the original live verification used Mechanical/Workbench 2025 R2. Other releases need a smoke test on the colleague's machine.

## Transport and starting Mechanical

Both scripts default to `wnua`. **Use the same version, transport and port for installation/config generation and launch.** Old releases without the required service pack need explicit `insecure` transport. The launcher binds only to `127.0.0.1`; no automatic fallback to insecure transport is performed.

For the original 2025 R2 installation without SP03:

```powershell
.\scripts\install.ps1 -Version 252 -TransportMode insecure
.\scripts\start_mechanical_server.ps1 -Version 252 -TransportMode insecure
```

For another installation:

```powershell
.\scripts\start_mechanical_server.ps1 -Version 261
# Inspect the command without starting Ansys:
.\scripts\start_mechanical_server.ps1 -Version 261 -DryRun
```

Open your project copy in Mechanical after the server starts; PyMechanical does not accept a project file together with server-mode startup. Wait for Mechanical to finish opening, then ask the AI client to call `connect_mechanical`. The launcher checks that PyMechanical resolves the same executable as this bridge. If paths disagree, configure PyMechanical's path before retrying.

See the official [PyMechanical CLI](https://mechanical.docs.pyansys.com/version/stable/user_guide/cli/ansys-mechanical.html) and [transport/service-pack requirements](https://mechanical.docs.pyansys.com/version/stable/user_guide/remote_session/grpc_security.html). The included convenience launcher supports WNUA and loopback insecure mode; custom mTLS setup is outside this installer.

## Connect other AI clients

This server uses standard **MCP stdio**, not a Codex-specific protocol. The client must support launching local stdio MCP servers on the Windows Ansys machine. These examples are configuration formats, not claims that every client has been live-tested.

Generate a JSON `mcpServers` entry for clients accepting that format:

```powershell
.\.venv\Scripts\python.exe -m ansys_mechanical_mcp.setup_cli config --format json
```

For Codex's TOML format:

```powershell
.\.venv\Scripts\python.exe -m ansys_mechanical_mcp.setup_cli config --format codex
```

Merge the generated entry into the client's existing MCP settings; do not replace unrelated servers. For clients with a form, copy the command, argument list and environment fields. Restart/reload its MCP connection afterward. Pass `--version 252 --transport insecure` when generating config for the original machine.

Generated config pins detected executable paths and versions and uses an absolute output directory (default: `~/ansys_mcp_output`). Regenerate it on each machine. A silent MCP terminal is normal: stdout is reserved for the protocol.

## Configuration

| Environment variable | Meaning/default |
| --- | --- |
| `ANSYS_MECHANICAL_VERSION` | Revision such as `252` or `261`; default `auto` |
| `ANSYS_WORKBENCH_VERSION` | Independent Workbench revision; inherits explicit Mechanical revision if unset, otherwise auto |
| `ANSYS_INSTALL_ROOT` | Additional discovery parent or version directory |
| `ANSYS_MECHANICAL_EXECUTABLE` | Override path to AnsysWBU.exe; also supply the explicit product revision |
| `ANSYS_WORKBENCH_EXECUTABLE` | Override path to RunWB2.exe; also supply the explicit product revision |
| `ANSYS_MECHANICAL_HOST` | Loopback only; default `127.0.0.1` |
| `ANSYS_MECHANICAL_PORT` | Default `10000` |
| `ANSYS_MECHANICAL_TRANSPORT` | Default `wnua`; must match the running server |
| `ANSYS_MCP_OUTPUT_DIR` | Absolute output location; generated config defaults to your home directory's `ansys_mcp_output` |
| `ANSYS_MECHANICAL_TIMEOUT` | Connection timeout in seconds; default `120` |
| `ANSYS_WORKBENCH_TIMEOUT` | Workbench job timeout in seconds; default `300` |

## Boundaries and verification

Inspection tools are read-only; model-changing, solving, and writing tools are labelled. No arbitrary Python, APDL, or shell execution tool is exposed. Disconnecting the MCP does not close Mechanical. Saved copies and captures remain confined to the configured output directory.

Tests cover discovery with multiple product/version combinations, Workbench-only setup, versioned journals, client-config escaping, and launcher argument validation and rejection of unsupported project/server combinations, alongside the original operation tests.

```powershell
.\.venv\Scripts\python.exe -m pytest -v
```

Windows is the supported setup target. Linux, remote network connections, Fluent operations, and solver equivalence across releases are not established by these tests.

## License

[MIT](LICENSE). Dependencies and Ansys software retain their respective licenses.