# ANSYS Icepak MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that enables AI assistants to interact with **ANSYS Icepak** through natural language commands, powered by [PyAEDT](https://aedt.docs.pyansys.com/) over gRPC.

Import geometry, assign materials and thermal loads, build meshes, run natural/forced convection simulations, and retrieve results — all by chatting with Claude.

> **Status: work in progress.** Core geometry/material/mesh/solve workflow is functional; expect rough edges (see [Known Issues](#known-issues)).

---

## Compatible Clients

| Client | Supported |
|---|---|
| Claude Desktop | ✅ |
| Cursor | ✅ |
| Windsurf | ✅ |
| VS Code (Copilot) | ✅ |
| Any MCP-compatible client | ✅ |

---

## Capabilities

### Connection Management
| Tool | Description |
|---|---|
| `connect_to_icepak` | Connect to a running AEDT/Icepak session via gRPC port |
| `check_connection` | Check current connection status |
| `disconnect` | Release the Icepak connection without closing the project |

### Geometry
| Tool | Description |
|---|---|
| `create_box` | Create a rectangular box primitive |
| `create_cylinder` | Create a cylinder primitive |
| `create_sphere` | Create a sphere primitive |
| `create_region` | Create the domain Region object (percentage/absolute offset or position padding) |

### Materials
| Tool | Description |
|---|---|
| `list_materials` | List all materials in the active project |
| `assign_material` | Assign a material to an existing geometry object |

### Thermal & Flow Boundaries
| Tool | Description |
|---|---|
| `assign_source_power` | Assign a fixed heat-source power (W) to an object |
| `assign_opening` | Assign an opening boundary on all faces of an object (e.g. the Region) |
| `assign_grille` | Assign a grille (perforated) boundary with free-area ratio / loss coefficient |
| `create_fan` | Create a fan object (circular or other cross-section) |

### Solution Setup
| Tool | Description |
|---|---|
| `create_solution_setup` | Create a steady-state temperature-and-flow solution setup (iterations, convergence, flow regime) |

### Solve & Results
| Tool | Description |
|---|---|
| `solve` | Launch the Icepak solver for one or all setups |
| `get_solve_status` | Check solved/unsolved status of all setups |
| `export_field_summary` | Export a field summary report (e.g. max/min Temperature over a volume or object) |

### Scripting
| Tool | Description |
|---|---|
| `run_icepak_script` | Execute arbitrary PyAEDT/Python code against the live Icepak session (runs in background, returns a job ID) |
| `get_script_result` | Poll the output of a background script job |

---

## Requirements

- ANSYS Electronics Desktop (AEDT) 2023 R1 or later with Icepak
- Python 3.10+
- PyAEDT (`ansys-aedt-core` or `pyaedt`)

---

## Installation

```bash
git clone https://github.com/NedaEmami123/icepak-mcp.git
cd icepak-mcp
python -m venv venv
venv\Scripts\activate       # Windows
pip install ansys-aedt-core mcp
```

---

## Configuration

Find your client's config file and add the `icepak-mcp` server entry:

| Client | Config file location |
|---|---|
| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | `%APPDATA%\Roaming\Cursor\User\globalStorage\cursor.mcp\mcp.json` |
| Windsurf | `%APPDATA%\Windsurf\User\globalStorage\codeium.windsurf\mcp_config.json` |
| VS Code | `.vscode/mcp.json` in your workspace |

Add this block:

```json
{
  "mcpServers": {
    "icepak-mcp": {
      "command": "C:/path/to/icepak-mcp/venv/Scripts/python.exe",
      "args": ["C:/path/to/icepak-mcp/icepak_mcp_server.py"],
      "env": {
        "ANSYSEM_ROOT261": "C:/Program Files/ANSYS Inc/v261/AnsysEM"
      }
    }
  }
}
```

> Replace `v261` with your installed AEDT version (e.g. `v232`, `v241`, `v251`).

---

## Usage

### 1. Start Icepak and get the gRPC port

Open ANSYS Electronics Desktop with an Icepak design. In the **Message Manager**, look for:
```
gRPC server started on port 50051
```

### 2. Connect Claude to Icepak

In your chat with Claude:
> *"Connect to Icepak"*

### 3. Build and solve a thermal model

> *"Import this STEP file, assign materials, create a natural convection region, add source power to the chips, mesh, and solve."*

Claude will typically:
- Import CAD geometry (via `run_icepak_script` + PyAEDT's `import_3d_cad`)
- Assign materials per object
- Create a properly-sized air Region (natural or forced convection padding rules)
- Assign source power / opening / grille boundaries
- Create a solution setup and mesh regions
- Solve and pull back field summaries or plots

### 4. Poll for results (long jobs)

Long workflows (imports, scripted geometry edits, mesh generation) run in the background. Claude will give you a `job_id` and poll automatically:
> *"Get script result for job_1"*

---

## Known Issues

- The AEDT gRPC bridge can intermittently lock up on certain calls (e.g. `GetObjectsInGroup`, `GetSetups`) after heavy geometry/mesh-region churn or a stuck dialog in the AEDT GUI. Disconnecting/reconnecting (`disconnect` + `connect_to_icepak`) usually recovers it; a full AEDT restart is sometimes required.
- `solve` blocks synchronously and can time out the MCP client on long solves even though AEDT keeps solving in the background — poll `get_solve_status` afterward rather than re-triggering `solve`.
- No dedicated tools yet for field plots, mesh regions, or design duplication — use `run_icepak_script` with raw PyAEDT calls for these.

---

## License

Apache 2.0 — see [LICENSE](LICENSE)