# solidworks-mcp

An [MCP](https://modelcontextprotocol.io) server that lets AI agents (Claude, ChatGPT, Cursor and any other MCP
client) design in **SolidWorks** on your computer: parametric parts, lofted wings and propellers, swept tubes,
sheet metal, weldment frames, assemblies with fasteners, GOST/ISO drawings, stress analysis and 3D-print checks.

Ask for *"a 5-inch tri-blade propeller with a 5 mm bore"*, *"an M6 tapped 3×2 hole grid in this plate"* or
*"a square-tube frame along this sketch, then the cut list"* - the agent calls the tools, checks the result with
screenshots and measurements, and exports the files.

[Русская версия](README.ru.md)

## Highlights

- **94 tools** covering modelling, parametrics, fabrication, assemblies, drawings and analysis.
- **Parametric by design:** named sketch dimensions, global variables, equations and configurations.
- **Aerospace generators:** wings (NACA 4/5-digit or `.dat` airfoils, taper, sweep, dihedral, twist), propellers
  (pitch-correct blade twist), fuselages from cross-sections.
- **Manufacturing:** Hole Wizard holes and real modelled threads, sheet metal with DXF flat patterns, weldment
  frames with cut lists, drawings with title-block properties, batch STEP/STL export.
- **Verification:** mass properties, measurements, requirement checks, overhang analysis for 3D printing,
  interference detection, SolidWorks Simulation static studies.
- **Robust:** failed features roll back automatically, every call has a timeout, a broken geometry kernel is
  detected, and every model change is journaled so a model can be rebuilt by replaying it.
- **Safe:** starting SolidWorks and overwriting files need the user's approval, writes are confined to allowed
  folders, and only a fixed list of operations is reachable (no macros, no "run any API").

## How it works

```
 Agent (Claude / ChatGPT / ...)
        │  MCP (stdio or HTTP)
        ▼
 solidworks-mcp  ───────────── Windows: talks to SolidWorks directly over COM
        │
        └── macOS: HTTP + token ──▶  solidworks-automation bridge   (inside a Windows VM)
                                              │ COM
                                              ▼
                                          SolidWorks
```

SolidWorks runs only on Windows. On a Mac, run it in a Windows VM and start the bridge inside the VM.

## Requirements

- SolidWorks 2018 or later (tested on SOLIDWORKS 2026); Simulation tools need a Premium or Simulation licence.
- Python 3.12+ and [uv](https://docs.astral.sh/uv/).

## Setup (Windows, same PC as SolidWorks)

```powershell
git clone https://github.com/pilotarbuza/solidworks-mcp C:\tools\solidworks_automation
cd C:\tools\solidworks_automation
uv sync
```

**Claude Desktop** - add to `claude_desktop_config.json` (use the full path of `uv.exe`, from `(Get-Command uv).Source`):

```json
{
  "mcpServers": {
    "solidworks": {
      "command": "C:\\Users\\you\\.local\\bin\\uv.exe",
      "args": ["--directory", "C:\\tools\\solidworks_automation", "run", "solidworks-automation"]
    }
  }
}
```

**Claude Code:**

```powershell
claude mcp add solidworks -- uv --directory C:\tools\solidworks_automation run solidworks-automation
```

**OpenAI Codex** (`~/.codex/config.toml`):

```toml
[mcp_servers.solidworks]
command = 'C:\Users\you\.local\bin\uv.exe'
args = ["--directory", 'C:\tools\solidworks_automation', "run", "solidworks-automation"]
startup_timeout_sec = 60
tool_timeout_sec = 1800   # starting SolidWorks, drawings and simulations take minutes
```

**HTTP clients:** `uv run solidworks-automation serve --transport streamable-http` serves `http://127.0.0.1:8000/mcp`.

### macOS (SolidWorks in a Windows VM)

1. In the VM: `uv sync` then `uv run solidworks-automation bridge --host 0.0.0.0 --port 8765`. It prints a token
   (or set `SW_BRIDGE_TOKEN`).
2. On the Mac: configure the client as above, with `"env": {"SW_BRIDGE_URL": "http://<vm-ip>:8765",
   "SW_BRIDGE_TOKEN": "<token>"}`. Keep the bridge on a host-only network or tunnel it over SSH.

## Tools

| Area | Tools |
|---|---|
| Session & documents | `sw_status`, `sw_health`, `sw_connect`, `sw_new_document` (part / assembly / drawing), `sw_open`, `sw_close` |
| Sketches | `sw_create_sketch` (lines, polylines with rounded corners, rectangles, circles, ellipses, arcs, polygons, slots, splines, points, NACA / `.dat` airfoils; patterns, mirroring, named dimensions, fully-defined sketches), `sw_create_3d_sketch` (paths with bend radii), `sw_sketch_info` |
| Solid features | `sw_extrude`, `sw_cut_extrude` (incl. thin walls), `sw_revolve`, `sw_loft` (solid / cut / surface, guides, tangency), `sw_sweep` (profile or circle, hollow tubes, twist), `sw_rib`, `sw_draft`, `sw_shell`, `sw_fillet`, `sw_chamfer`, `sw_mirror` |
| Curves, surfaces, bodies | `sw_helix`, `sw_spring`, `sw_planar_surface`, `sw_thicken`, `sw_combine` (union / subtract / intersect), `sw_move_copy_body`, `sw_scale`, `sw_delete_body`, `sw_list_bodies` |
| Reference geometry | `sw_create_plane` (offset or angled), `sw_create_axis` |
| Patterns | `sw_linear_pattern`, `sw_circular_pattern`, `sw_sketch_pattern`, `sw_curve_pattern` |
| Holes & threads | `sw_hole_wizard` (tapped, counterbore, countersink, clearance; ISO / DIN / ANSI), `sw_thread` (modelled helical thread), `sw_cosmetic_thread`, `sw_hole` |
| Parametrics | `sw_list_dimensions`, `sw_set_dimension`, `sw_rename_dimension`, `sw_set_variables`, `sw_add_equation`, `sw_list_equations`, `sw_delete_equation`, `sw_add_configuration`, `sw_activate_configuration`, `sw_list_configurations`, `sw_delete_configuration` |
| Appearance & material | `sw_set_appearance` (document, features, components, faces), `sw_clear_appearance`, `sw_set_material` |
| Aircraft & drones | `sw_generate_wing`, `sw_generate_propeller`, `sw_generate_fuselage`, `sw_assembly_mass` (centre of gravity) |
| Standard parts | `sw_generate_fastener` (ISO 4762 / 4017 / 4032 / 7089), `sw_generate_part` (L-bracket, flange, PCB enclosure, motor mount) |
| Sheet metal | `sw_sheet_metal_base` (flat or bent from open profiles), `sw_flat_pattern`, `sw_export_flat_pattern` (DXF/DWG) |
| Weldments | `sw_weldment_profiles`, `sw_structural_member` (mitred frames along a sketch), `sw_cut_list` |
| Assemblies | `sw_insert_component`, `sw_add_mate` (standard, symmetric, width, limit, gear, rack-pinion, screw, hinge, slot, lock), `sw_insert_fastener`, `sw_interference`, `sw_explode` / `sw_collapse`, `sw_bill_of_materials` (CSV), `sw_list_components` |
| Drawings | `sw_create_drawing` (GOST or default templates, standard + isometric views, model dimensions, BOM), `sw_add_drawing_view`, `sw_set_properties` / `sw_get_properties` (title block) |
| Inspection & analysis | `sw_list_features`, `sw_rebuild`, `sw_mass_properties`, `sw_list_entities`, `sw_screenshot`, `sw_measure`, `sw_check_requirements`, `sw_print_check`, `sw_static_study` |
| Files | `sw_save`, `sw_export` (STEP, IGES, STL, Parasolid, 3MF, PDF, DXF/DWG, PNG/JPG), `sw_batch_export` |
| Journal | `sw_journal`, `sw_replay_journal` |

Prompts: `model_from_drawing` (drawing → plan → build → verify) and `drone_part`.

All lengths are millimetres and angles degrees. Model space is Y-up with the Front plane at Z = 0.

## Examples

**Parametric plate** - change one variable, the part follows:

```text
sw_set_variables  {"width": 80}
sw_create_sketch  entities=[{type: 'center_rectangle', center: [0,0], width: 80, height: 50, dimension: ['w', 'h']}]
sw_extrude        sketch='Sketch1' depth=6
sw_add_equation   dimension='w@Sketch1' expression='"width"'
sw_set_variables  {"width": 120}
```

**Wing** - root NACA 2412 to tip NACA 23012, 8° sweep, 4° dihedral, 3° washout, mirrored:

```text
sw_generate_wing  span=500 root_chord=180 tip_chord=100 root_airfoil='2412' tip_airfoil={naca: '23012'}
                  sweep=8 dihedral=4 twist=-3 sections=4
```

**Propeller** 5×4.5", three blades: `sw_generate_propeller diameter=127 pitch=114 blades=3 shaft_diameter=5`

**Bent tube:**

```text
sw_create_3d_sketch entities=[{type: 'polyline', points: [[0,0,0], [0,0,120], [0,80,120], [60,80,160]], bend_radius: 20}]
sw_sweep            path='3DSketch1' circle_diameter=12 wall_thickness=1.5
```

**Frame + cut list:** `sw_create_3d_sketch` (layout) → `sw_structural_member profile='square tube' size='20 x 20 x 2'`
→ `sw_cut_list`.

**Sheet metal U-channel for laser cutting:** sketch an open polyline → `sw_sheet_metal_base thickness=1.5
bend_radius=2 depth=40` → `sw_save` → `sw_export_flat_pattern`.

**Assembly with fasteners:** `sw_insert_component` (fixed) → `sw_insert_fastener kind='hex_bolt' size='M5' length=20
hole_face_point=[...] seat_face_point=[...]` → `sw_interference` → `sw_bill_of_materials csv_path='bom.csv'`.

**Stress check:** `sw_set_material '6061-T6 (SS)'` → `sw_static_study fixed_face_points=[[0,0,0]]
forces=[{face_point: [200,0,0], newtons: 100}]` → max von Mises stress, displacement and safety factor.

## Safety model

- **Starting SolidWorks needs the user's approval** (an MCP elicitation prompt, or explicit agreement in chat for
  clients that cannot prompt). The server never closes SolidWorks.
- **Edits stay in memory** until `sw_save` / `sw_export`. Failed features are rolled back.
- **Writes are confined** to `~/Documents/SolidWorksMCP` (`SW_MCP_OUTPUT_DIR`) and folders in `SW_MCP_ALLOWED_DIRS`.
  Existing files are replaced only with `overwrite=true`, which also asks the user. Batch exports ask first.
- **Deletion is limited** to features created in the current session; others can only be suppressed.
- **No arbitrary code:** only the operations in `ops.OPERATIONS` are reachable (also over the bridge).
- **Timeouts:** each call has a limit (`SW_MCP_TIMEOUT`, default 180 s; longer for simulations and drawings). If
  SolidWorks shows a dialog or hangs, the agent gets an error instead of waiting forever.
- **Journal:** model changes are logged to `~/Documents/SolidWorksMCP/journal/*.jsonl` (`SW_MCP_JOURNAL=0` turns it off).

## Configuration

| Variable | Meaning |
|---|---|
| `SW_MCP_OUTPUT_DIR` | Output folder (default `~/Documents/SolidWorksMCP`). |
| `SW_MCP_ALLOWED_DIRS` | Extra folders the server may write to (`;`-separated on Windows). |
| `SW_MCP_PART_TEMPLATE` / `SW_MCP_ASSEMBLY_TEMPLATE` / `SW_MCP_DRAWING_TEMPLATE` | Force a document template. |
| `SW_MCP_TIMEOUT` | Default per-call timeout in seconds (180). |
| `SW_MCP_JOURNAL` | `0` disables the journal. |
| `SW_MCP_WELDMENT_PROFILES` | Weldment profile library folder (default: the SolidWorks one). |
| `SW_BRIDGE_URL`, `SW_BRIDGE_TOKEN` | Use a remote bridge (macOS / VM setups). |

## Development

```powershell
uv sync
uv run pytest                                        # 100+ tests, no SolidWorks needed
uv run python examples/full_smoke.py                 # every tool group against a real SolidWorks
uv run python examples/full_smoke.py aero assembly   # selected groups
uvx ruff check src tests examples
```

Layout (`src/solidworks_automation/`):

- `ops/` - every SolidWorks API call, one mixin per topic (`sketch`, `features`, `patterns`, `holes`,
  `parametric`, `fabrication`, `assembly`, `drawing`, `inspect`, `simulation`, `generators`, ...), combined into
  `SolidWorksOps`. `@operation` marks what the server and bridge may call.
- `server/` - MCP tools and schemas, permission prompts, prompts.
- `geometry/` - pure Python: sketch expansion, airfoils, fasteners, colours, mesh checks (unit-tested).
- `com.py` - late-bound COM helpers and the COM thread; `backend.py` - local / remote execution with timeouts;
  `bridge.py` - token-authenticated HTTP bridge; `safety.py` - file policy; `journal.py` - operation journal.

## License

Copyright (c) 2026 Maksim Akhmadulin. All rights reserved - see [LICENSE](LICENSE).
SOLIDWORKS is a trademark of Dassault Systèmes; this project is not affiliated with it.