Mechanical Server

A Model Context Protocol (MCP) server that connects any MCP-compatible AI client to ANSYS Mechanical via PyMechanical gRPC. Talk to your simulation in plain English.

https://github.com/user-attachments/assets/309952dc-dce0-4aa6-9b06-e8047f32c2de

Compatible clients

Works with any MCP-compatible client, including:

• Claude Desktop
• Cursor
• Windsurf
• VS Code (with Copilot MCP support)
• Continue

What it does

Category	Capabilities
Connection	Connect to one or more running Mechanical instances by port
Geometry	List bodies, assign materials, suppress/unsuppress bodies
Mesh	Set element size, generate mesh, get statistics
Boundary Conditions	Fixed support, displacement, remote displacement, frictionless support, force, remote force, pressure, moment, gravity
Solve & Results	Solve, get status, modal frequencies, equivalent stress, directional deformation, principal stress, stress tool, reaction force
Point Mass	Convert a Part to a combined Point Mass (no extensions required), auto-create attachment Named Selection
Named Selections	List, delete
Reports	Generate DOCX or TXT simulation reports
Scripting	Run arbitrary IronPython directly in the Mechanical ACT API

Requirements

• ANSYS Mechanical 2023 R1 or later (with gRPC enabled)
• Python 3.10+

Installation

git clone https://github.com/codersag/mechanical-mcp.git
cd mechanical-mcp
pip install -e .

To include DOCX report generation:

pip install -e ".[report]"

MCP Client Configuration

Add the following to your MCP client's config file. The config file location varies by client:

Client	Config file location
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop (Mac)	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor	.cursor/mcp.json in your project, or ~/.cursor/mcp.json globally
Windsurf	~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mechanical-mcp": {
      "command": "ansys-mechanical-mcp"
    }
  }
}

Or if running from source:

{
  "mcpServers": {
    "mechanical-mcp": {
      "command": "python",
      "args": ["C:/path/to/mechanical-mcp/mechanical_mcp_server.py"]
    }
  }
}

Restart your client after editing the config.

Finding the Mechanical gRPC port

Mechanical exposes a gRPC server whose port you pass to connect_to_mechanical.

In Workbench (Tools → Scripting → Run Script):

port = GetSystem("SYS").GetContainer(ComponentName="Model").StartGrpcServer()
print(port)

If you have multiple Mechanical systems open (e.g. Modal + Static Structural), run the script for each system by replacing "SYS" with the system name (e.g. "SYS 1", "SYS 2").

Usage

1. Open ANSYS Mechanical (gRPC is enabled by default in 2023 R1+)
2. Find the port using one of the methods above
3. Connect to your Mechanical instance:

"Connect to Mechanical on port 10000"

Then interact naturally:

"Assign Structural Steel to all bodies"

"Generate a mesh with 50mm element size"

"Add a fixed support to the named selection called Base"

"Solve the analysis and get the maximum von Mises stress"

"Convert part Equipment1 to a point mass"

Multiple Instances

You can connect to multiple Mechanical instances (e.g. Modal on port 51811, Static Structural on port 53038) by calling connect_to_mechanical with the relevant port. The server maintains one active connection at a time.

License

Apache License 2.0 — see LICENSE