name: ansys-structural-mcp description: >- Provides full-process ANSYS Mechanical MAPDL structural simulation capabilities, including CAD geometry creation, material definitions, viscoelastic Prony series, mesh controls, force/displacement loading, solving, and PyVista off-screen stress/displacement plotting. Supports running both as direct CLI commands and as a stdio Model Context Protocol (MCP) server.

ansys-structural-mcp

Overview

ansys-structural-mcp is a professional engineering simulation skill designed to interface natively with a local ANSYS 2024 R2 solver on Windows. It wraps finite element analysis (FEA) workflows—such as parametric cantilever beams, plate stress concentrations, and viscoelastic polymer disk compression—into highly structured Python classes and exposes them as commands and standardized Model Context Protocol (MCP) tools.

Dependencies

• Python: Python 3.8+ (designed and verified on Python 3.12.4 in Anaconda D:\anaconda3).
• ANSYS MAPDL Solver: Local installation of ANSYS 2024 R2 (environment variables AWP_ROOT242 and ANSYS242_DIR configured).
• Python Libraries:
  • ansys-mapdl-core (version 0.73.0+)
  • pyvista (version 0.48.0+ for advanced 3D post-processing)
  • ansys-tools-visualization-interface (required by modern PyMAPDL rendering)
  • matplotlib, numpy (for math and curve plotting)

Quick Start

1. Verify Local Environment

Before running simulations, run a quick diagnostic check to ensure the Python environment and ANSYS License Manager service are fully running:

D:\anaconda3\python.exe C:\Users\f\Documents\antigravity\delightful-lavoisier\ansys_agent_toolkit\environment_test.py

2. Run Direct CLI Simulation

To run a parametric cantilever beam simulation and generate cloud plots:

D:\anaconda3\python.exe C:\Users\f\Documents\antigravity\delightful-lavoisier\ansys_agent_toolkit\run_simulation.py --type cantilever --params "{\"length\": 1.5, \"force_y\": -2000.0, \"mesh_size\": 0.02}"

3. Launch stdio MCP Server

To boot the toolkit as a stdio MCP server for Cursor, Claude Desktop, or other external clients:

D:\anaconda3\python.exe C:\Users\f\Documents\antigravity\delightful-lavoisier\ansys_agent_toolkit\run_simulation.py --mcp

Utility Scripts (CLI & MCP Tools)

test_environment (MCP) / environment_test.py (CLI)

Checks system paths, environment variables (AWP_ROOT242), imports dependencies, and attempts to launch a background headless MAPDL instance to verify licensing.

run_structural_simulation (MCP) / run_simulation.py (CLI)

Runs a full structural FEA simulation based on a pre-defined template.

• Arguments:
  • type (string, required): Choice of simulation:
    • cantilever: Standard cantilever beam bending simulation. Uses mapped hex meshing.
    • plate_with_hole: Stress concentration around a circular hole. Uses free tetrahedral meshing and clamping to prevent under-constrained pivots.
    • viscoelastic_disk: Time-dependent compression of an elastomer cylinder utilizing shear Prony relaxation parameters and static time-stepping.
  • params (object, optional): JSON parameters overriding default geometry, mesh size, load values, and material inputs.

extract_stress_curves (MCP) / plot_stress_curves.py (CLI)

Applies high-accuracy geometric path line interpolation (PyVista line sampling) to extract stress values along the vertical center axis or radial paths across the viscoelastic disk. Plots comparative curves and exports raw data to JSON.

Common Mistakes

1. ANSYS License Manager CVD Service is Stopped:
   • Problem: launch_mapdl hangs or fails with license checkout error.
   • Fix: Start the service ANSYS, Inc. License Manager CVD in Windows Services (services.msc) or via ANSYS License Management Center.
2. Under-Constrained/Pivot Term Errors:
   • Problem: In free tetrahedral meshes (e.g. plate_with_hole), selecting a single point-node to prevent rigid body motion is highly susceptible to mesh coordinate tolerances.
   • Fix: Clamp boundary faces fully in UX, UY, and UZ to guarantee rigid body constraints and solver stability.
3. Pollution of Stdio Stream:
   • Problem: In stdio MCP mode, random prints from PyMAPDL or python modules pollute stdout and corrupt JSON-RPC.
   • Fix: The toolkit automatically redirects sys.stdout to sys.stderr during tool calls to keep JSON stdio communication perfectly clean.