Real SolidWorks automation needs Windows 10 or 11 with SolidWorks installed and opened at least once. Linux and WSL work for the docs, the tests and mock mode.
uv runs the server from PyPI and fetches Python 3.13 for it, so you don't need Python installed. In PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Then open a new PowerShell window, so uvx is on the PATH. (winget install --id=astral-sh.uv -e works too.)
uvx solidworks-mcp-python setupThe package is solidworks-mcp-python. uvx solidworks-mcp installs a different project.
Setup walks through:
- SolidWorks. It reads the installed versions from the registry and starts the server with the newest one (
--year 2026);--yearpicks another. With none found, it offers mock mode. - Clients. It lists Claude Desktop, Claude Code, VS Code, Cursor and LM Studio, with what it found for each, and you pick by number.
- A start-up check. It starts the server once in mock mode and confirms that it lists its tools. SolidWorks isn't touched, and nothing is written if this fails.
- The entry. It adds a
solidworksentry that runsuvx solidworks-mcp-python --year <year>, withuvxby its full path, so it works whatever PATH the client starts it with. Run from a clone's.venv, it runs that.venv'ssolidworks-mcp.exeinstead. Claude Code is configured withclaude mcp add --scope user. - Older entries. If a client has other entries that start this server the old way (
run-mcp.ps1,start_local_server_claude.pyand the like), it names them and offers to remove them, so tools don't load twice. - Next steps. It says what to restart in each client and how to confirm the connection.
| Option | What it does |
|---|---|
--client <name> |
Configure claude-desktop, claude-code, vscode, cursor or lmstudio without the list. Repeat it for several. |
--dry-run |
Show what would change, and change nothing. |
--yes |
Don't ask: configure every client found. Older entries are kept unless --replace-old is also given. |
--remove |
Take the solidworks entry out again. |
--replace-old |
Remove older entries for this server without asking. |
--mock |
Configure mock mode, which answers without SolidWorks. |
--year <year> |
The SolidWorks release to start the server with, e.g. 2026. Default: the newest installed. Setup stops, changing nothing, if that year isn't installed. |
--skip-check |
Don't run the start-up check. |
Client config files often hold other servers' API keys and tokens, so setup:
- changes only the
solidworksentry, or an older entry for this server that you agreed to remove; - never prints or logs any other entry. The client list shows only file paths, and the
solidworksentry's own command when it runs a different copy of the project; - recognises older entries from their
commandandargsalone, and never readsenvorheaders; - backs the file up first, beside it, as
<name>.bak-YYYYMMDD-HHMMSS; - writes it in one step, as UTF-8 without a byte-order mark, and reads it back to check it is valid and holds the new entry;
- leaves a file that isn't valid JSON untouched, and reports only its line and column. VS Code's
mcp.jsonmay hold comments, which plain JSON doesn't allow, so remove them or add the entry by hand.
Nothing in the install or setup signs in to anything. The only download is the Python packages, from PyPI.
Open SolidWorks, restart your client as setup told you, and ask "What model is open in SolidWorks?". The server's log (VS Code shows it under the server's output; Claude Desktop writes %LOCALAPPDATA%\Claude\Logs\mcp-server-solidworks.log) includes:
SolidWorks COM interface is availableRegistered 135 SolidWorks tools(the count grows as tools are added)Listing 135 tools: toolsets all, list mode(fewer with the settings below)Connected to SolidWorks
VS Code labels every line the server writes to stderr as [warning]. That is where its normal log goes, since stdout carries the MCP messages, so those labels aren't problems.
To check the whole setup without a client, run the selftest with SolidWorks open and idle:
uvx solidworks-mcp-python selftestIt builds a small part, an assembly, a drawing view and a STEP export through the same tools a client calls, checks each against a hand calculation, and prints PASS or FAIL per area. It opens and closes a few documents of its own and leaves yours alone. On a release other than 2026, please send the result with the compatibility report form; see Compatibility.
Every tool's name, description and inputs are sent to the model on every turn, so a long list costs tokens all session, and some clients cap how many tools a server may list. Two settings shorten it. Neither changes what the tools do, and with neither set the server lists every tool, as before.
SOLIDWORKS_MCP_TOOLSETS lists only some groups of tools, comma-separated:
| Toolset | Tools |
|---|---|
core |
Parts and assemblies: modelling, sketching, files, measuring and checking, materials and properties, export, the circuit-breaker reset |
drawing |
Drawings: views, dimensions, the title block and sheet, the drawing package and check |
automation |
Macros, recording and batch automation |
vba |
The VBA code generators |
docs |
Lookups in the SolidWorks API help |
all |
Everything (the default) |
SOLIDWORKS_MCP_TOOL_MODE=search lists four tools in place of the rest: get_model_info, reset_circuit_breaker, search_tools (finds tools from a plain-language description, with their inputs) and call_tool (runs one). The model searches before each new kind of step; the server's instructions tell it how. The search covers only the chosen toolsets and leaves deprecated tools out, so it returns their replacements. list is the default.
What each choice sends on every turn, measured on this release (tokens are bytes divided by 4, an estimate):
--8<-- "docs/assets/progress/tool-list-size.md"
Set them in the env of the client's solidworks entry. For Claude Desktop or Cursor:
"solidworks": {
"command": "...",
"args": ["..."],
"env": {
"SOLIDWORKS_MCP_TOOLSETS": "core,drawing",
"SOLIDWORKS_MCP_TOOL_MODE": "search"
}
}For Claude Code: claude mcp add solidworks --scope user -e SOLIDWORKS_MCP_TOOL_MODE=search -- <command>. A name that isn't a toolset, or a mode other than list or search, stops the server at start with a message listing the valid values, rather than quietly hiding tools. selftest reports how many tools your settings list.
execute_macro runs macro files. SOLIDWORKS_MCP_ALLOW_VBA_SOURCE decides whether it also runs VBA text, such as what the generate_vba_* tools write, so a model can write a macro and run it in one step. VBA runs inside SolidWorks with your Windows account's rights, so this is off unless you choose otherwise.
| Value | What vba_source does |
|---|---|
off (the default; also when unset) |
Refused as vba_source_off. Nothing is written or run. |
restricted |
Runs only if the source passes the SolidWorks-only check below; otherwise refused as vba_source_refused, listing every refused name and its line. Nothing is written or run when refused. |
full |
Runs whatever the source says, unchecked. Choose it only for macros you have read and trust. |
Any other value, including 1, true or yes, stops the server at start with these three listed, so nobody gets full by guessing.
When it runs, the text is saved as <temp>\solidworks_mcp\macros\vba-<random>.swb (the files are kept, so you can see what ran), and the reply gives that source_file and repeats the vba_source. The dialog watchdog applies as for any macro.
Comments and text in quotes are ignored. Every other name in the source must be one of:
- a VBA keyword, or a safe VBA function: maths, text, conversions, dates,
MsgBox,InputBox,Err,Debug.Print,vb…constants; - a name the macro declares itself (
Dim,Const,Sub/Functionand their parameters, loop variables, labels,Type/Enum); - a SolidWorks enum or enum value (
swDocPART), or type name (ModelDoc2); Application.SldWorks, the way to reach SolidWorks;- after a
., a member of the SolidWorks type library installed on this machine.
An undeclared variable is refused too; declare it with Dim.
- VBA that reaches outside SolidWorks:
AppActivate,Application,CallByName,ChDir,ChDrive,Close,CreateObject,CurDir,CurDir$,Declare,DeleteSetting,Dir,Dir$,Environ,Environ$,FileCopy,FileDateTime,FileLen,FileSystem,FreeFile,Get,GetAllSettings,GetAttr,GetObject,GetSetting,Input,Interaction,Kill,Line,Load,Lock,MkDir,Name,Open,Print,Put,Reset,RmDir,SaveSetting,Seek,SendKeys,SetAttr,Shell,Unload,Unlock,VBA,Width,Write. - SolidWorks members that touch files, run code, close or quit, or change what lasts beyond the open documents:
AddCallback,AddIns,AddSearchFolder,CallBack,ClickDialogControl,CloseAllDocuments,CloseDoc,CopyDocument,DownloadFromMySolidWorksSettings,ExitApp,GetAddInObject,GetCommandManager,ImportSwSettings,InsertObject,InsertObjectFromFile,JournalManager,LoadAddIn,LoadAdminSettingsFile,LoadModel,LoadPointsFromFile,OpenCompFile,PrintDirect,PrintFile,PrintToFile,Quit,QuitDoc,RemoveAllCommandItems,RemoveCallback,RemoveSearchFolder,RenameDocument,ReplaceCommandItem,RunAttachedMacro,RunBatchSaveProcess,RunCommand,RunJournalCmd,RunMacro,RunMacro2,RunXMLCommand,SendDataForNetworkJob,SetAddinCallbackInfo,SetAddinCallbackInfo2,SetCurrentWorkingDirectory,SetDialogButtonState,SetDialogControlText,SetSearchFolders,UnloadAddIn,UploadToMySolidWorksSettings,WriteJournalToMacro,WriteToJournalFile, and every member whose name starts withsave…,export…,opendoc…,loadfile…,closeandreopen…,setuserpreference…,printout…,iprintout…,addcommand…,removecommand…,addtoolbarcommand…,createcommandgroup….
So a restricted macro works on the documents already open. Opening, saving and exporting are done with the tools (open_model, save_file, export_*), which you can see in the conversation.
It reads the source before it runs; it is not a sandbox, and Windows can't take rights away from one macro inside SolidWorks. Allowed SolidWorks calls can still change or delete geometry in the open documents (undo works as usual), show dialogs, and use a lot of time. The check has no exceptions you can add per macro: if restricted refuses something you need, either do that step with a tool or use full for that macro.
Set it in the env of the client's solidworks entry, as in section 4: "SOLIDWORKS_MCP_ALLOW_VBA_SOURCE": "restricted".
To work on the server itself, install it from a clone. You need Python 3.13+, installed with Add python.exe to PATH ticked, and Git.
git clone https://github.com/andrewbartels1/SolidworksMCP-python.git
cd SolidworksMCP-python
.\install.ps1install.ps1:
- finds Python 3.13+ (the
pylauncher first, thenpythonon the PATH); - creates
.venvin the project folder, if it doesn't exist; - installs the project into it, with
uvif it's on the PATH, otherwisepip; - runs
solidworks-mcp setup, which points your clients at this.venv.
Any options after .\install.ps1 are passed on to setup, for example .\install.ps1 --dry-run. To run setup again later: .\.venv\Scripts\solidworks-mcp.exe setup.
The install is editable: code changes in the folder take effect the next time a client starts the server. For the development tools as well, run .\.venv\Scripts\python.exe -m pip install -e ".[dev,test,docs]", or .\dev-commands.ps1 dev-install for the micromamba-based dev environment.
Open a new PowerShell window after installing uv; the installer adds %USERPROFILE%\.local\bin to the PATH for new windows only. A client set up by hand that can't start uvx needs its full path as command, from (Get-Command uvx).Source. Setup always writes the full path.
A client started with uvx solidworks-mcp-python keeps the version uv downloaded first. To move to the latest release, quit your clients, run uv cache clean solidworks-mcp-python, and start them again: the next start downloads the newest version.
Windows locks a running program, so an install can't replace solidworks-mcp.exe while Claude Desktop, VS Code or another client is running it. install.ps1 checks first: if the server is installed and running, it skips the install and goes on to setup. To update dependencies after a git pull, quit your clients (Claude Desktop from the system tray) and run it again.
If an install was interrupted anyway and the server now fails with an ImportError, quit your clients and reinstall: uv pip install --python .venv\Scripts\python.exe -e . (or the pip equivalent). uv pip check --python .venv\Scripts\python.exe reports any package left half-installed.
- Claude Desktop must be quit from the system tray, not just closed. It keeps its config in one of three places:
%LOCALAPPDATA%\Claude-Data\claude_<id>\(current releases),%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\, or%APPDATA%\Claude\. Setup picks the one in use. It also saves its preferences to that file, so a copy still running in the tray may write over the entry; if the entry is gone after a restart, quit Claude Desktop fully and run setup again. - VS Code: run MCP: List Servers and start
solidworks. - Run
uvx solidworks-mcp-python setup --dry-runto see each client's status, including whether itssolidworksentry runs a different copy of the project, such as a test copy you have since deleted.
The server is in mock mode: its entry's args include --mock. Run setup again without --mock.
SolidWorks wasn't running when the client started the server. Open SolidWorks, then restart the server from the client (for example MCP: List Servers > solidworks > Restart in VS Code). Despite the next log line, "Continuing with mock adapter for testing", the server does not switch to mock mode; its tools fail until it is restarted with SolidWorks open.
- Open SolidWorks before the client starts the server.
- Run on Windows, not WSL.
- Check COM:
.\.venv\Scripts\python.exe -c "import win32com.client; print('win32com OK')". - The troubleshooting runbook covers COM errors in detail.
The client read something on the server's stdout that wasn't an MCP message. It happens with the older launchers:
deployment/run-mcp.ps1andsrc/utils/start_local_server.pyare a hands-on demo harness. They print banners to stdout, so they can't be used from a client config.deployment/run-mcp-claude.ps1andsrc/utils/start_local_server_claude.pyare quiet, but go through PowerShell. A client starts servers with no console attached, which Windows PowerShell handles unreliably.
Run setup to replace the entry with solidworks-mcp.exe, which needs neither. It offers to remove the old entry too.
The .venv the client starts isn't installed. Run .\install.ps1 again, or install by hand: .\.venv\Scripts\python.exe -m pip install -e ..
!!! note "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:
```powershell
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
powershell -NoProfile -ExecutionPolicy Bypass -File .\dev-commands.ps1 dev-help
```
!!! note "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:
```powershell
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:
```powershell
micromamba shell init -s powershell;
micromamba activate base;
```
Then close and reopen PowerShell. Verify it works:
```powershell
micromamba --version
```
Then retry:
```powershell
.\dev-commands.ps1 dev-install
```
If you prefer not to use micromamba, use the virtualenv path instead (no conda required):
```powershell
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]"
```
!!! note "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:
```powershell
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:
```powershell
$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")
```
Or simply close and reopen PowerShell. Verify it works:
```powershell
gh --version
```
**Step 3 — Authenticate:**
```powershell
gh auth login
```
At the prompts:
1. Select **GitHub.com**
2. Select **HTTPS**
3. Select **Login with a web browser** — a code will be shown; paste it in the browser window that opens and approve
Verify authentication succeeded:
```powershell
gh auth status
```
Once authenticated, `dev-test-full` will automatically pick up the token via `gh auth token`.