PyMechanical-MCP provides a Model Context Protocol (MCP) server that enables AI assistants to interact with Ansys Mechanical through PyMechanical. Use natural language to set up, solve, and postprocess structural, thermal, and multiphysics simulations.
Overview
Key features:
- Manage Mechanical sessions by launching new instances or connecting to existing ones
- Run Mechanical scripting workflows through the Mechanical API
- Execute custom Python and PyMechanical code in a persistent session
- Export results, capture screenshots, and create custom plots
- Retrieve built-in guidance for common Mechanical workflow steps
- Work with local, remote, or containerized Mechanical deployments
Tool surface
You can use 28 tools exposed by the server, grouped as follows:
| Group | Tools |
|---|---|
| Connection and lifecycle | check_mechanical_status, check_mechanical_installed, launch_mechanical, connect_to_mechanical, disconnect_from_mechanical, list_mechanical_instances |
| File and project management | list_files, upload_file, download_file, download_project, clear_mechanical, save_project, open_project |
| Mechanical scripting and solve | run_python_script, check_script, solve_analysis, get_model_info, get_results_summary, export_results |
| Object discovery and property changes | find_objects, describe_api, preview_property_change, apply_property_change |
| Visualization and diagnostics | screenshot, create_custom_plot, get_mechanical_logs |
| Persistent Python execution | run_python_code |
| Workflow guidance | get_guidelines_for |
The server also exposes an MCP resource, files://mechanical/working_directory, that
returns the working directory of the connected Mechanical instance.
In v0.3.0, check_mechanical_status replaces get_session_diagnostics and
includes its connection ownership, transport, and persistent Python diagnostics,
even when Mechanical is disconnected. Update clients that call the old name.
Installation
For users
Install the latest release with:
pip install ansys-mechanical-mcp
Or run directly without installing by using uvx. Install
uv and
Git first. uv provides uvx, and Git is required
because uvx downloads and runs PyMechanical-MCP directly from this repository
without cloning it.
uvx --index-strategy unsafe-best-match --from git+https://github.com/ansys/pymechanical-mcp ansys-mechanical-mcp
For developers
git clone https://github.com/ansys/pymechanical-mcp.git
cd pymechanical-mcp
pip install -e ".[dev]"
Usage
For step-by-step setup instructions for VS Code, Claude Code, Claude Desktop, and other MCP-compatible clients, see IDE and client configuration in the documentation.
For launch and connect workflows, including GUI and batch mode behavior, see Quick start.
Configuration
Use STDIO for local MCP clients. Use HTTP transport for remote access in trusted networks or behind infrastructure that provides authentication and TLS.
Run with default STDIO transport:
ansys-mechanical-mcp
Run with HTTP transport:
ansys-mechanical-mcp --transport http --http-host 127.0.0.1 --http-port 8080
Common configuration options:
| Option | Description |
|---|---|
--transport |
MCP transport type: stdio or http |
--ip, --port |
Mechanical connection target for connect_on_startup or defaults |
--connect-on-startup |
Connect to Mechanical when the MCP server starts |
--transport-mode |
gRPC mode: auto, insecure, mtls, wnua |
--certs-dir |
Directory containing mTLS certificates (ca.crt, client.crt, client.key) |
--cors-origins |
Comma-separated allowed origins for HTTP transport |
Environment variables:
| Variable | Description |
|---|---|
PYMECHANICAL_TRANSPORT_MODE |
Default gRPC transport mode when --transport-mode is not set |
ANSYS_GRPC_CERTIFICATES |
Default certificate directory when --certs-dir is not set |
PYMECHANICAL_IP, PYMECHANICAL_PORT |
Docker connection defaults used by connection and discovery tools |
License
This project is licensed under the Apache 2.0 license agreement. See the LICENSE file for details.
Resources
1 maintainer
Metadata
1 maintainer
Release files for ansys-mechanical-mcp 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ansys_mechanical_mcp-0.3.0.tar.gz | 75.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ansys_mechanical_mcp-0.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 157.3 kB
Release files / ansys_mechanical_mcp-0.3.0.tar.gz
| Download URL | ansys_mechanical_mcp-0.3.0.tar.gz |
|---|---|
| Size | 75.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9c8d24ae8be7ead99cfd287a8b0575af7b5628970bc29b2f672f5d70933bda3e
|
|
BLAKE2b-256 checksum How to use checksums |
6f9793aacc3708a420628bbea5210976e399bacbb01b13050d8974d7301adac8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency logRelease files / ansys_mechanical_mcp-0.3.0-py3-none-any.whl
| Download URL | ansys_mechanical_mcp-0.3.0-py3-none-any.whl |
|---|---|
| Size | 81.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e08367576034b15aa8618e3f201d822d3d569851018bce977c27d67a42bb9b4a
|
|
BLAKE2b-256 checksum How to use checksums |
36b8591d286a21860fef6412dc5d14611b3ac688ea4678b7b0c59efc8f1b5963
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency log
