SolidWorks CAD Assistant & MCP Server

Languages: English | Español

Python MCP server for SolidWorks automation with 151 tools, plus an optional agent/prompt-testing layer for AI-assisted workflows.

Overview

Tried it? Tell us what worked and what didn't in a feedback issue. Reports from real setups decide what gets fixed next.

This project focuses on practical SolidWorks automation with an AI-friendly loop:

1. describe intent
2. generate a plan
3. execute MCP tools
4. inspect results
5. iterate

It includes:

• core MCP runtime for SolidWorks tool execution
• COM/VBA routing and adapter safety wrappers
• tool coverage across modeling, sketching, drawing, analysis, export, automation, templates, and macros
• optional agent orchestration/testing utilities under src/solidworks_mcp/agents/

Supported Today

• Windows + SolidWorks COM automation for the main CAD lifecycle.
• Modeling, sketching, drawing, analysis, export, automation, templates, and macro tools.

Not Yet / Simulated

• Mock adapter output is simulated and should not be treated as engineering truth.
• Live 3D viewport streaming in a UI.
• Checkpoint-level interference validation.
• Simple simulation and fluid workflows
• Simple Topology Optimization via SimulationXpress etc.

What Works (Verified Windows Setup)

This is the setup path validated end-to-end:

1. Install Python from python.org (Windows installer).
2. Enable Add python.exe to PATH during install.
3. Install this project into a local .venv.
4. Launch MCP from .venv\Scripts\python.exe (not from WSL).

When this is correct, startup logs show:

• Platform: Windows
• SolidWorks COM interface is available
• Registered ... SolidWorks tools (count varies as tools evolve)
• Connected to SolidWorks

Requirements

• Windows 10/11 for real SolidWorks COM automation.
• Python 3.13+ from python.org.
• Git.
• SolidWorks installed and launched at least once.

Linux/WSL is useful for docs/tests/mock mode, but not for direct COM automation.

Quick Start (Windows, python.org)

git clone https://github.com/andrewbartels1/SolidworksMCP-python.git
cd SolidworksMCP-python

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip setuptools wheel
.\.venv\Scripts\python.exe -m pip install -e .

Start server manually:

.\.venv\Scripts\python.exe -m solidworks_mcp.server

Or use the helper script (open SolidWorks first):

powershell -NoProfile -ExecutionPolicy Bypass -File .\deployment\run-mcp.ps1 --real --year 2026

Mock mode warning — running run-mcp.ps1 without --real starts the
server in mock mode. All tool responses are simulated; nothing touches
SolidWorks. Always pass --real --year <year> for live automation.

Development Commands

Use the helper script for common workflows:

.\dev-commands.ps1

Common commands:

• dev-install - install/update local dev environment
• dev-test - run standard test suite (CI-safe subset)
• dev-test-full - run full test suite (includes smoke/integration paths)
• dev-lint - lint checks
• dev-format - format code
• dev-docs-build - build docs site once
• dev-docs-strict - strict docs build (fails on warnings)
• dev-docs-audit - generate docs audit report in .generated/docs

Local CI Replica (Docker)

To mirror GitHub Actions CI locally (Ubuntu + conda env from solidworks_mcp.yml + make test), run:

.\run-ci-local.ps1

The first run builds the image. Re-run without rebuild when only executing tests:

.\run-ci-local.ps1 -NoBuild

MCP Client Configuration (Windows)

There are two parallel sets of launch scripts, both in deployment/:

• deployment/run-mcp.ps1 / src/utils/start_local_server.py — the local
  dev/demo harness: decorative startup banners, an HTTP health-check step,
  and an example tool-call workflow. Good for running by hand in a terminal
  to see what the server does. Not recommended for MCP host configs — a
  stdio MCP host treats a spawned server's stdout as a pure JSON-RPC
  channel, and this script's banner output goes to stdout.
• deployment/run-mcp-claude.ps1 / src/utils/start_local_server_claude.py
  — a minimal entrypoint with no decorative output, meant specifically for
  MCP host configs (Claude Desktop, Claude Code, VS Code, LM Studio). Use
  these for any host config below.

If a tool call fails with an error like invalid_union / "expected
object, received string" — that's the client's JSON-RPC parser choking
on non-JSON text. It almost always means the config's args point at
start_local_server.py (or run-mcp.ps1) instead of the _claude
variant. This is easy to hit after editing a config by hand or letting a
client's own "fix it for me" assistant rewrite the command: it may resolve
the path to the plain script by filename guess. Check the exact filename
in your config against the list above.

MCP hosts spawn servers over raw stdio pipes with no console attached.
Windows PowerShell's native-command invocation is unreliable in that exact
scenario — run-mcp-claude.ps1's venv-detection step uses Start-Process
instead of piping to Out-Null to avoid it (piping a native command's
output makes it a pipeline stage, which throws Cannot run a document in the middle of a pipeline when there's no console attached to the host
process). If you still hit connection failures with it, point the client
directly at the venv's python.exe instead, which skips PowerShell
entirely.

Claude Desktop

Claude Desktop reads its MCP server list from a claude_desktop_config.json file. The path depends on how the app was installed:

• Classic/legacy installs: %APPDATA%\Claude\claude_desktop_config.json
• Packaged (MSIX-style) installs: %LOCALAPPDATA%\Packages\Claude_<hash>\LocalCache\Roaming\Claude\claude_desktop_config.json — look under %LOCALAPPDATA%\Packages\ for a folder starting with Claude_ if the classic path doesn't exist.

Create the file if it doesn't exist yet, and use the server key solidworks (the troubleshooting runbook in CLAUDE.md and the app's own log filenames assume this name). If the file already has other top-level keys (preferences, etc.), just add mcpServers alongside them — don't replace the file:

{
  "mcpServers": {
    "solidworks": {
      "command": "C:\\path\\to\\SolidworksMCP-python\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\SolidworksMCP-python\\src\\utils\\start_local_server_claude.py",
        "--real",
        "--year",
        "2026"
      ]
    }
  }
}

Replace the paths with your local repository path. The --real --year 2026 flags start the server in live COM automation mode (requires SolidWorks already open). Omit them for mock mode.

After saving, fully quit Claude Desktop (not just close the window — use File > Exit or the tray icon) and relaunch it so it reloads the MCP server list. To confirm it picked up the server:

• In the app, open Settings > Developer and check that solidworks is listed and connected.
• Or check %LOCALAPPDATA%\Claude\Logs\mcp-server-solidworks.log for a full initialize / tools/list round trip.
• Tool-call errors are logged separately; see Troubleshooting Runbook in CLAUDE.md if the server appears but tool calls fail.

VS Code

Set your user MCP config (%APPDATA%\Code\User\mcp.json) to:

{
  "servers": {
    "solidworks-mcp-server": {
      "type": "stdio",
      "command": "powershell",
      "args": [
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "C:\\path\\to\\SolidworksMCP-python\\deployment\\run-mcp.ps1",
        "--real",
        "--year",
        "2026"
      ]
  },
  "inputs": []
}

Replace the script path with your local repository path. The --real --year 2026 flags start the server in live COM automation mode (requires SolidWorks open). Omit them for mock mode.

If this doesn't connect (see the note above about stdio hosts and stdout), switch to the MCP-host-safe wrapper below.

Recommended for MCP use: run-mcp-claude.ps1

{
  "servers": {
    "solidworks-mcp-server": {
      "type": "stdio",
      "command": "powershell",
      "args": [
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "C:\\path\\to\\SolidworksMCP-python\\deployment\\run-mcp-claude.ps1",
        "--real",
        "--year",
        "2026"
      ]
  },
  "inputs": []
}

LM Studio

Set your LM Studio MCP config file to include this server (LM Studio expects mcpServers):

{
  "mcpServers": {
    "solidworks-mcp-server": {
      "command": "C:\\path\\to\\SolidworksMCP-python\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\SolidworksMCP-python\\src\\utils\\start_local_server_claude.py",
        "--real",
        "--year",
        "2026"
      ]
    }
  }
}

After saving, restart LM Studio so it reloads MCP servers.

Optional Features (environment toggles)

All off/default unless set. Pass these as environment variables when launching
the server (or in your MCP host config's env block); every
SOLIDWORKS_MCP_<FIELD> maps to a config field of the same name.

SolidWorks-as-Code session logging — off by default

Logs every adapter tool call to a local SQLite database so a session can be
replayed or exported as a runnable Python script (see
docs/getting-started/solidworks-as-code.md).

$env:SOLIDWORKS_MCP_SOC_LOGGING_ENABLED = "true"
$env:SOLIDWORKS_MCP_SOC_SESSION_ID = "my-bracket"
.\.venv\Scripts\python.exe -m solidworks_mcp.server
# ...work in your MCP client...
.\.venv\Scripts\python.exe -m solidworks_mcp.agents.soc_exporter my-bracket my_bracket.py

Effective only with the circuit-breaker adapter wrapper (the default for real
SolidWorks); the mock adapter does not log.

API docs index auto-refresh — on by default

The granular API-lookup tools (lookup_api_interface, lookup_api_method,
find_related_api_members) and search_solidworks_api_help read a JSON index
built by discover_solidworks_docs. When that index is older than the
threshold it is rebuilt automatically on the next lookup.

Common Windows Fixes

If python is not found:

python --version

If this opens Microsoft Store or fails, reinstall Python from python.org and enable PATH.

If startup fails with ModuleNotFoundError: solidworks_mcp:

.\.venv\Scripts\python.exe -m pip install -e .

If startup fails with ModuleNotFoundError: fastmcp:

.\.venv\Scripts\python.exe -m pip install -e .

Docs

• Main docs site: https://andrewbartels1.github.io/SolidworksMCP-python/
• Home/overview: docs/index.md

Key docs sections:

• Getting Started: docs/getting-started
• MCP Server Guide: docs/user-guide
• Tool Catalog: docs/user-guide/tool-catalog
• Agents and Skills: docs/agents
• Planning/Roadmap: docs/planning

Direct links:

• Installation
• Quick Start
• Tutorial: U-Joint Assembly Build
• Tutorial Tracks
• VS Code MCP Setup
• Architecture
• Agents and Prompt Testing
• PydanticAI and Schemas

License

MIT License. See LICENSE.