Installation Guide¶

This guide documents the Windows setup path that was validated to work with real SolidWorks COM automation.

Core Rule¶

Real SolidWorks automation requires Windows.

Windows: real COM automation.
Linux/WSL: mock-mode testing and docs workflows.

1. Install Python from python.org¶

Download Python 3.11+ from https://www.python.org/downloads/windows/.
Run installer.
Enable Add python.exe to PATH.
Finish install and open a new PowerShell window.

Verify:

python --version
python -c "import sys; print(sys.executable)"

If python is not found or opens Microsoft Store, reinstall Python from python.org and confirm PATH option was enabled.

2. Clone Repository¶

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

3. Create venv and Install Package¶

Option A: Core MCP server only¶

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip setuptools wheel
.\.venv\Scripts\python.exe -m pip install -e ".[dev,test,docs]"

Option B: Core + Prefab UI dashboard (recommended)¶

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip setuptools wheel
.\.venv\Scripts\python.exe -m pip install -e ".[dev,test,docs,ui]"

The ui extra installs prefab-ui and fastapi which are needed for dev-ui-probe and dev-ui.

venv created from conda/micromamba Python

If you use micromamba (recommended for dev workflows), create the venv from the micromamba Python to ensure compatible binaries. After creating the venv, bootstrap pip if it is missing:

# Create venv from the micromamba solidworks_mcp env Python
C:\Users\<you>\micromamba\envs\solidworks_mcp\python.exe -m venv .venv
.\.venv\Scripts\python.exe -m ensurepip --upgrade
.\.venv\Scripts\python.exe -m pip install --upgrade pip setuptools wheel
.\.venv\Scripts\python.exe -m pip install -e ".[dev,test,docs,ui]"

Or use the all-in-one dev command after setup:

.\dev-commands.ps1 dev-install-ui

This installs both solidworks_mcp and runtime dependencies such as fastmcp in the same interpreter used by the MCP server.

4. Configure VS Code MCP¶

Open %APPDATA%\Code\User\mcp.json and configure:

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

Set the script path to your local repository location.

5. Start and Verify¶

Start server:

powershell -NoProfile -ExecutionPolicy Bypass -File .\run-mcp.ps1

Healthy startup logs include:

Platform: Windows
SolidWorks COM interface is available
Registered 109 SolidWorks tools
Connected to SolidWorks

Troubleshooting¶

`ModuleNotFoundError: solidworks_mcp`¶

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

`ModuleNotFoundError: fastmcp`¶

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

SolidWorks connection problems¶

Launch SolidWorks before starting MCP.
Confirm you are running on Windows, not WSL for COM usage.
Verify COM import:

.\.venv\Scripts\python.exe -c "import win32com.client; print('win32com OK')"

PowerShell execution policy blocks `dev-commands.ps1`¶

Fix: set execution policy for your user

Error: cannot be loaded because running scripts is disabled on this system

This is a Windows security default. Allow locally created scripts for your user only — no admin required:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

Then retry .\dev-commands.ps1 dev-help.

RemoteSigned lets local scripts run freely but still enforces signing for scripts downloaded from the internet. CurrentUser scope only affects your profile. Never set Bypass persistently — it disables all script security checks.

For a one-time run without changing any policy (e.g. in CI):

powershell -NoProfile -ExecutionPolicy Bypass -File .\dev-commands.ps1 dev-help

`micromamba` is not recognized when running `dev-install`¶

Install micromamba on Windows PowerShell

Error: micromamba : The term 'micromamba' is not recognized as the name of a cmdlet, function, script file, or operable program

dev-install uses micromamba to create the conda environment from solidworks_mcp.yml. Install it first:

Invoke-Expression ((Invoke-WebRequest -Uri https://micro.mamba.pm/install.ps1 -UseBasicParsing).Content)

The installer will prompt for an install location (default is %LOCALAPPDATA%\micromamba) and ask whether to initialize the shell. Answer yes — this adds micromamba to your PowerShell profile so it is available in future sessions.

If micromamba is still not recognized after reopening PowerShell, initialize it manually:

micromamba shell init -s powershell;
micromamba activate base;

Then close and reopen PowerShell. Verify it works:

micromamba --version

Then retry:

.\dev-commands.ps1 dev-install

If you prefer not to use micromamba, use the virtualenv path instead (no conda required):

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip setuptools wheel
.\.venv\Scripts\python.exe -m pip install -e ".[dev,test,docs,ui]"

`prefab.exe` not found when running `dev-ui-probe` or `dev-ui`¶

Install UI extras to get prefab-ui into .venv

Error: Prefab executable not found: .venv\Scripts\prefab.exe

This means the .venv was created without the ui optional dependency group, or pip skipped writing the console-script wrapper on initial install.

Option 1 — Let run-ui.ps1 fix it automatically:

run-ui.ps1 detects when prefab.exe is missing and auto-reinstalls prefab-ui before starting. Just run:

.\dev-commands.ps1 dev-ui-probe

Option 2 — Use the UI install helper:

.\dev-commands.ps1 dev-install-ui

Option 3 — Manual fix:

.\.venv\Scripts\python.exe -m pip install --force-reinstall "prefab-ui>=0.19.0" "fastapi>=0.115.0" "uvicorn>=0.24.0"

If .venv\Scripts\python.exe fails with "No pyvenv.cfg file", the venv is corrupted. Delete and recreate it:

Remove-Item -Recurse -Force .venv
python -m venv .venv
.\.venv\Scripts\python.exe -m ensurepip --upgrade   # if pip missing (conda Python)
.\.venv\Scripts\python.exe -m pip install -e ".[dev,test,docs,ui]"

GitHub CLI (`gh`) not installed or not authenticated¶

Install GitHub CLI and log in

dev-test-full uses gh auth token to resolve a GitHub token for smoke tests that call the GitHub API. If gh is missing or you are not logged in, those tests will be skipped or fail.

Step 1 — Install GitHub CLI on Windows:

Download and run the MSI installer from https://cli.github.com/ (recommended for beginners), or install silently via winget:

winget install --id GitHub.cli

Step 2 — Reload your PATH without closing PowerShell:

After installation the gh command won't be found in the current window until the PATH is refreshed. Run:

$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")

Or simply close and reopen PowerShell. Verify it works:

gh --version

Step 3 — Authenticate:

gh auth login

At the prompts:

Select GitHub.com
Select HTTPS
Select Login with a web browser — a code will be shown; paste it in the browser window that opens and approve

Verify authentication succeeded:

gh auth status

Once authenticated, dev-test-full will automatically pick up the token via gh auth token.