# solidworks-mcp-2

[![CI](https://github.com/rdolan5/solidworks-mcp-2/actions/workflows/ci.yml/badge.svg)](https://github.com/rdolan5/solidworks-mcp-2/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11-3.13](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](pyproject.toml)

An MCP (Model Context Protocol) connector that drives **SOLIDWORKS 2025** and
**SOLIDWORKS CAM 2025** through COM automation, so an MCP client like Claude
can model parts and assemblies, produce drawings, and generate real,
posted G-code — with real geometry, real mass properties, and real files on
disk, not a simulation of any of those things.

It is a ground-up rebuild of the `solidwprks-mcp` predecessor concept: one
dedicated STA worker thread owns every COM object, clients get opaque session
handles instead of raw pointers, every dimensional value has an explicit unit
convention, and 13 grouped MCP tools give ~122 modeling/CAM operations their
own typed Pydantic schema instead of one giant generic surface. See
`docs/architecture.md` for the full design.

## Status

Code-complete for this release: 474 tests passing against a fake-COM layer,
`ruff`/`mypy` clean, and — unusually for a project at this stage —
**live-verified against a real, licensed SOLIDWORKS 2025 + SOLIDWORKS CAM 2025
installation**. That pass found and fixed 9 real bugs the fake-COM suite alone
had not caught, and it honestly documents 2 remaining live-flakiness issues.
See "Verified" below and `docs/verification/VERIFICATION.md` for the full,
unedited report.

## Install

Requires 64-bit Windows and, to actually connect to SOLIDWORKS,
a licensed **SOLIDWORKS 2025** (revision 33.x) installation. The package
itself installs and its non-live test suite runs on any OS.

```powershell
git clone https://github.com/rdolan5/solidworks-mcp-2.git
cd solidworks-mcp-2
uv sync
```

or with plain `pip`:

```powershell
python -m venv .venv
.venv\Scripts\pip install -e .
```

Verify the install (no SOLIDWORKS process launched):

```powershell
uv run solidworks-mcp --doctor
```

## Configure Claude Desktop

Add to `claude_desktop_config.json`'s `mcpServers`:

```json
{
  "mcpServers": {
    "solidworks": {
      "command": "C:\\path\\to\\solidworks-mcp-2\\.venv\\Scripts\\solidworks-mcp.exe",
      "args": ["--workspace", "C:\\Users\\you\\Documents\\SOLIDWORKS-MCP"]
    }
  }
}
```

## Configure Claude Code

```powershell
claude mcp add solidworks -- C:\path\to\solidworks-mcp-2\.venv\Scripts\solidworks-mcp.exe --workspace C:\Users\you\Documents\SOLIDWORKS-MCP
```

Full step-by-step (both clients, troubleshooting) in
`docs/configuring-claude.md`.

## Tool catalog

~40 MCP tools total: 13 **grouped** tools (each dispatching on a typed
`operation` field to one of ~122 capability-module functions) plus 27
**standalone** tools for connection, generic COM access, document lifecycle,
and CAM connection. Every operation name below is exactly the string you pass
as `payload.operation`; the authoritative, always-current mapping is
`src/solidworks_mcp/specs.py`'s `TOOL_OPS` table.

| Grouped tool | Operations | Docs |
|---|---|---|
| `solidworks_reference_geometry` | plane, axis, coordinate_system(_numeric), point | `docs/cad-tools.md` |
| `solidworks_sketch` | begin, exit, add_entities, fillet, chamfer, offset, convert_entities, mirror, add_relation, add_dimension | `docs/cad-tools.md` |
| `solidworks_feature` | extrude(_cut), revolve(_cut), sweep(_cut), loft(_cut), boundary, fillet, chamfer, shell, draft, rib, wrap, dome, hole_wizard, simple_hole, thread, mounting_boss, mirror, delete, modify | `docs/cad-tools.md` |
| `solidworks_pattern` | linear, circular, mirror, curve_driven, sketch_driven, table_driven, fill | `docs/cad-tools.md` |
| `solidworks_body` | combine, split, move_copy, cavity, indent, scale, list, delete | `docs/cad-tools.md` |
| `solidworks_parametric` | get/set_dimension, add_equation, add_global_variable, list/delete_equation, link_dimensions | `docs/cad-tools.md` |
| `solidworks_material` | apply, get, custom_density, get_density, color | `docs/cad-tools.md` |
| `solidworks_configuration` | add, activate, list, delete, set_config_dimension, get/delete/insert_design_table | `docs/cad-tools.md` |
| `solidworks_analyze` | bounding_box, mass_properties, measure, section_properties, check_geometry, interference, draft_analysis, thickness_analysis | `docs/cad-tools.md` |
| `solidworks_assembly` | insert_component(s), mate, fix, float, move/rotate_component, replace_component, pattern/mirror_components, interference, clearance, explode, collapse, bom | `docs/assemblies.md` |
| `solidworks_drawing` | new_from_model, model_view, standard_3view, projected_view, section_view, detail_view, insert_dimensions, add_annotation, insert_bom, set_sheet_format, export | `docs/drawings.md` |
| `solidworks_exchange` | export, import | `docs/cad-tools.md` |
| `solidworks_cam` | list_machines, set_machine, set_post, define_stock, recognize_features, define/list_features, list_setups, generate_operation_plan, list_operations, set_operation_parameter, set_tool, generate_toolpaths, simulate, check_collisions, post_process, setup_sheet, techdb_query, save_cam_data | `docs/cam.md` |

Standalone tools: `solidworks_discover`, `solidworks_connect`,
`solidworks_api`/`solidworks_batch`/`solidworks_array`/`solidworks_release`,
`solidworks_api_load`/`solidworks_api_search`, `solidworks_active_document`,
`solidworks_templates`, `solidworks_new_document`/`open_document`/`save`,
`solidworks_rebuild`, `solidworks_inspect`, `solidworks_assembly_tree`,
`solidworks_mass_properties`, `solidworks_sketch_begin` (legacy convenience),
`solidworks_persistent_reference`/`resolve_reference`,
`solidworks_modify_feature`, `solidworks_cam_connect`/`cam_status`/`cam_workflow`
(legacy low-level CAM dispatcher), `solidworks_script`, `solidworks_job`/
`cancel_job`.

## Units and selection conventions

Every dimensional field accepts a value plus an optional `unit`, defaulting to
**millimetres** for length and **degrees** for angle (SOLIDWORKS' COM API
itself is always metres/radians/kilograms internally — this connector
converts at the boundary in both directions). Full convention, including
handle lifetime and document-targeting rules, in
`docs/units-and-conventions.md`.

## Safety model

- **Workspace sandboxing**: every file-writing tool (`solidworks_save`,
  `solidworks_exchange`'s `export`, CAM's `post_process`, drawing `export`)
  resolves its destination through `Runtime.output_path`, which rejects any
  path that resolves outside the configured `--workspace` directory
  (default `~/Documents/SOLIDWORKS-MCP`). A relative path is resolved inside
  the workspace; an absolute path elsewhere on disk is refused.
- **`--allow-scripts`**: `solidworks_script` executes arbitrary trusted Python
  on the COM apartment — full local code execution with the OS user's
  permissions, not a sandbox. It is only registered when the server is
  started with `--allow-scripts`; omit that flag (the default) to disable it
  entirely.
- **Generic API access is still full-trust local automation**:
  `solidworks_api`/`solidworks_batch` expose the complete COM surface,
  including calls that can modify documents, run macros, or touch the local
  filesystem outside the workspace sandbox via COM's own file APIs (the
  sandbox is enforced at this connector's boundary, not inside SOLIDWORKS
  itself). Treat granting an MCP client access to this server as granting it
  the same trust you'd give a local automation script running as you.
- **CAM is never treated as proof of a license or of manufacturing
  correctness.** An installed product, a registered add-in, or a successful
  API connection does not establish CAM license entitlement — see "CAM notes"
  below. A void COM return is documented as void, not silently reinterpreted
  as success.

## `--doctor`

```powershell
uv run solidworks-mcp --doctor
```

Prints installed SOLIDWORKS/SOLIDWORKS CAM versions, registered add-ins, and
library paths as JSON, discovered from the Windows registry and filesystem —
no SOLIDWORKS process is launched. Use it first when `solidworks_connect` or
CAM tools aren't behaving as expected.

## CAM notes

SOLIDWORKS CAM access requires the add-in to be **installed and registered**
(discovered from the registry, never guessed) and, separately, a **valid
license** — the connector's own `cam.status()` deliberately reports
`license: "unknown"` even when the API connection succeeds, because an API
connection is not license proof. License checks (`solidworks_cam_workflow`'s
`license` action) require an explicit vendor module name and are recorded
per-module, not aggregated into a blanket "licensed" flag. Full detail,
including the confirmed add-in identifier/entry point and the CAM operation
table, in `docs/cam.md`.

## Verified

`docs/verification/VERIFICATION.md` is a from-scratch run against a real,
licensed SOLIDWORKS 2025 SP5.0 + SOLIDWORKS CAM 2025 installation — every
number, error message, and G-code line in it is copied verbatim from an
actual run, not fabricated:

| Scenario | Result |
|---|---|
| Complex part | Partial pass (27/29 steps). Real mass `7.9877 g`, volume `2.9584e-6 m³`, bounding box `80x50x20mm`, STEP/STL/SLDPRT written. |
| Assembly | Partial pass. 3 real components inserted/rebuilt/fixed, 4 real interferences detected before mating, `[]` after, real BOM rollup, SLDASM+STEP written. |
| Drawing | **Full pass (9/9 steps).** Standard 3-view, section view, detail view, model dimensions, PDF + DXF export, SLDDRW saved. |
| CAM → G-code | Core pipeline pass (8/10 steps). Real CAMWorks connection, 2 machinable features recognized, **225 lines of real G-code** posted to a real `.nc` file. |

That pass also found and fixed **9 real bugs** in this codebase (wrong COM
member names, `ByRef`/VARIANT marshalling, treating void-but-successful
returns as failures, an unopened-referenced-file assembly-insert bug) — see
the report for the full list with exact interfaces and members.

### Known issues (not hidden)

- **`FeatureLinearPattern5`/`FeatureCircularPattern5`** (`solidworks_pattern`'s
  `linear`/`circular` operations) consistently return `Nothing` against this
  SOLIDWORKS 2025 install despite a confirmed-correct signature and roughly a
  dozen parameter/selection variations tried. Open, unresolved blocker.
- **`AddMate5`** (`solidworks_assembly`'s `mate` operation) is intermittently
  flaky in this headless COM automation context — selection sometimes reports
  zero selected objects immediately after component insertion, and the mate
  call itself sometimes returns an unknown error even with a verified
  selection. One isolated run did succeed with an identical call, confirming
  the API itself works; the flakiness wasn't fully root-caused in the time
  available.
- **CAM operation-collection enumeration** (`solidworks_cam`'s
  `list_operations`) has nothing to enumerate because `generate_operation_plan`
  returns `None` even though the plan demonstrably exists (toolpath generation
  and posting both succeed and produce real G-code). Only the introspection
  step is unverified.

See `docs/verification/VERIFICATION.md`'s "Known gaps / confirmed blockers"
section for the full detail on all three.

## Examples

Worked, documented scripts under `examples/` — adapted from the exact
sequences run in live verification, not hypothetical code:
`complex_part_bracket.py`, `parametric_housing.py`, `gearbox_assembly.py`,
`drawing_from_part.py`, `cam_mill_part_to_gcode.py`.

## Documentation

- `docs/architecture.md` — STA worker/bridge/gateway/runtime design
- `docs/cad-tools.md` — geometry/sketch/feature/pattern/body/parametric/material/configuration/analyze
- `docs/assemblies.md`, `docs/drawings.md`, `docs/cam.md`
- `docs/units-and-conventions.md`
- `docs/configuring-claude.md`
- `docs/verification/VERIFICATION.md`

## Development

```powershell
uv sync
uv run pytest -m "not live and not cam"
uv run ruff check
uv run mypy src
```

See `CONTRIBUTING.md` for test tiers, code style, and how to add a new
operation. `CHANGELOG.md` covers what changed between the `solidwprks-mcp`
predecessor concept and this release.