README.md

SolidWorks CAD Assistant & MCP Server

Python MCP server for SolidWorks automation with 109 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.
• Prefab UI preview sync from the active viewport as PNG.

Not Yet / Simulated

• Mock adapter output is simulated and should not be treated as engineering truth.
• Live 3D viewport streaming in the UI.
• Checkpoint-level interference validation in the UI runner.

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.11+ 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 .\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

Prefab UI Dashboard

Interactive CAD assistant with GitHub Copilot integration and real-time 3D viewport sync.

Quick Start (2 terminals required):

1. Terminal 1 - Backend API server:

.\.venv\Scripts\python.exe -m pip install -e ".[ui]"  # one time
.\.venv\Scripts\python.exe -m uvicorn solidworks_mcp.ui.server:app --host 127.0.0.1 --port 8766 --reload

The backend is a FastAPI app, so local API docs are available at http://127.0.0.1:8766/docs.

1. Terminal 2 - Prefab frontend:

.\.venv\Scripts\prefab.exe serve src/solidworks_mcp/ui/prefab_dashboard.py

1. Open http://127.0.0.1:5175 in your browser.

Layout:

• Left pane (wider): Design intent input + family classification gate
• Middle pane: Checkpoint queue + context window + evidence table + manual sync
• Right pane (larger): 3D model view with orientation buttons (Isometric/Front/Top/Current)

Key features:

• ✅ GitHub Copilot integration for goal clarification and family classification
• ✅ Checkpoint workflow with SQLite session persistence
• ✅ Execute Next Checkpoint runs supported adapter tools and logs per-tool results
• ✅ Real-time PNG preview sync from SolidWorks using export_image(view_orientation=...)
• ✅ Manual edit detection via snapshot comparison
• 🔧 MOCKED: check_interference from checkpoint runner (until tool-layer wiring exists)
• 🔧 MOCKED: live 3D viewport streaming and STL embedding in the UI (PNG sync is live)
• 📋 Future: richer model-state diffing (feature-level and mass-property deltas)

LLM Requirements:

• GH_TOKEN or GITHUB_API_KEY environment variable (models:read scope)
• OR: authenticated gh auth login session

Preview Pane:

• Exports from active SolidWorks viewport every 3 minutes or on manual refresh
• Supports: Isometric, Front, Top, Current orientations
• Requires: SolidWorks running + COM adapter available

Full Documentation:

See Prefab UI Dashboard Guide for button reference, architecture notes, and troubleshooting.

VS Code MCP Configuration (Windows)

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\\run-mcp.ps1"
      ]
    }
  }
}

Replace the script path with your local repository path.

LM Studio MCP Configuration (Windows)

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

{
  "mcpServers": {
    "solidworks-mcp-server": {
      "command": "powershell",
      "args": [
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "C:\\Users\\andre\\OneDrive\\Documents\\GitHub\\SolidworksMCP-python\\run-mcp.ps1"
      ]
    }
  }
}

Alternative direct-python entry:

{
  "mcpServers": {
    "solidworks-mcp-server": {
      "command": "C:\\Users\\andre\\OneDrive\\Documents\\GitHub\\SolidworksMCP-python\\.venv\\Scripts\\python.exe",
      "args": ["-m", "solidworks_mcp.server"]
    }
  }
}

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
• Prefab UI Dashboard
• VS Code MCP Setup
• Architecture
• Agents and Prompt Testing
• PydanticAI and Schemas

License

MIT License. See LICENSE.