SolidworksMCP-python

SolidWorks CAD Assistant & MCP Server

Languages: English | Español

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

Overview

⚠️ Project Status: This project is under active construction. Features, APIs, documentation, and setup steps may change as the Python and UI implementation is finalized. This is a hobby/research product, please feel free to make an issue if you have questions or feedback! ⚠️

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.

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.