sw-mcp

Let an AI agent (Claude, or any other MCP client) model real parametric parts and assemblies in your own SolidWorks — and check its own work. Every modelling call returns the measured volume, mass and bounding box, so the agent can compare the result with the spec and correct itself instead of guessing that it "looks about right".

sw-mcp is a fork of SolidWorks-MCP by Henk Jan Baard (solidworks-mcp 0.16.3 on PyPI). It adds manufacturing drawings, lofts and reference axes, run_script, and merges related tools into families so a client loads fewer of them; see Differences from upstream. It is the SolidWorks connector of Jig, and works on its own with any MCP client.

_{Built by the tools themselves: a mounting bracket (every step checked against a hand calculation), an M10 bolt with a real thread, a revolved + shelled vase, a swept pipe, a lofted + shelled horn.}

Why this server

• It verifies, not just generates. Features report measured geometry; dimensions and mates are measured back after the rebuild.
• Fully defined sketches. Every sketch is constrained the way a designer would: dimensions from the origin, relations only where the geometry is exactly horizontal, vertical or on the origin. Tools return their dimensions by role (width@Sketch1), so the part stays editable, in SolidWorks or through the agent.
• Real CAD, not just primitives. Extrude, revolve, sweep, loft and splines; holes, counterbores, slots and pockets on any face; rounded polygon corners; ISO holes from the Hole Wizard; real ISO metric threads; fillets, chamfers, shells, patterns, mirrors, ribs, equations and materials. Assemblies with mates and interference checks. STEP/STL/3MF export and screenshots. Engraved and embossed text. Work on existing parts: list, delete, suppress and reorder features; read, extrude and cut a person's sketches; import STEP. Colours per part or component. Joints with concentric and angle mates, checked over their range. Printability checks. Manufacturing drawings: ISO sheets with a title block, section and detail views, dimensions placed from model references (also baseline, chain and ordinate), counted hole callouts, surface finish, datum and geometric tolerance symbols, tables and computed gear data tables, notes, automatic layout, a sheet check, and drawings built from a spec. Planes at any offset or angle, or through a point square to any direction; axes anywhere, and circular patterns about them; lofts and loft cuts between sketches on any planes. Several bodies per part, combined and split. Variable fillets and full rounds. Free sketches with tangent arcs and splines. 91 tools in total, and run_script for what none of them covers (off unless allowed).
• It fails loud. A call that cannot do what was asked returns {ok: false, error} with the cause, never silently wrong geometry.
• A fixed, typed tool surface. The agent can only do what the tools allow. run_script, which runs arbitrary Python, is off unless you start the server with --allow-scripts.
• Tested against real SolidWorks. 697 tests; each feature's integration test compares the result with a hand calculation.
• Local. It talks to your running SolidWorks over COM; the server itself makes no network calls.

Quickstart

1. Install uv.

2. Start SolidWorks and leave it open (the server attaches to the running instance — it does not launch one).

3. Register the server with your MCP client.

   Claude Code:

   claude mcp add solidworks -- uvx sw-mcp
   

   Claude Desktop (claude_desktop_config.json) or any other client:

   {
     "mcpServers": {
       "solidworks": {
         "command": "uvx",
         "args": ["sw-mcp"]
       }
     }
   }
   

   With Jig there is nothing to register: the plugin starts sw-mcp itself.

4. Ask for a part, for example:

   Design a 100 × 80 × 8 mm mounting plate with a Ø16 mm centre bore, four counterbored M5 holes 12 mm from the corners and R5 corners. Check the volume against your own calculation, then export a fine STL.

Guidelines for agents

The server hands every MCP client short modelling guidelines when it connects (conventions, verify each step, known pitfalls). The full guide is the resource solidworks://guide: recipes for holes, ribs, threads and assemblies, 3D-print advice, and how to reverse-engineer a part from a mesh (STL/3MF). The same text is in src/sw_mcp/guide.md.

Requirements and compatibility

• Windows, with SolidWorks installed, licensed and running.

• Python 3.11+ (uv fetches one if needed).

• A Y-up part template, SolidWorks' standard. Since SOLIDWORKS 2025 new parts can also be Z-up; the tools build in the Y-up frame and refuse a Z-up part with a message that says so.

• Tested on SOLIDWORKS 2026 (3DEXPERIENCE R2026x). The API calls it uses exist since SOLIDWORKS 2020 SP2, so 2020–2025 should work, but that is untested. To check your installation, run this with SolidWorks open:

  uvx sw-mcp --selftest
  

  It builds a few small parts, compares each with a hand calculation and closes them unsaved. Please paste its output in a compatibility report, whether it worked or not.

Status: early (0.x). It works end-to-end, but tool names and conventions may still change. Versions restart at 0.1.0 for the fork. See CHANGELOG.md.

Troubleshooting

• Start with the selftest: uvx sw-mcp --selftest shows your SolidWorks release, language and templates, and which tool areas work. Add its output to a bug report.
• "No running SolidWorks found" / connection fails — SolidWorks must be running before you start the server or run a script; it attaches to the active instance via GetActiveObject and does not launch one.
• First call is slow or EnsureModule errors — the first COM call generates the makepy typelib wrappers under your temp gen_py folder. Let it finish; if it gets into a bad state, delete the gen_py cache and retry. Early binding is mandatory on this build (see Architecture).
• A feature returns {ok: false, error: ...} — that is by design: every tool fails loud with a readable message rather than silently producing wrong geometry. Read the message; it names the likely cause.
• Only tested against SOLIDWORKS 2026 (3DEXPERIENCE R2026x). On other builds the verified enum values or method signatures may differ — re-run scripts/introspect_api.py to inspect your installed typelib.

Development

Clone the repository, then install it editable into a venv:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .[dev]

To run the MCP server from this checkout instead of via uvx, point your client at the venv's Python:

{
  "mcpServers": {
    "solidworks": {
      "command": "C:\\path\\to\\sw-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "sw_mcp.server"]
    }
  }
}

Add "--allow-scripts" to args to switch on run_script, which runs any Python it is given on this computer.

Run the verification scripts

With SolidWorks open:

.\.venv\Scripts\python.exe scripts\probe_connection.py     # M0
.\.venv\Scripts\python.exe scripts\m1_block.py             # M1
.\.venv\Scripts\python.exe scripts\m2_parametric.py        # M2
.\.venv\Scripts\python.exe scripts\test_mcp_server.py      # M3 (full MCP loop over stdio)
.\.venv\Scripts\python.exe scripts\m5_demo_bracket.py      # M5 (3D-print bracket, every step verified)

scripts/introspect_api.py regenerates/inspects the installed typelib and prints verified enum values — run it if SolidWorks is upgraded and signatures change.

Tests

.\.venv\Scripts\python.exe -m pytest                 # all tests
.\.venv\Scripts\python.exe -m pytest -m "not solidworks"   # fast unit layer, no SolidWorks

Two layers: pure unit tests (units, selector/direction parsing, polygon cleaning, the component-placement maths, and that every MCP tool forwards its arguments to the right session method) run anywhere; integration tests (solidworks marker) drive a running SolidWorks and verify each feature's volume — or each component's placement — against a hand calc. They auto-skip if SolidWorks isn't reachable.

Tools

The server speaks MCP over stdio.

Part tools

Drawing tools

Sheet millimetres, origin at the sheet's bottom-left corner. Annotations are named <name>@<view>. Each family of drawing operations is one tool with a kind / type / action / style switch, so a client loads 16 drawing tools. Where geometry matters, tools take references into a view: edge:-x (the part's face facing -x, seen edge-on), hole:<feature>, feature:<name>, or a model point [x, y, z].

Assembly tools

export and screenshot work on assemblies too.

Faces are selected by direction in the component's own frame (+x, -z, …), so a selector keeps meaning the same face however the component is turned. Add :inner (e.g. +y:inner) for the cavity side of a hollow part — the inside of a room wall instead of its outer skin.

All linear dimensions are millimetres; the server converts to/from the SolidWorks-internal metre/radian units at the boundary.

Architecture

src/sw_mcp/
  binding.py     early-binding plumbing (wrap raw dispatches in generated classes)
  com_worker.py  one dedicated STA thread; all COM calls serialised through it
  session.py     SolidWorks operations (must run on the COM thread)
  server.py      FastMCP tools that delegate to session via the worker
  families.py    one tool per family: picks the session method from the arguments
  advanced.py    axes, lofts, planes by normal, run_script
  drawing.py     drawing tools (views, dimensions, symbols, tables, checks)
  drawing_layout.py  view and dimension placement (pure, no COM)
  image_sheet.py several views on one PNG (run_script's picture)
  constants.py   enum values read from the installed typelib (verified)
  units.py       mm<->m, deg<->rad
  errors.py      SolidWorksError -> agent-facing {ok:false,error}

Two non-obvious design decisions, both load-bearing:

1. Early binding is mandatory. On this build GetActiveObject returns a dispatch whose GetTypeInfo() fails, so EnsureDispatch/CastTo cannot infer types and pure late binding breaks (IModelDoc2.FirstFeature → DISP_E_MEMBERNOTFOUND). We generate makepy wrappers from the installed typelib and wrap each raw dispatch in the right interface class; calls then go by dispid via InvokeTypes, bypassing name resolution. See binding.py.

2. A dedicated COM thread. COM is STA and thread-affine. The MCP server runs on asyncio, so all COM work is pinned to one worker thread (com_worker.py) that handlers post to and await — actively enforcing the "one COM session, single-threaded" rule that does not hold automatically in an async server.

Status and roadmap

Proven end-to-end against SOLIDWORKS 2026 (3DEXPERIENCE R2026x):

See Docs/PROGRESS.md for the detailed log and roadmap. Feedback and contributions are welcome.

Known limitations

• Geometry so far: boxes, cylinders/cones (revolve), arbitrary extruded profiles, holes, polygon pockets/slots (cut_profile), fillets, chamfers, shells, linear + circular patterns (bolt circles); plus equations, materials, geometry inspection, and save/open of .sldprt, holes + pockets on any planar face (model→sketch transform), round flanges (disc + bore + bolt circle), and slotted holes (cut_slot, obround at any angle — the first arc-based sketch), general revolves (add_revolved_profile: any (r,z) profile → shafts, vases, rings), swept pipes/tubes (add_swept_pipe: a round profile along a rounded 2D path), and lofts (add_lofted_solid: blend stacked polygon profiles → transitions/adapters), free-form extrusions (add_extruded_spline: a smooth closed spline → organic/aesthetic outlines), and non-circular sweeps (add_swept_profile: any cross-section along a path → rails, gaskets, trim), and mirrors (add_mirror: features or the whole body about a plane through the part).
• Selection: plane walk, face-by-normal/direction (_planar_face_by_normal, +z/…, with :inner for the cavity side of a hollow part), and edge selection by axis or explicit index (_select_edges). list_faces/list_edges let an agent inspect geometry before selecting.
• Assemblies (M6): components, transforms, mates and interference detection. Component patterns, in-context features, configurations and Simulation (FEA) are out of scope.
• list_faces, list_edges and add_fillet see only the first body of a multibody part.

Differences from upstream

Forked from hjbaard/SolidWorks-MCP at 0.16.3. Added since (details in CHANGELOG.md):

• Manufacturing drawings: make_drawing on an ISO sheet with title block, counted hole callouts and hole positions, plus 15 drawing tools (views, sections, details, dimensions, hole callouts, surface finish, datums, GD&T, tables and gear data tables, notes, layout, a sheet check, build_drawing from a spec).
• Modelling: add_axis, add_loft (also loft cuts), circular patterns about any axis, planes through a point square to any direction, add_sketch(fixed=True), several mates in one call, replace_component.
• run_script (off unless allowed): a whole part from a script file in one call, with one report and a four-view picture.
• Tool families: related tools merged into one with a switch (add_hole, add_extruded_profile, cut_profile, new_document, ...), 91 tools in place of 106.
• Different names: the package is sw-mcp, the module sw_mcp.

Fixes from upstream are merged in from time to time. In a clone:

git remote add upstream https://github.com/hjbaard/SolidWorks-MCP.git
git fetch upstream && git merge upstream/main

Credits and license

MIT, see LICENSE. The original server is by Henk Jan Baard (hjbaard/SolidWorks-MCP); this fork is maintained by Nejc Dvorsek.