solidworks-mcp

An MCP server that drives a running SOLIDWORKS session over its COM API.

It does not launch SOLIDWORKS, register an add-in, execute arbitrary code, or
touch the network. It attaches to a session you already have open and calls the
documented API — so if a tool can't do something, neither could a macro.

192 tools: sketching with real relations and driving dimensions, the solid
features you actually reach for, reference geometry, assemblies and mates, and —
importantly — a feedback channel, including screenshots returned as images so
the model can see what it just built.

覆盖范围包含 SolidWorks 本体与官方自带、随附模块，排除嘉立创等第三方插件。
当前仍未全覆盖；功能域、完成判据和缺口记录见 COVERAGE.md。

A sibling server, autocad-mcp,
does the same for AutoCAD.

Requirements

• Windows, with SOLIDWORKS installed and already running
• Python 3.10+

Install

git clone https://github.com/limuzi013/solidworks-mcp.git
cd solidworks-mcp
py -3 -m venv .venv
.venv\Scripts\python.exe -m pip install .

That puts a solidworks-mcp command in the environment, which is what the MCP
host runs. uv works too, if you prefer it:

uv tool install --from git+https://github.com/limuzi013/solidworks-mcp solidworks-mcp

Claude Code / Claude Desktop

{
  "mcpServers": {
    "solidworks-mcp": {
      "command": "C:\\path\\to\\.venv\\Scripts\\solidworks-mcp.exe"
    }
  }
}

Codex CLI (~/.codex/config.toml)

[mcp_servers.solidworks-mcp]
command = 'C:\path\to\.venv\Scripts\solidworks-mcp.exe'

Use single-quoted TOML strings so backslashes survive. Restart the MCP host after
editing its configuration.

An MCP host can also be pointed straight at a checkout, with nothing installed
but the dependencies — server.py at the repository root exists for exactly
that:

[mcp_servers.solidworks-mcp]
command = 'C:\path\to\.venv\Scripts\python.exe'
args = ['C:\path\to\solidworks-mcp\server.py']

Configuration

The two ideas that make it usable

1. Units are explicit, always

Every length parameter ends in _mm and every angle in _deg. The COM API
underneath is metres and radians; conversion happens once, at the boundary. No
tool has ever silently taken metres.

2. Selection is declarative

SOLIDWORKS features read from an implicit global selection set, with per-feature
"marks" deciding which selection means what. Exposing that to an agent is
hopeless. Instead every tool that needs geometry takes the same selection
object, and the server sets the marks:

// list_edges first, then:
{ "selection": { "edges": [4, 6, 9] } }
{ "selection": { "face_edges": [2] } }        // every edge of face 2
{ "selection": { "planes": ["front"] } }
{ "selection": { "sketch_segments": [0, 1] } }
{ "selection": { "points": [{ "x_mm": 30, "y_mm": 0, "z_mm": 20, "type": "FACE" }] } }

Indices come from list_faces / list_edges / list_vertices /
list_sketch_segments and describe the current model state — re-list after
any geometry change. Under the hood, selection resolves to a point that provably
lies on the entity and picks by 3D coordinate, which survives the fact that
late-bound Python cannot QueryInterface a Face2 to IEntity.

Tools

Session and documents

Reference geometry

list_reference_planes, create_plane (offset / angle / midplane / three points /
parallel-through-point), create_axis.

create_reference_points / list_reference_points 支持圆心、直线中点、面中心、
距离/百分比分布、均匀分布、交点、投影及草图点，读回模型坐标。
create_coordinate_system / list_coordinate_systems 创建与查询坐标系，
原点单位为 mm，输入角度为度；数值坐标系创建需要 SolidWorks 2022+。
参考点投影当前支持模型面，基准面投影仍是覆盖缺口。

create_curve_through_points / get_curve_points / set_curve_points 创建、
读取和修改通过 XYZ 点的原生参考曲线，输入和输出坐标均为 mm。
composite_curve 将相连的草图、边或参考曲线生成组合曲线。

Sketching

create_sketch (on a plane or a model face), create_3d_sketch, edit_sketch, close_sketch,
list_sketches, list_sketch_segments, list_sketch_points, get_sketch_status.

create_3d_sketch 在零件或装配体中创建原生 3D 草图；draw_line 支持 z1_mm/z2_mm，
draw_point 和 draw_spline 支持 z_mm。3D 坐标以模型坐标为准，单位为 mm；
2D 草图拒绝非零 Z，避免原生接口忽略坐标。编辑与关闭根据原生 Is3D 选用对应接口，
编辑时核验持久引用；读取较早草图时不误报为最新草图名称。
list_sketch_points 包含内部点与用户点，返回选择索引、类型和草图/模型坐标。
draw_centerline 支持 XYZ 构造线，并核验端点与构造属性；draw_3point_arc 支持
三点 XYZ 圆弧，核验半径、弧长、端点和点到曲线距离，共线/重合输入在创建前拒绝。
重叠/共端点圆弧原生结果曾偏离输入，返回未确认状态。圆/椭圆可在 2D 平面草图创建后
用 convert_entities 转换成空间曲线；转换逐点比较源曲线经坐标变换后的采样点与输出，
并读取实际类型，椭圆在本机变为样条。draw_ellipse 核验理论点和周长，直接 3D 创建会
产生无有效曲线的原生对象，因此在修改前拒绝。模型边/面与部分圆弧等输入的完整对应
几何核验仍未覆盖；返回的 geometry_correspondence_confirmed 明确区分已核验与未核验。
其他 3D 曲线、工作平面、完整约束/尺寸与更多建模组合仍有缺口。
add_3d_dimension 用两个原生点索引创建 X/Y/Z 投影尺寸；重建求解后恢复原草图编辑，
核验线性尺寸、点的持久引用及实际轴向距离。零件 XYZ 和装配体 XY 实测通过；
本机装配体 Z 接口返回空，明确失败并保留缺口。
含 3D 圆/椭圆转换的零件中，后续 X 尺寸也出现原生拒绝，仍为缺口；原生点选择前
验证持久引用，避免把选择成功当成选中了正确点。list_dimensions 保留原生状态值：
0 未知、1 从动、2 驱动，并修正 driven 标记。

Geometry: draw_line, draw_centerline, draw_circle, draw_rectangle,
draw_arc, draw_3point_arc, draw_ellipse, draw_polygon, draw_slot,
draw_point, draw_spline.

Editing: sketch_fillet, sketch_chamfer, sketch_trim, sketch_offset,
sketch_mirror, convert_entities, set_construction_geometry.

Parametrics: add_relation, add_dimension, set_dimension, list_dimensions.

Features

boss_extrude, cut_extrude, revolve, fillet, chamfer, shell, draft,
rib, simple_hole, sweep, loft, linear_pattern, circular_pattern,
mirror_feature, delete_feature, rename_feature, set_feature_suppression.

Inspection — the feedback channel

直接编辑

拓扑改变后重新查询面和边。删除与修补、替换面已通过实机体积/面积检查；
删除面的填充及相切填充模式仍待专项验证。

Assemblies

list_components, insert_component, add_mate, list_mates,
set_component_fixed, set_component_visibility, set_component_suppression,
set_component_configuration.

多实体、曲面与螺旋线

实体操作沿用 selection，例如 {"selection": {"bodies": [0, 1]}}。
索引取自 list_bodies，几何变化后需重新查询。曲面体索引与实体索引独立，
曲面选择使用 surface_bodies，索引取自 list_surface_bodies。

修剪先调用 preview_surface_trim，再把返回的区域索引传给 trim_surface。
标准修剪指定一个 trim_selection；相互修剪设置 mode=mutual，只指定目标曲面体。
区域索引按目标顺序、包围盒和面积排序，几何变化后必须重新预览。
复杂区域可用 picked_points_mm 指定实际落在区域上的选择点。
相互修剪在本机即使 knit=false 仍会合并相接曲面；工具返回失败并保留特征信息。
实体形成选项、更多复杂曲面组合和旧版软件尚待覆盖或实测。

边界曲面的 direction1、direction2 是有序曲线列表，每项包含一个 selection。
曲线需先全部选择，再设置条件；创建后读取实际曲线数量、影响范围、相切类型和实体类型。
create_solid=true 使用原生 InsertNetBlend2 的形成实体选项，旧接口不支持该选项。
相切/曲率连续性检查使用输入面边界的几何采样和输出曲面的法向、第二基本形式，
参数读回正确而几何不符时仍返回失败。本机圆端面案例的法向差为 90°，该细项尚未完成。
方向向量、中心线、控制柄编辑和更多复杂边界条件仍待覆盖。

钣金与焊件

官方 Motion 算例

list_motion_studies、create_motion_study、activate_motion_study、
duplicate_motion_study、delete_motion_study、set_motion_study_type、
set_motion_study_timing。

时间单位为秒。零件与装配体均支持基础算例管理；工具读取实际支持的类型位掩码，
无法使用的 Basic Motion 或 Motion Analysis 会返回失败，不自动加载模块。
算例管理已验证，动力学求解、载荷、接触、结果曲线与动画输出仍待覆盖。

文档、配置、属性与方程

configuration 为空时操作文档级属性，非空时必须是已存在的配置名称。
实例选择只作用于当前 MCP 服务进程；process_id=0 恢复默认 COM 注册。
可通过 SW_MCP_SESSION_PID 指定启动时连接的已有实例；显式工具选择优先。
实例退出后调用会失败，不会自动切换到另一个实例。查询可读不代表建模命令正常。
方程里的单位由 SOLIDWORKS 语法解释，应明确写出 mm 等单位；方程索引在删除后变化。

Engineering drawings

create_drawing, list_sheets, add_sheet, activate_sheet,
insert_standard_views, insert_model_view, insert_projected_view,
insert_section_view, insert_detail_view, list_drawing_views,
activate_drawing_view, create_drawing_sketch, set_drawing_view,
insert_model_annotations, auto_dimension_view, insert_center_marks,
insert_centerlines, add_note.

For section and detail views, call create_drawing_sketch after activating the
parent view, then use the normal draw_line or draw_circle sketch tools.

A worked example

create_new_document   { "kind": "part" }
create_sketch         { "plane": "front", "name": "Base" }
draw_rectangle        { "x1_mm": 10, "y1_mm": 10, "x2_mm": 70, "y2_mm": 50 }
add_dimension         { "selection": { "sketch_segments": [0] }, "kind": "horizontal",
                        "value_mm": 80, "place_x_mm": 40, "place_y_mm": -10 }
add_dimension         { "selection": { "sketch_segments": [1] }, "kind": "vertical",
                        "value_mm": 50, "place_x_mm": -10, "place_y_mm": 30 }
close_sketch          {}
boss_extrude          { "depth_mm": 20, "name": "BasePad" }

list_edges            { "curve_type": "line", "min_length_mm": 19 }   // find the four verticals
fillet                { "radius_mm": 5, "selection": { "edges": [0, 1, 2, 3] } }
shell                 { "thickness_mm": 2, "selection": { "faces": [4] } }

capture_screenshot    { "view": "isometric" }
get_mass_properties   {}

Notes from the implementation

These are the things that cost real time. They are documented because anyone
automating SOLIDWORKS from Python will hit them.

SOLIDWORKS members are inconsistently exposed to pywin32. Most are declared
in the type library as PROPGET with arguments. Late-bound pywin32 may resolve
such a member on plain attribute access by invoking it with no arguments.
IBody2.GetFaces then returns a bound method that looks like a one-element
result — which is why an extruded box reported exactly one face. Worse,
ModelDocExtension.AddDimension invoked that way crashes SOLIDWORKS outright.
sw_core.flag_methods() calls _FlagAsMethod on every member the server invokes
with arguments, and sw_core.value() invokes zero-argument callables rather than
returning the method object.

Modal dialogs deadlock the server. AddDimension2 pops the "Modify" box
whenever Input dimension value is enabled — which is the default. A modal
dialog blocks the COM call that opened it, and with it the whole server, until
somebody clicks. Dimension tools turn the preference off and restore it after.
If a tool ever hangs, look for a dialog behind the SOLIDWORKS window.

Return values lie. SketchTrim returns False on success. The Create*
sketch APIs return arrays whose truthiness is unreliable. SketchAddConstraints
takes a magic string and silently ignores one it does not recognise. So the
drawing tools judge success by the sketch's segment count, sketch_trim by
whether the sketch actually changed, and add_relation uses the typed
ISketchRelationManager.AddRelation and verifies via the relation count — and on
failure reports which relations that selection would accept.

Most failures are silent. SOLIDWORKS returns null far more often than it
raises. Every feature tool therefore rebuilds and reports
ModelDocExtension.GetWhatsWrong, and check_errors exposes it directly.

sketch_trim needs its target selected. Pass the segment in selection;
the point alone only tells SOLIDWORKS which piece to discard.

Multi-reference features want distinct marks. InsertRefPlane reads its
first, second, and third reference from marks 0, 1, 2 — not from selection
order. Selecting all of them with mark 0 silently produces nothing, which is why
create_plane selects each reference with its own mark and documents that
references are consumed in written order.

Two unit traps. IPartDoc.GetPartBox(False) returns document units, not
metres, so it reads 1000x large if you treat it like the rest of the API; pass
True. And swSketchLINE is 0, so folding a segment type through or turns
every line into "unknown".

Known limitations

• One SOLIDWORKS session, one COM apartment: tool calls are serialised. Two
  clients driving the same session at once will deadlock it.
• Snapshot indices from list_faces / list_edges are invalidated by any
  geometry change. Re-list; do not cache.
• A modal dialog opened by SOLIDWORKS for any other reason will still block
  the server until dismissed.
• rib is picky about its profile. InsertRib returns void and simply builds
  nothing unless the open profile reaches material at both ends and the
  extrusion direction can get there. The tool defaults to parallel_to_sketch
  (right for a cross-section profile) and retries the other direction
  automatically, reporting which one worked. A profile that overlaps an existing
  rib still fails, and the tool says so rather than pretending.
• Only the first insert_projected_view off a given parent succeeds;
  subsequent projections from the same parent return nothing, through
  re-activation and rebuild alike. Use insert_standard_views for a full
  orthographic set.
• Detail-view scale is absolute (model to paper), not relative to the parent.
  On a 1:4 sheet, 2:1 makes the detail eight times the parent view and it
  overflows the sheet. Pick a scale near the sheet scale.
• Standard-plane and model-view display names are localized. Use front,
  top, and right for reference planes, and use names returned by
  list_drawing_views for drawing views; do not hard-code English UI labels.
• through_all_both is translated internally to a two-direction feature with
  through_all in both directions. Passing swEndCondThroughAllBoth as a
  single-ended feature silently cuts only one side in SOLIDWORKS 2026.
• circular_pattern cannot pattern a feature that built a separate body
  (merge: false) — SOLIDWORKS rejects the feature scope. Merge the body, or
  pattern the body instead.
• save_document cannot overwrite a file SOLIDWORKS currently has open, even
  with overwrite: true. The error says so when that is the cause.

Testing

The useful tests are live SOLIDWORKS tests: the COM behaviour that matters here
cannot be mocked faithfully. With SOLIDWORKS already running, run:

.\.venv\Scripts\python.exe tests\live_p0_regression.py

It verifies the P0 geometry/constraint regressions, including the full-volume
through_all_both cut.

Every tool has been exercised against SOLIDWORKS 2026 SP3.2 on a Simplified
Chinese install. Where a result could be checked numerically it was: the revolved
ring, swept rod and lofted cone match their closed-form volumes; a 5-degree
draft removes exactly the expected wedge; rib produces exactly the triangle
under its profile; through_all_both removes the full cylinder rather than half
of it. The limitations above are what survived that pass.

新增 28 个工具使用 tests/live_expansion_regression.py 验证。该脚本只修改新建测试文档，
结束时关闭它们并恢复原活动文档；装配体引用的测试零件保存在输出根目录下
.expansion-tests/<uuid>/。验证包括缩放体积、旋转包围盒、布尔运算体积、
曲面面积、螺旋线高度、配置、属性、方程以及组件状态的读取结果。

python tests/live_expansion_regression.py

The original 92 tools were also exercised on SOLIDWORKS 2016 SP3 with a German
install. The 28 expansion tools have been checked on SOLIDWORKS 2026 SP3.2;
their behaviour on older releases has not yet been verified. Where a release lacks the newest
numbered method (FeatureCut4, FeatureLinearPattern5, CreateDetailViewAt4,
...) the tool falls back to the earlier variant with the arguments it takes; on
newer releases the newest name is always tried first, so nothing changes there.

Layout

tools/tlb_probe.py is worth knowing about before you add a tool. The published
API reference disagrees with the shipped type library often enough to matter —
FeatureFillet3 takes 14 arguments here, not the documented 7 — so check first:

python tools/tlb_probe.py methods '^IFeatureManager$' '^FeatureFillet3$'
python tools/tlb_probe.py enums '^swMateType_e$'

Adding a tool means writing one decorated function; the registry does the rest.

@tool("my_tool", "What it does. Lengths are millimetres.",
      {"depth_mm": {"type": "number"}}, ["depth_mm"])
def my_tool(args: dict[str, Any]) -> dict[str, Any]:
    _, doc = require_part()
    ...
    return result(True, "Did the thing.")

License

Apache License 2.0 — see LICENSE. Copyright 2026 JIALE LIU.

Use it, change it, ship it in a commercial product; that is all allowed. What
the license does require, if you redistribute this or anything derived from it,
is that you keep the copyright notices, pass on a copy of the NOTICE
file, and state which files you changed.