PyAEDT-MCP
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ansys/pyaedt-mcp/main/doc/source/_static/images/logo-dark.png">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ansys/pyaedt-mcp/main/doc/source/_static/images/logo-light.png">
<img alt="PyAEDT-MCP" src="https://raw.githubusercontent.com/ansys/pyaedt-mcp/main/doc/source/_static/images/logo-light.png" width="900">
</picture>
</p>
[](https://docs.pyansys.com/)
[](https://www.python.org/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/astral-sh/ruff)
PyAEDT-MCP is an MCP (Model Context Protocol) server for Ansys Electronics Desktop (AEDT). It gives you reliable AEDT tools and a persistent PyAEDT-backed Python session for tasks that do not fit a dedicated tool.
## What PyAEDT-MCP does
PyAEDT-MCP supports this runtime loop:
1. Check whether AEDT is installed or already reachable.
2. Launch AEDT or connect to an existing gRPC session.
3. Open projects, create designs, run analyses, inspect the model, and export results.
4. Use `run_python_code` or `run_python_script` for custom PyAEDT work.
Supported AEDT applications include HFSS, Maxwell 2D/3D, Q2D, Q3D, Icepak, Circuit, TwinBuilder, Mechanical, EMIT, RMXprt, and HFSS 3D Layout.
## Install
### Run without cloning
Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and
[Git](https://git-scm.com/downloads) first. Git is required because `uvx`
downloads and runs PyAEDT-MCP directly from this repository without cloning it.
Python 3.13 is recommended; `--python 3.13` selects it explicitly and lets uv
download it if needed.
```bash
uvx --python 3.13 --from git+https://github.com/ansys/pyaedt-mcp.git ansys-aedt-mcp
```
### Install locally
Use a Python 3.13 or later environment (3.13 recommended).
```bash
pip install git+https://github.com/ansys/pyaedt-mcp.git
```
Or use `uv`:
```bash
uv pip install git+https://github.com/ansys/pyaedt-mcp.git
```
### Windows installer
Windows releases include `PyAEDT-MCP-Installer-windows.exe`:
- Installs the desktop manager into `C:\Program Files\ANSYS Inc\PyAEDT MCP`.
- Adds a Start Menu entry and registers an uninstaller in Windows Installed Apps.
- On first use, creates `%APPDATA%\.pyaedt_mcp\.venv` and uses bundled CPython 3.13 and `uv` to install `ansys-aedt-mcp` from PyPI.
- Supports offline installation from the Settings tab. Each install or update prompts you to select a Python 3.13 wheelhouse ZIP and installs only from that archive, without querying package indexes.
- Saves the offline installation selection in `%APPDATA%\.pyaedt_mcp\settings.yaml`.
Opening the executable provides setup, HTTP server controls, AEDT options, and stdio or HTTP profiles for Copilot/VS Code, Claude, Cursor, Codex, and OpenCode.
### Install for development
```bash
git clone https://github.com/ansys/pyaedt-mcp.git
cd pyaedt-mcp
pip install -e .
pre-commit install
```
Or use `uv`:
```bash
git clone https://github.com/ansys/pyaedt-mcp.git
cd pyaedt-mcp
uv pip install -e .
pre-commit install
```
## Requirements
- Python 3.13 or later (3.13 recommended)
- [Git](https://git-scm.com/downloads) to install or run PyAEDT-MCP directly from this repository with `uv`
- AEDT 2022 R2 or later for gRPC workflows
- A local AEDT installation or a reachable remote AEDT gRPC endpoint
## Quick start
1. Start AEDT in gRPC mode when connecting to an existing session:
```bash
"C:\Program Files\ANSYS Inc\v261\AnsysEM\ansysedt.exe" -grpcsrv 50051
```
Or, just launch AEDT normally. It automatically starts a gRPC server.
> PyAEDT-MCP can also launch AEDT for you if it is not already running.
2. Choose an MCP transport:
- **stdio** is the simplest option for one local client. The client starts
PyAEDT-MCP automatically through `uvx` or from a cloned repository's
virtual environment.
- **HTTP** connects the client to a separately running server. Use it for
local development, Docker, or a remote server.
Start an HTTP server through `uvx` without cloning:
```bash
uvx --python 3.13 --index-strategy unsafe-best-match \
--from git+https://github.com/ansys/pyaedt-mcp.git ansys-aedt-mcp \
--transport http --http-host 127.0.0.1 --http-port 8080
```
3. Point an MCP client at the server:
Use the [IDE and client configuration guide](https://aedt-mcp.docs.pyansys.com/version/dev/getting_started/ide_configuration.html)
for short HTTP and stdio configurations for VS Code/Copilot, Claude,
OpenCode, and Codex, plus local virtual-environment instructions.
## Tool reference
For information on the available tools, see [Tools and capabilities](https://aedt-mcp.docs.pyansys.com/version/dev/user_guide/tools_and_capabilities.html) in the PyAEDT-MCP documentation.
## How the repository is organized
The core package is in `src\ansys\aedt\mcp`:
| File | Role |
| --- | --- |
| `__main__.py` | Module entry point that forwards to the CLI launcher |
| `server.py` | CLI parsing, app setup, context creation, startup cleanup, and transport selection |
| `tools.py` | Runtime tool implementations for AEDT lifecycle, project, scripting, and export workflows |
| `helpers.py` | Small utilities for probing endpoints, normalizing versions, and extracting model data |
| `prompts.py` | System prompt content shown to MCP clients |
| `contexts.py` | Optional context helper tools enabled by `--include-context` |
| `toolsets.py` | `toolsets://definition` resource used for logical tool discovery |
| `aedt_helper\startup_code.py` | Startup code loaded into the persistent Python session |
Other top-level folders include:
- `doc\source`: Sphinx documentation
- `tests`: Unit and integration coverage
- `docker`: Container assets
- `examples`: Sample assets used by the project
## Development workflow
To contribute, see [Contribute](https://aedt-mcp.docs.pyansys.com/version/dev/getting_started/contribution.html) in the PyAEDT-MCP documentation.
## Add a new tool
Most tools require a live AEDT connection. Tag those tools with `REQUIRES_AEDT_TAG` in `src\ansys\aedt\mcp\tools.py` so they can be hidden until the session exists when dynamic discovery is enabled.
For more information, see [Add a new tool](https://aedt-mcp.docs.pyansys.com/version/dev/examples/adding_new_tool.html) in the PyAEDT-MCP documentation.
## License
Apache 2.0 license. See [LICENSE](LICENSE).
## Related projects
- [PyAEDT](https://github.com/ansys/pyaedt)
- [PyAEDT documentation](https://aedt.docs.pyansys.com/)
- [FastMCP documentation](https://github.com/jlowin/fastmcp)
- [Model Context Protocol documentation](https://modelcontextprotocol.io/)
## Repository provenance · 仓库来源
Independent copy of [HNNUYUXUAN/pyaedt-mcp](https://github.com/HNNUYUXUAN/pyaedt-mcp), derived from [ansys/pyaedt-mcp](https://github.com/ansys/pyaedt-mcp). Original authorship and license notices are preserved.
TDQS
Scored across 21 tools
Most tools target a distinct resource+action, and descriptions clarify boundaries like launch_aedt vs connect_to_aedt, and check_aedt_installed vs check_aedt_status. Overlap remains in a few spots: list_designs also returns projects (overlapping list_projects), get_model_info overlaps check_aedt_status's project/design reporting, and run_python_script vs run_python_code differ only subtly in execution context.
Nearly all tools follow a clean snake_case verb_noun pattern (launch_aedt, list_projects, create_design, export_results, validate_design). The only deviation is the bare noun 'screenshot', which breaks the otherwise predictable pattern.
21 tools is on the higher side but each maps to a real capability across connection lifecycle, project/design management, script execution, and reporting. The set is somewhat broad, with display_html being peripheral to the core AEDT workflow, but nothing feels redundant filler.
Core workflows (launch/connect, project open/save, design create/validate/analyze, results export, script execution) are covered. However there are notable asymmetries: no create_project or close_project, no delete operations for projects/designs, and export_config has no matching import_config, leaving agents with dead ends for common lifecycle steps.