SolidWorks MCP — run, test & auto-fix VBA macros

An MCP server that connects to a running SolidWorks 2022 over COM (pywin32), runs your VBA macros (or inline VBA), inspects the resulting model, and returns structured diagnostics so Claude can fix errors and re-run until the model builds clean. It also ships an API-documentation pipeline that renders the JavaScript-only help.solidworks.com/2022 pages headlessly and extracts the method/enum facts that keep generated code correct.

Built to pair with the solidworks-vba skill: the skill writes verified-style macros; this server runs, tests and repairs them.

How it works

Claude (+ solidworks-vba skill)
        │  writes / fixes VBA
        ▼
  run_and_verify ──► COM worker thread (STA) ──► SolidWorks 2022
        │                                              │
        │   ◄── verdict: ran? rebuild errors?  ◄───────┘
        ▼        errored features? VBA error?
   if not success: read errors, regenerate, call again   (Claude-driven loop)

• Inline VBA is written to a temporary .swb and executed with RunMacro2 (SolidWorks compiles .swb text on the fly — no .swp authoring, no VBA trust-access setting needed).

• All COM access runs on one STA worker thread (COM objects are apartment-bound).

• Generated/automated macros use a silent log (SWMCP_Log) instead of MsgBox, and a dialog watchdog auto-dismisses stray modal dialogs so a macro can never deadlock the server.

• The server never edits your VBA. It returns rich errors; Claude fixes them.

Related MCP server: solidworks-mcp

Session-first fast workflow

Every modeling request should begin with prepare_modeling_context(request). It performs the complete preflight in one round trip:

1. Detect running SOLIDWORKS processes through their exact ROT monikers.

2. Auto-select the only session, or return the process list when a choice is required.

3. Stop with action=start_solidworks when no session is running—nothing is launched silently.

4. Return matching skills, professional design guidance, bundled Cosmon references, and local SOLIDWORKS CHM results before any code is generated.

5. Bind every subsequent modeling tool to the selected process.

sw_list_sessions, sw_select_session(process_id), and sw_disconnect_session provide explicit control. Execution suppresses graphics/tree churn reversibly, generated macros rebuild once, verification scans the feature tree once, and repeated Cosmon searches are served from memory.

Requirements

• Windows + SolidWorks 2022 (COM ProgID SldWorks.Application).

• Python 3.10+.

• A default part/assembly/drawing template configured in SolidWorks (Tools ▸ Options ▸ Default Templates) — macros abort cleanly if none is set.

Install

pip install -e .
python -m playwright install chromium   # one-time, for the docs pipeline

Register with Claude Code

Already registered at user scope during setup:

claude mcp add solidworks -s user -- C:/Python313/python.exe -m sw_mcp.server

Or, for a project-scoped, shareable config, drop a .mcp.json in the project root (see install/register-mcp.md). Confirm with claude mcp list (look for solidworks: ... ✓ Connected).

Tools

Session and preflight — prepare_modeling_context, sw_status, sw_list_sessions, sw_select_session, sw_disconnect_session

Professional design knowledge (proactive)

• get_design_guidance(query) — call this BEFORE modeling. Returns the matching professional archetype recipe (ordered feature sequence, design-intent practices, key dimensions), the relevant universal design principles, and — for tolerancing queries — a GD&T reference. Distilled from real SolidWorks tutorials (transcripts.txt) so the build tools produce a real engineered component instead of a bare block or cylinder.

• list_design_recipes() — the available archetypes (bearing, engine, bottle, manifold, revolved housing, mounting plate). See DESIGN_PLAYBOOK.md.

Execute & verify

• run_macro(path, module, procedure) — run an existing .swp/.swb.

• run_vba(code, procedure, module) — run an inline VBA string.

• run_and_verify(code | macro_path, …) — run → rebuild → scan → one verdict. The auto-fix-loop primitive.

Diagnostics — rebuild_model, get_build_errors, get_feature_tree, get_mass_properties, get_bounding_box, capture_screenshot

Documents — new_document, open_model, save_model, close_model, export_file (STEP/IGES/STL/X_T/PDF/PNG by extension)

Feature generators — single-feature primitives (verified-style VBA, each built → run → rebuilt → error-scanned). These are building blocks and smoke tests, not finished parts; a professional component is composed from them (plus inline run_vba) following the recipe from get_design_guidance: create_extrusion, create_cylinder, create_fillet, create_chamfer, create_shell, create_draft, create_rib (L-bracket + gusset), create_revolve (tube), create_sweep (swept groove), create_loft (lofted cut), create_hole_wizard (metric counterbore), create_thread (real cut thread), create_spring (helix + sweep), create_linear_pattern, create_mirror, create_circular_pattern, create_assembly (2 components fully mated). Surface modeling: create_surface_extrude, create_surface_planar, create_surface_revolve, create_surface_thicken (surface→solid). Sheet metal: create_sheet_base_flange (flat plate), create_sheet_lbracket (bent, real bend). Extend by adding builders to feature_tools.py (see below). Pattern variants not yet given a one-call tool (curve/sketch/table/fill), sheet-metal edge flange/hem/miter, and any other feature are fully buildable via run_vba + the solidworks-vba skill + the auto-fix loop.

Self-improving knowledge base — learn_rule, list_rules. Every fixed error becomes a persistent rule (resources/knowledge/rules.json, human-readable LESSONS.md). On failure, run_and_verify returns suggested_fixes matched from past rules, so the same mistake is never solved twice.

API docs — docs_lookup_method(interface, method), docs_lookup_enum(enum_name), docs_get(url). Read the remarks field — it holds the selection-mark/precondition details that separate working from crashing code.

Cosmon-compatible resources and skills — engineering_resources_status, list_engineering_resources, search_engineering_resources, get_engineering_resource, list_skills, get_skill, create_skill, update_skill, delete_skill, import_skill. The server bundles Cosmon's complete SOLIDWORKS documentation payload—including the large feature/function databases—plus C# templates, persistent-service source, and all 12 packaged skills. The installed Cosmon resources remain a fallback source. Set COSMON_RESOURCES_DIR for a non-default Cosmon location and SW_MCP_SKILLS_DIR for editable skill overrides.

The auto-fix loop

1. Claude writes a macro (via the solidworks-vba skill) and calls run_and_verify.

2. The verdict comes back: {success, ran, run_error, log[], log_errors[], errors[], errored_features[], suppressed_features[], feature_count}.

3. If success == false, Claude reads log_errors/errors (and looks up the exact API via docs_lookup_method), regenerates the corrected VBA, and calls run_and_verify again — until success == true.

Designing professional parts (not bare blocks)

The build loop only checks that geometry rebuilds — left alone, the simplest shape that builds clean is a block or a cylinder. To get a real engineered component, design intent has to come from somewhere. That is the get_design_guidance layer (design_library.py, surfaced from the tutorial transcripts):

1. Call get_design_guidance("<part description>") (e.g. "deep-groove ball bearing", "mounting base plate with bolt circle", "hollow exhaust manifold", "shaft tolerance / GD&T").

2. Follow the returned feature sequence and design-intent notes — revolve about a centerline, fully-define sketches, locate holes on a construction PCD and circular-pattern them, break every edge, surface-then-thicken for thin-wall parts, combine-then-shell for hollow ones, fix-first then fully-constrain for assemblies, apply GD&T to functional features.

3. Emit the VBA (the feature primitives below, or inline run_vba) and drive it through run_and_verify until success == true.

The recipes are an index of archetypes; the principles apply to every part. The same knowledge is mirrored as reactive rules in rules.json, so a related build error also surfaces the relevant professional practice as a suggested_fix.

Writing more feature generators

Generators emit VBA in the verified solidworks-vba style and run through run_and_verify. Two non-negotiable rules for inline .swb code (learned the hard way — see src/sw_mcp/vba/helpers.vba):

1. Never test an API boolean with bitwise If Not x. In an on-the-fly .swb, API VARIANT_BOOL returns arrive as +1, and VBA's Not is bitwise (Not 1 = -2, truthy). Always write If x = False Then. Object checks (Is Nothing) are fine.

2. Create*Rectangle returns a Variant array, not an object. Capture with Dim v As Variant: v = ... and check IsArray(v) — never Set seg = … (raises run-time error 424).

Add a build_<feature>() to feature_tools.py (reuse assemble_part_macro) and a thin @mcp.tool() wrapper in server.py.

Diagnostic scripts

scripts/ contains the standalone spikes used to validate each layer (spike_connect, spike_runmacro, spike_build, spike_autofix, …). They are handy for debugging the COM link without going through the MCP transport.