How to Connect a SolidWorks MCP Server to Claude Code from WSL Ubuntu

Why Would You Do This?

Imagine telling an AI “put a 10mm countersunk hole in the top face” and watching it happen in SolidWorks — no menu diving, no macro hacking, no YouTube tutorial rabbit holes at 1 AM. That’s what a SolidWorks MCP server gives you.

MCP (Model Context Protocol) is an open standard that lets AI tools like Claude Code talk to external software. A SolidWorks MCP server translates natural-language intent into real CAD operations on a running SolidWorks session.

Here’s the catch: SolidWorks only runs on Windows, but if you’re like most developers, you’re doing your real work in WSL Ubuntu. Claude Code lives in your terminal, your terminal lives in WSL, and SolidWorks lives on the Windows host. This guide is about connecting those two worlds.

The Architecture

Understanding the split is key to not losing your mind during setup:

┌─────────────────────────────────────────────────┐
│  Windows Host                                   │
│                                                 │
│  SolidWorks ← COM API ← MCP Server ← HTTP :8765│
│                                                 │
└──────────────────────┬──────────────────────────┘
                       │ network (via WSL gateway)
┌──────────────────────┴──────────────────────────┐
│  WSL Ubuntu                                     │
│                                                 │
│  Claude Code → connects to http://<host>:8765   │
│                                                 │
└─────────────────────────────────────────────────┘

The MCP server must run on Windows because it talks to SolidWorks through the COM API — a Windows-only technology. Claude Code runs in WSL Ubuntu and connects to that server over HTTP across the WSL network boundary. Two operating systems, one pipeline.

What You Need

On the Windows side:

• Windows 10/11 with WSL 2 and Ubuntu installed
• SolidWorks 2024+ installed, licensed, and launchable
• Python 3.10+ for Windows (from python.org or the Microsoft Store — not your WSL Python)
• Git for Windows (or use git from within WSL to clone, then access via /mnt/c/)

On the WSL Ubuntu side:

• Claude Code installed (npm install -g @anthropic-ai/claude-code)
• curl for testing the connection (already installed on most Ubuntu setups)

Important: You need Python installed on both sides. The Windows Python runs the MCP server (COM needs native Windows). The WSL Python is irrelevant for SolidWorks — don’t try to run the MCP server from inside WSL. It will not find SolidWorks.

Step 1: Pick Your MCP Server

Several open-source SolidWorks MCP servers exist. Here are the main ones:

Server	Language	Approach
SolidPilot (eyfel/mcp-server-solidworks)	Python + C#	Feature-level IR, compiles intent down to SolidWorks ops. Supports 2D drawing → 3D reconstruction.
Solidworks-MCP (alisamsam)	Python	Direct natural-language to SolidWorks control via COM.
SW_MCP (tylerstoltz)	C# (.NET)	Native C# SDK, targets SolidWorks 2020+.
SolidworksMCP-python (andrewbartels1)	Python	Python-based automation with COM bridge.

This guide uses the Python-based approach. The concepts apply to all of them — only the install commands and entry point change.

Step 2: Clone and Install the Server (on the Windows Side)

Open PowerShell or Windows Terminal (not your WSL terminal):

# Clone the server
git clone https://github.com/alisamsam/Solidworks-MCP.git
cd Solidworks-MCP

# Create a virtual environment using Windows Python
python -m venv .venv
.venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Most SolidWorks MCP servers depend on pywin32 to talk to the COM API. If the install fails:

pip install pywin32
python Scripts\pywin32_postinstall.py -install

WSL users — don’t clone here from inside WSL. You can access Windows files from WSL via /mnt/c/, but running the MCP server through that path adds filesystem overhead and often breaks COM. Clone natively on Windows.

Step 3: Expose the MCP Server Over HTTP

This is the step that makes the WSL bridge work. By default, most MCP servers use stdio (stdin/stdout) transport — great when the client and server are on the same OS, useless when they’re split across WSL and Windows.

You need to wrap the server with an HTTP transport so Claude Code in WSL can reach it over the network.

On Windows (PowerShell):

# Install the MCP proxy
pip install mcp-proxy

# Launch SolidWorks first, then start the server on port 8765
# Bind to 0.0.0.0 so WSL can reach it
mcp-proxy --host 0.0.0.0 --port 8765 -- python server.py

You should see output confirming the server is listening. Leave this terminal open — it needs to stay running.

Quick sanity check from WSL:

# Find your Windows host IP from inside WSL
WIN_HOST=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
echo "Windows host IP: $WIN_HOST"

# Test that the port is reachable
curl -s -o /dev/null -w "%{http_code}" http://$WIN_HOST:8765/mcp

If you get a response (even a 4xx — that’s fine, it means the port is open), the bridge is working. If you get connection refused, check:

1. Windows Firewall — you may need to allow inbound connections on port 8765. Open Windows Defender Firewall → Advanced Settings → Inbound Rules → New Rule → Port → TCP 8765 → Allow.
2. Is the MCP server still running in that PowerShell window?
3. Is SolidWorks open? The COM connection fails if SolidWorks isn’t running.

Step 4: Configure Claude Code in WSL

Now switch to your WSL Ubuntu terminal. First, grab the Windows host IP:

WIN_HOST=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')

Then register the MCP server with Claude Code:

claude mcp add --transport http solidworks http://$WIN_HOST:8765/mcp

This writes the server config into Claude Code’s settings. You can also add it manually by editing ~/.claude.json or your project’s .mcp.json:

{
  "mcpServers": {
    "solidworks": {
      "type": "http",
      "url": "http://172.x.x.1:8765/mcp"
    }
  }
}

Replace 172.x.x.1 with your actual Windows host IP.

Heads up: The WSL gateway IP can change between reboots. If your connection suddenly stops working after a restart, re-check the IP with cat /etc/resolv.conf. For a stable setup, consider setting a static IP for your WSL adapter or using the Windows hostname (e.g., http://$(hostname).local:8765/mcp — though mDNS in WSL can be flaky).

Step 5: Verify the Connection

In your WSL terminal:

claude mcp list

You should see:

solidworks: ✔ Connected (http)
  Tools: create_sketch, extrude_boss, create_hole, save_part, ...

If it shows ✘:

Symptom	Fix
Connection refused	Check firewall, verify MCP server is running on Windows
Timeout	Wrong IP — re-check cat /etc/resolv.conf
COM error in PowerShell	SolidWorks isn’t running, or 32/64-bit Python mismatch
url but no type error	Add "type": "http" to your .mcp.json entry

Step 6: Start Designing with Natural Language

Open Claude Code in WSL and go:

> Create a new SolidWorks part with a 50mm × 30mm × 10mm rectangular block,
  then add a 5mm through-hole centered on the top face.

Claude will use the MCP tools to create the sketch, extrude the block, add the hole, and cut through — all on the SolidWorks instance running on your Windows desktop. You’ll see it happen in real time on the Windows side.

Step 7: Add a SolidWorks Skill (You Really Should)

The MCP server gives Claude the tools — create a sketch, extrude, cut, fillet. But tools alone don’t make Claude good at CAD. SolidWorks has decades of conventions, constraints, and gotchas that a language model doesn’t inherently know. That’s where a skill comes in.

A skill is a markdown file (typically SKILL.md or a file under .claude/skills/) that gives Claude persistent, domain-specific instructions. Think of it as a cheat sheet that’s always loaded into context. Without one, Claude will make rookie SolidWorks mistakes: using the wrong units (the COM API works in meters, not millimeters), guessing parameter counts on 15-parameter API calls, extruding before constraining a sketch, or building features in an order that breaks the parametric tree.

The good news: you don’t have to write one from scratch. The community has already published skills specifically for SolidWorks.

Option A: Install a Community SolidWorks Skill

Several purpose-built SolidWorks skills exist on GitHub. Here are the ones worth knowing about:

solidworks-api-skill — A Claude Code skill focused on writing correct SolidWorks API automation code. It encodes the parameter signatures, COM gotchas, and constant enums (swConst) that Claude would otherwise guess wrong. Covers sketches, extrusions, revolves, cuts, patterns, mates, materials, and STEP export. Built from a real shield-machine cutterhead modeling project, so the pain points are battle-tested.

Key things this skill teaches Claude:

• SolidWorks API uses meters internally, not millimeters (1 mm = 0.001)
• Methods like FeatureExtrusion2 take 10–15 parameters with mixed types — the skill provides the exact signatures
• Late-binding COM calls fail with >12 parameters — the skill documents workarounds
• swConst enums like swDocPART, swEndCondBlind, swPlaneTop instead of magic numbers

Install it in your WSL terminal:

# Clone and copy the skill file
git clone https://github.com/guoleizhen717/solidworks-api-skill.git /tmp/sw-skill
mkdir -p ~/.claude/skills/solidworks-api
cp /tmp/sw-skill/SKILL.md ~/.claude/skills/solidworks-api/SKILL.md

text-to-cad — A broader library of CAD/CAM agent skills. While not SolidWorks-specific (it uses CadQuery/OpenCascade under the hood), it includes skills for STL export, DXF generation, DfAM (Design for Additive Manufacturing) printability checks, and even Bambu Labs printer integration. Useful as a complement to a SolidWorks-specific skill if your workflow goes all the way to the printer.

Install via the skills CLI:

npx skills add earthtojake/text-to-cad

Or for Claude Code specifically:

claude plugin marketplace add earthtojake/text-to-cad
claude plugin install cad@text-to-cad

cad-skill (flowful-ai) — A Claude Code skill for parametric 3D-printable model generation. Focuses on a describe → model → export STL → preview → iterate loop. It uses CadQuery rather than SolidWorks directly, but the design patterns (fully constrain before extruding, build large-to-small, validate before export) overlap heavily.

Install it:

git clone https://github.com/flowful-ai/cad-skill ~/.claude/skills/parametric-3d-printing

Option B: Write Your Own Custom Skill

Community skills cover API patterns and general CAD discipline, but they don’t know your workflow — your templates, naming conventions, default units, or print settings. A custom skill fills that gap.

Create .claude/skills/solidworks-custom.md in your project directory (inside WSL):

mkdir -p .claude/skills

Then write the rules that match how you work:

# SolidWorks — Project-Specific Rules

## Units and Templates
- Default to MMGS (millimeters, grams, seconds) for all new parts.
- Use the company part template at
  C:\ProgramData\SolidWorks\templates\custom-part.prtdot
- Save after every major feature, not just at the end.

## Sketch Discipline
- Every sketch must be fully constrained (black lines, not blue)
  before extruding or cutting.
- Use construction geometry (centerlines) for symmetry instead of
  manually mirroring dimensions.
- Place sketches on standard planes (Front, Top, Right) or existing
  flat faces.

## Feature Tree
- Build large to small: base extrude → cuts → fillets → chamfers.
- Name features descriptively ("Base Plate", "Mounting Hole Left"),
  never leave default names.

## File Paths and Naming
- Always use Windows paths for saves:
  C:\Users\me\Documents\SolidWorks\project\PROJ-001-part-v1.SLDPRT
- Never use WSL paths — SolidWorks can't access /home/.
- Convention: PROJ-XXX-description-vN.SLDPRT

## 3D Print Export
- STL tolerance: 0.02mm deviation, 5° angle.
- Minimum wall: 1.2mm (3 perimeters at 0.4mm nozzle).
- Minimum hole diameter: 2mm for clean FDM prints.
- Orient largest flat face on build plate.

## Error Handling
- On COM drops, tell the user to restart SolidWorks and the MCP
  server. Don't silently retry.
- On sketch over-constraint (red lines), remove the most recently
  added constraint.

Combining Skills: The Recommended Stack

The best setup layers multiple skills:

1. Community API skill (solidworks-api-skill) — teaches Claude the correct API signatures, parameter types, unit conversions, and COM workarounds. This prevents the low-level “wrong number of arguments” crashes.

2. Your custom skill — teaches Claude your project conventions, templates, naming, and print-specific rules. This prevents the “technically correct but useless for my workflow” problem.

3. (Optional) CAD/printing skill (text-to-cad or cad-skill) — adds printability checks, STL validation, and slicer-aware design rules. Useful if your output goes directly to a printer.

Claude loads all skills in its context, and they stack — the API skill tells it how to call FeatureExtrusion2, your custom skill tells it when and why, and the print skill tells it what to check before exporting.

How Skills and MCP Servers Actually Work Together

This is the part that confuses people: you don’t need to configure anything to make a skill “talk to” an MCP server. They’re two separate inputs to Claude that combine automatically at runtime.

Here’s what happens when you type “create a 50mm mounting bracket” in Claude Code:

1. Claude reads your prompt
       ↓
2. Claude's context already includes:
   ├── Skill: "SolidWorks API uses meters. 50mm = 0.05.
   │          Fully constrain sketches. Build large → small."
   └── MCP tools: create_sketch(), extrude_boss(), create_hole(), save_part()
       ↓
3. Claude plans the approach (informed by the skill):
   "Set units → sketch on Top plane → constrain → extrude 0.05m → save"
       ↓
4. Claude calls MCP tools in sequence:
   create_sketch(plane="Top") → add_rectangle(50mm) →
   add_constraints() → extrude_boss(depth=0.05) → save_part()
       ↓
5. Each tool call goes over HTTP to the Windows MCP server
       ↓
6. The MCP server executes the COM call in SolidWorks

The skill shapes how Claude thinks about the task. The MCP server gives Claude the hands to do it. They don’t communicate with each other — they both communicate with Claude.

To set this up, you just need two things in place:

1. The MCP server registered (from Step 4):

// .mcp.json
{
  "mcpServers": {
    "solidworks": {
      "type": "http",
      "url": "http://172.x.x.1:8765/mcp"
    }
  }
}

2. The skill file installed (from earlier in this step):

# Community skill
~/.claude/skills/solidworks-api/SKILL.md

# Your custom skill (optional, in project dir)
.claude/skills/solidworks-custom.md

That’s it. No linking, no glue code, no config that says “use this skill with that server.” Claude sees both and uses them together. The skill prevents Claude from making dumb calls; the MCP server executes the smart ones.

Why This Matters

Without any skill, here’s what happens when you ask Claude to “create a 50mm bracket with two M4 mounting holes”:

1. Claude calls FeatureExtrusion2 with the wrong number of parameters → COM error
2. Even if the call works, it passes 0.05 expecting millimeters, but the API uses meters → your bracket is 50 meters wide
3. It adds holes before the face they belong on exists in the feature tree → rebuild failure
4. It doesn’t save → one COM hiccup and everything is lost
5. It exports STL with default tolerance → the file is either 200MB or looks like a polygon from 1997

With the API skill, the calls are correct. With your custom skill, the workflow makes sense. With the print skill, the output is actually printable. Three layers, each solving a different class of problem.

WSL-Specific Gotchas

File paths cross the boundary. When you tell Claude to save a file, use Windows paths (C:\Users\you\Documents\parts\bracket.SLDPRT), not WSL paths. SolidWorks doesn’t know what /home/you/ means. If you want to access the saved file from WSL later, remember it lives at /mnt/c/Users/you/Documents/parts/bracket.SLDPRT.

The gateway IP changes. WSL 2 uses a virtual network adapter. The IP assigned to your Windows host (from WSL’s perspective) changes on reboot. Script it:

# Add to your .bashrc or .zshrc
export WINDOWS_HOST=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')

Don’t run the MCP server in WSL. It will install, it will start, it will find zero SolidWorks instances and fail with a cryptic COM error. The COM API is Windows-native. The server must run on the Windows side.

32-bit vs 64-bit Python on Windows. This trips up everyone. SolidWorks is 64-bit, so you need 64-bit Windows Python. Check from PowerShell:

python -c "import struct; print(struct.calcsize('P') * 8)"

It should print 64. If it prints 32, uninstall and reinstall the 64-bit version.

Keep SolidWorks in the foreground. Some COM operations silently fail when SolidWorks is minimized. Keep it visible — ideally on a second monitor so you can watch Claude work.

WSL clock drift. WSL’s clock can drift from Windows, which occasionally causes TLS or timestamp issues. If things get weird, sync it:

sudo hwclock -s

The Startup Checklist

Every time you sit down to use this setup:

1. Launch SolidWorks on Windows
2. Start the MCP server in PowerShell: mcp-proxy --host 0.0.0.0 --port 8765 -- python server.py
3. Open WSL Ubuntu and run claude in your project directory
4. Verify: claude mcp list shows solidworks: ✔ Connected
5. Design away

If you want to automate steps 1–2, you can create a Windows batch script or a PowerShell script that launches both and drop it in your Startup folder.

The Bigger Picture for 3D Printing

If you’re a 3D printing nerd like me, this setup is a game-changer. The workflow becomes:

1. Describe the part you need to Claude (from your WSL terminal)
2. Claude designs it in SolidWorks on the Windows side via MCP
3. Export as STL directly from SolidWorks
4. Access the STL from WSL at /mnt/c/..., slice, and print

No more fumbling with TinkerCAD for quick functional parts. No more manually modeling the same parametric bracket for the 50th time. Describe it, let Claude build it, tweak the parameters if needed, and send it to the printer.

This is especially powerful for parametric designs — tell Claude “make the bracket 5mm wider and add M4 mounting holes” and it modifies the existing part instead of starting over.

Wrapping Up

The WSL + Windows split adds one layer of complexity (the HTTP bridge), but once it’s wired up, you get the best of both worlds: your comfortable Linux dev environment in WSL and the full power of SolidWorks on the Windows host, with Claude Code orchestrating between them.

Setup takes about 20 minutes. The firewall rule is the part most people forget. After that, it just works — describe a part, watch it appear in SolidWorks, iterate with natural language, export, and print.

Now go print something you designed with words.