solidworks-mcp

MCP server for SolidWorks automation. It drives a running SolidWorks over COM so an LLM (or any MCP client) can open and save native parts/assemblies/drawings, read and write driving dimensions, switch configurations, rebuild, export STEP, and run prebuilt VBA macros — the sw_* tools below.

It also ships an optional, cross-platform build123d code-CAD engine: generate geometry from Python code (OpenCascade/OCCT B-rep) with PNG visual feedback, then export STEP and hand it to SolidWorks. Useful when it is easier to write a part than to model it by hand — but secondary to the SolidWorks surface.

Status: working skeleton. The sw_* tools register automatically wherever pywin32 is present; exercising them against live geometry needs a Windows machine with a running, licensed SolidWorks. See Verification status at the bottom for exactly what has been run vs. what needs SolidWorks installed.

---

SolidWorks tools (sw_*) — the primary surface

These register by default on any machine where pywin32 imports (see Install / Enabling & disabling below). They talk to a running, licensed SolidWorks (2021–2025+) over COM. Units at this boundary are millimetres (the bridge converts to/from SolidWorks' native metres).

Tool	What it does
sw_connect(launch_if_needed=False)	Attach to (or optionally launch) SolidWorks; returns its revision
sw_open(filepath)	Open a native .sldprt / .sldasm / .slddrw; returns its title
sw_save(filepath=None)	Save in place, or Save As to a path
sw_close(save_first=False)	Close the active document
sw_export_step(output_path)	Export the active model to STEP (forces .step, clears selection first)
sw_rebuild(force=False)	EditRebuild3 (changed only) / ForceRebuild3 (whole tree)
sw_get_dimension(name)	Read a named driving dimension in mm (e.g. D1@Sketch1)
sw_set_dimension(name, value_mm, do_rebuild=True)	Set a named dimension and rebuild
sw_list_configurations()	List configuration names of the active document
sw_activate_configuration(name)	Activate a configuration by name
sw_run_macro(macro_path, module_name, procedure_name)	Run a prebuilt VBA macro via RunMacro2

It is not headless. Like every SolidWorks COM integration it drives the desktop GUI, so a SolidWorks instance must be open (or let sw_connect(launch_if_needed=True) start one — that can take up to a minute). Registering the tools does not start SolidWorks; the app is only touched on an actual sw_* call. Call sw_connect once before the other sw_* tools.

Fail-loud, no silent fallback. With the tools registered but no SolidWorks running, a real call fails with a clear SolidWorks not available error rather than pretending to succeed — by design.

Example calls (what the agent sends)

// sw_connect — attach to a running SolidWorks (or launch it)
{ "launch_if_needed": true }
// -> "33.4.0"  (revision string)

// sw_open — open a native part
{ "filepath": "C:\\work\\bracket.sldprt" }

// sw_set_dimension — widen a feature to 50 mm and rebuild
{ "name": "D1@Sketch1", "value_mm": 50.0, "do_rebuild": true }

// sw_export_step — STEP out for downstream interop
{ "output_path": "C:\\work\\bracket.step" }

COM signature accuracy (note). The bridge uses late binding (win32com.client.Dispatch), which is enough for these methods. For exact early-bound signatures (complex ByRef structs / overloads), generate a typed wrapper from the official SolidWorks Type Library with pywin32 makepy — python -m win32com.client.makepy "SOLIDWORKS <ver> Type Library" (or win32com.client.gencache.EnsureModule(...)). The TLB plus help.solidworks.com (API Help) are the legal, sufficient sources. Reverse-engineering the SolidWorks binaries (Ghidra, etc.) is not used and is not needed — Dassault Systèmes' EULA forbids it, and the TLB + API Help fully cover the signatures.

See NOTICE for third-party attribution (the bridge is original code; API signatures and patterns were informed by two MIT-licensed reference projects).

---

build123d engine (optional, cross-platform)

A secondary code-CAD surface: send build123d Python code, get back a part with a PNG preview so the model can see the geometry instead of generating blind. It runs headless (no SolidWorks, any OS), and its STEP export feeds straight into SolidWorks via sw_open / downstream tooling.

Tool	What it does	Returns
generate_part(code)	Run build123d code in the sandbox	PNG preview (image) + metrics (bbox, size, volume, CoM) + part_id
render_views(part_id)	Isometric + front + top + right views	PNG image
export_model(part_id, format, path)	Write step or stl to disk	status JSON
run_drc(part_id, min_wall, max_bbox)	Minimal DFM: volume>0, max size, min-dimension proxy	pass/fail per check
batch_generate(specs)	Many parts in one call (list of code strings)	per-spec part_id/metrics or error
list_catalog(query)	bd_warehouse standard parts — STUB / TODO	stub note

Contract for generate_part code: build your part and bind the final solid to a variable named result. Allowed imports: build123d, bd_warehouse, math/cmath/statistics/random/itertools/functools. Blocked (loudly): os, sys, subprocess, eval, exec, open, dunder-attribute escapes, etc.

with BuildPart() as p:
    Box(40, 30, 10)
    with Locations((0, 0)):
        Hole(radius=4)
result = p.part

// generate_part
{ "code": "with BuildPart() as p:\n    Box(40, 30, 10)\n    with Locations((0,0)):\n        Hole(radius=4)\nresult = p.part" }
// -> image (PNG) + { part_id: "part_1", metrics: { size:{x:40,y:30,z:10}, volume: ... } }

// render_views  -> 4-up PNG
{ "part_id": "part_1" }

// export_model  -> STEP you can open in SolidWorks
{ "part_id": "part_1", "format": "step", "path": "C:\\tmp\\plate.step" }

---

Install

Requires Python 3.12–3.14 (3.12 recommended). On Windows, the SolidWorks sw_* tools need pywin32 (the [solidworks] extra). The build123d engine pulls in cadquery-ocp (the OCCT binding); prebuilt Windows/macOS/Linux wheels exist for CPython 3.10–3.14.

With uv (recommended)

cd C:\Users\<you>\Desktop\solidworks-mcp
uv venv --python 3.12              # create venv with a known-good interpreter
uv pip install -e ".[solidworks]"  # SolidWorks (pywin32 on Windows) + build123d engine
# add test deps (and the optional standard-parts library) too:
uv pip install -e ".[solidworks,warehouse,dev]"

With pip / venv

cd C:\Users\<you>\Desktop\solidworks-mcp
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[solidworks]"

The [solidworks] extra adds pywin32 on Windows only. On macOS/Linux it installs nothing extra and the sw_* tools simply do not register — the build123d engine still works. If cadquery-ocp has no wheel for your exact Python, use Python 3.12 (widest wheel coverage); build123d cannot run without it.

---

Run the server

# from the project venv:
python -m solidworks_mcp.server   # stdio transport (what MCP clients spawn)
# or via the console script:
solidworks-mcp

It speaks MCP over stdio — there is no port; the MCP client launches the process and talks over stdin/stdout. On startup the sw_* tools register automatically if pywin32 is importable (see below); the build123d tools always register.

Enabling & disabling the SolidWorks tools

• Default (Windows + pywin32): the sw_* tools register automatically. No flag needed. Registration does not launch SolidWorks.
• No pywin32 / non-Windows: the sw_* tools are skipped (logged), the server starts normally, and the build123d tools remain available.
• Opt out: set SOLIDWORKS_MCP_DISABLE=1 to force the build123d-only surface even where pywin32 exists.

# build123d-only, even on a SolidWorks machine:
$env:SOLIDWORKS_MCP_DISABLE = "1"
python -m solidworks_mcp.server

Quick standalone check (no MCP client)

python examples\plate_with_holes.py   # builds a build123d demo part, writes STEP + STL, prints metrics

---

Register in Claude Code / an MCP client

Use the venv's Python so pywin32 / build123d resolve. Replace the path with your venv.

Claude Code (CLI)

claude mcp add solidworks-mcp -- C:\Users\<you>\Desktop\solidworks-mcp\.venv\Scripts\python.exe -m solidworks_mcp.server

Or edit the MCP config JSON directly

Claude Code project config (.mcp.json) or a client's mcpServers block:

{
  "mcpServers": {
    "solidworks-mcp": {
      "command": "C:\\Users\\<you>\\Desktop\\solidworks-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "solidworks_mcp.server"]
    }
  }
}

On macOS/Linux the command is .venv/bin/python instead of .venv\Scripts\python.exe. After adding it, restart the client and confirm the solidworks-mcp tools appear.

---

Project layout

solidworks-mcp/
├── pyproject.toml            # deps, entry-point (solidworks-mcp = solidworks_mcp.server:main)
├── README.md
├── src/solidworks_mcp/
│   ├── server.py             # FastMCP server: registers sw_* + build123d tools, wraps PNG -> image
│   ├── sw_tools.py           # sw_* FastMCP wrappers (register by default; gated by pywin32 + opt-out)
│   ├── solidworks_bridge.py  # SolidWorks COM bridge (lazy pywin32, fail-loud)
│   ├── tools.py              # build123d engine: tool logic + part registry + metrics + DRC
│   ├── render.py             # HLR PNG previews (iso + 3 ortho), headless matplotlib
│   └── sandbox.py            # AST whitelist: blocks os/sys/subprocess/eval/open/dunder
├── examples/
│   └── plate_with_holes.py   # parametric build123d demo part (also runnable standalone)
└── tests/
    └── test_smoke.py         # end-to-end build123d loop: generate -> render -> drc -> export; sandbox gate

---

Security note

generate_part executes model-authored Python. The AST whitelist (sandbox.py) rejects dangerous imports/builtins/dunder access before execution and runs with a restricted builtins namespace. This is a deny-by-default static gate, not a full security boundary on its own. For multi-user or untrusted deployment, add OS-level isolation (separate worker process, execution timeout, no network) — see the TODOs.

TODO before production

• OS-level sandbox isolation: run generated build123d code in a separate process with a hard timeout and no network (the AST gate is in-process today).
• Real DFM: true minimum wall thickness (medial axis / ray casting), overhang angle for FDM, clearance/interference between solids — port from cad-khana.
• bd_warehouse catalog: wire list_catalog to real part generators (gears, flanges, bearings, fasteners).
• Session persistence / limits: the build123d part registry is in-memory and resets on restart; add eviction/limits if sessions grow.
• More sw_* coverage: assembly mates, feature creation, drawing views, BOM export — the bridge covers the common open/edit/export/rebuild loop today.

---

Verification status

• python -m py_compile on every module — clean.
• pytest (build123d engine smoke + sandbox gate) — green (13 tests) when build123d/OCP is installed; the suite skips cleanly if it is not.
• The server imports and starts; the build123d tools register, and the sw_* tools register whenever pywin32 is importable.
• The sw_* tools have not been exercised against live geometry here — that requires a Windows machine with a running, licensed SolidWorks. Without one, a real sw_* call fails loud with SolidWorks not available, which is the intended behaviour.