# SolidWorks MCP Server

[中文说明](README.zh-CN.md)

A self-contained [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes SolidWorks 2023+ to Kimi, Claude, Codex, and other MCP clients on Windows. It drives SolidWorks through the COM API, marshalling all calls onto a single STA thread so the application stays alive and responsive.

This package includes the original MCP server, the local `solidworks_automation` COM helper modules, and setup scripts to register the server with Kimi and Claude clients.

## Prerequisites

- Windows 10/11 (SolidWorks COM automation requires a Windows desktop session).
- SolidWorks 2023 or later (license and installation required).
- Python 3.8+.
- `mcp` package (`>=1.0.0`).
- `pywin32` package (`>=305`) for COM interop.

## Quick Install

1. Open PowerShell in the package directory.
2. Run the install script:

   ```powershell
   .\setup.ps1
   ```

The script will install Python dependencies and register the server in:

- `C:\Users\<you>\.kimi\mcp.json`
- `C:\Users\<you>\.claude\settings.json`

Existing settings in those files are preserved (merged, not overwritten).

## Manual Install / MCP Config Snippet

If you prefer to register the server manually, add this block under the `mcpServers` key of your client config:

```json
{
  "mcpServers": {
    "solidworks": {
      "command": "python",
      "args": [
        "<repo>\\solidworks-mcp\\server.py"
      ],
      "cwd": "<repo>\\solidworks-mcp",
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "SW_HIDE_WINDOW": "1"
      }
    }
  }
}
```

Then install dependencies from the package root:

```powershell
pip install -r requirements.txt
# or install in editable mode
pip install -e .
```

## Tool Overview

| Category | Tools | What they do |
|---|---|---|
| **Connection / Docs** | `sw_connect`, `sw_get_status`, `sw_new_part`, `sw_new_assembly`, `sw_new_drawing`, `sw_open_document`, `sw_close_document`, `sw_save_document`, `sw_list_open_documents` | Connect to SolidWorks, create/open/close documents, save. |
| **Sketch** | `sw_start_sketch`, `sw_exit_sketch`, `sw_sketch_line`, `sw_sketch_circle`, `sw_sketch_rectangle`, `sw_sketch_corner_rectangle`, `sw_sketch_arc`, `sw_sketch_polygon`, `sw_sketch_spline`, `sw_sketch_slot`, `sw_add_dimension` | Start/exit sketches and draw 2D geometry on a selected plane. |
| **Features** | `sw_extrude`, `sw_cut_extrude`, `sw_extrude_midplane`, `sw_revolve`, `sw_fillet`, `sw_chamfer`, `sw_shell`, `sw_linear_pattern`, `sw_circular_pattern`, `sw_mirror`, `sw_rib`, `sw_list_features` | Build 3D features from sketches and list the feature tree. |
| **Assembly** | `sw_add_component`, `sw_add_mate`, `sw_list_components`, `sw_exploded_view` | Add components, apply mates, and create exploded views. |
| **Drawing** | `sw_create_standard_views`, `sw_add_view`, `sw_insert_dimensions`, `sw_add_note`, `sw_insert_bom`, `sw_export_pdf` | Generate drawing views, annotations, BOMs, and PDF export. |
| **Export** | `sw_export_file` | Export to STEP, STL, IGES, DXF/DWG, Parasolid, PDF, and native formats. |
| **Analysis / Properties** | `sw_get_mass_properties`, `sw_check_interference`, `sw_get_model_info`, `sw_set_material`, `sw_get_sketches`, `sw_run_analysis` | Mass properties, interference checks, model metadata, and material assignment. |
| **Custom Properties / Configurations** | `sw_get_custom_properties`, `sw_set_custom_property`, `sw_get_configurations`, `sw_activate_configuration`, `sw_get_active_configuration` | Read/write custom file properties and switch between model configurations. |

## Example Usage Prompts

- *“Connect to SolidWorks and create a new 100 mm × 60 mm × 20 mm box.”*
- *“Draw a 30 mm radius circle on the Front Plane and extrude it to 10 mm.”*
- *“Add the part `C:\\Models\\bracket.sldprt` to the active assembly at the origin.”*
- *“Create a coincident mate between the `top` face of `bracket-1` and the `bottom` face of `plate-1`.”*
- *“Export the current drawing to `C:\\Output\\drawing.pdf`.”*
- *“Set the custom property `PartNumber` to `A-1001` and activate the `Default` configuration.”*

## Boundaries and Limitations

- **Not truly headless.** The server still requires a Windows desktop session with SolidWorks installed. `SW_HIDE_WINDOW=1` only hides a *newly launched* SolidWorks instance; it does not remove the need for SolidWorks or for a Windows session.
- **Single-threaded COM.** All SolidWorks COM calls are serialized on one STA thread. Very long-running operations can block subsequent tool calls until they complete.
- **No Simulation/FEA.** The server does not drive SolidWorks Simulation (COSMOS) or run finite-element analysis. It is limited to geometry, assemblies, drawings, and basic mass/interference checks.
- **Entity selection is name-based.** Tools that select faces, edges, or planes rely on the English feature names (`FACE`, `EDGE`, `PLANE`) and named features in the SolidWorks feature tree. On non-English SolidWorks installations or models with renamed/special characters, selection may be brittle or fail.
- **Attaches to existing windows.** If a SolidWorks window is already running when the server connects, it may attach to that instance instead of creating a new hidden one. That can produce surprising results if the active document is not what you expect.
- **Model/drawing must be saved for some exports.** Some export routines behave best when the source document has already been saved to disk.
- **Error handling.** COM errors are caught and returned as JSON error messages, but they do not always map to an obvious root cause. When SolidWorks shows a modal dialog, the call may hang until the dialog is dismissed.