ZWCAD MCP Server

中望CAD（ZWCAD）自动化 MCP 服务，让大模型通过 MCP 协议直接操控 ZWCAD 平台与中望机械CAD，完成绘图、标注、图层/块/样式管理，以及图框、标题栏、明细表（BOM）等机械操作。

功能概览

分类	工具数	说明
绘图	3	zwcad_draw_entity（2D）、zwcad_draw_batch（批量）、zwcad_draw_3d_solid（3D）
注释与标注	3	zwcad_add_annotation、zwcad_add_dimension、zwcad_insert_block
实体操作	4	zwcad_transform_entity、zwcad_modify_entity、zwcad_get_entity_info、zwcad_set_entity_properties
对象查询	3	zwcad_find_object、zwcad_get_objects_in_model、zwcad_query_dimensions
样式管理	1	zwcad_manage_style（图层/线型/文字/标注样式 CRUD）
视图与布局	2	zwcad_manage_view、zwcad_zoom
文档管理	1	zwcad_manage_document
表格操作	1	zwcad_manage_table
选择集	1	zwcad_select_entities
图块管理	1	zwcad_manage_block
系统工具	3	zwcad_get_variable、zwcad_set_variable、zwcad_get_app_info
诊断工具	3	zwcad_get_capabilities、zwcad_diagnose、zwcad_mech_diagnose
标题栏	1	zwcad_mech_manage_title_block
图框	2	zwcad_mech_manage_frame、zwcad_mech_create_frame
明细表	2	zwcad_mech_manage_bom、zwcad_mech_create_partlist
机械数据库	1	zwcad_mech_manage_db
机械应用	4	zwcad_mech_doc、zwcad_mech_cad_environment_init、zwcad_mech_get_balloon、zwcad_mech_insert_balloon
扩展数据	3	zwcad_manage_dictionary、zwcad_manage_xdata、zwcad_manage_utility

共计 39 个工具（ZWCAD 平台 26 + 机械扩展 11 + 统一诊断 2）。平台工具始终可用；机械工具在未连接中望机械时返回明确错误。

系统要求

• 操作系统：Windows 10/11 x64
• CAD 软件：中望CAD 或 中望机械CAD 已安装并运行，且至少打开一张 DWG
• Python：3.10+（FastMCP 2.x 要求）；使用 uvx 免安装方式则无需手动准备 Python
• 机械工具：需要中望机械CAD 及其匹配版本的 ZwmToolKit
• 位数：Python 与 CAD 位数建议一致

快速开始

最简单的接入方式：在支持 MCP 的客户端（Cursor / Claude Desktop / WorkBuddy 等）中安装此 MCP 服务：

{
  "mcpServers": {
    "zwcad": {
      "command": "uvx",
      "args": ["zwcad-mcp"],
      "env": {
        "PYTHONUTF8": "1"
      }
    }
  }
}

uvx 会自动准备 Python、创建隔离环境并拉取全部依赖（等价于 npm 世界的 npx）。前置条件：本机装有 uv。从源码运行见下方步骤。

1. 安装依赖

pip install -r requirements.txt

或直接从 PyPI 安装（免源码）：

pip install zwcad-mcp

2. 启动中望CAD（或中望机械CAD）

确保中望CAD（或中望机械CAD）已启动并打开了一张 DWG 文件。机械工具需中望机械CAD 及匹配版本的 ZwmToolKit。

3. 启动 MCP Server

python -m zwcad2d

或使用一键启动脚本：

start.bat

若已通过 pip install zwcad-mcp 安装，也可直接运行：

zwcad-mcp

4. 配置 MCP 客户端

本项目是标准 MCP 服务（stdio），任意支持 MCP 协议的客户端均可接入。

Cursor

在项目根目录创建 .cursor/mcp.json，或编辑全局配置：

{
  "mcpServers": {
    "zwcad": {
      "command": "uvx",
      "args": ["zwcad-mcp"],
      "env": {
        "PYTHONUTF8": "1"
      }
    }
  }
}

若使用源码方式，可指向项目 .venv：

{
  "mcpServers": {
    "zwcad": {
      "command": "D:\\YOUR_PATH\\ZWCAD-2D\\.venv\\Scripts\\python.exe",
      "args": ["-m", "zwcad2d"],
      "env": {
        "PYTHONUTF8": "1"
      }
    }
  }
}

Claude Desktop

编辑 ~/AppData/Roaming/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "zwcad": {
      "command": "uvx",
      "args": ["zwcad-mcp"],
      "env": {
        "PYTHONUTF8": "1"
      }
    }
  }
}

WorkBuddy

WorkBuddy 接入方式与 Cursor 相同（见上），使用 uvx zwcad-mcp 免安装即可；也可参考项目根目录 mcp.example.json 使用本地源码方式，将 D:\YOUR_PATH 替换为项目实际所在目录。例如项目位于 C:\ZWCAD-MCP 时：

{
  "mcpServers": {
    "zwcad": {
      "command": "C:\\ZWCAD-MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "zwcad2d"],
      "env": {
        "PYTHONUTF8": "1"
      }
    }
  }
}

保存配置并重启 WorkBuddy 后生效。

工具详细说明

绘图工具

工具	说明	entity_type / solid_type
zwcad_draw_entity	绘制2D实体	line, circle, arc, ellipse, lwpolyline, polyline, spline, point, ray, xline, mline, 3d_polyline
zwcad_draw_batch	批量绘制多个实体，减少交互轮次	entities 为 dict 列表，每项含 entity_type 与 params，可选 layer
zwcad_draw_3d_solid	绘制3D实体	box, cylinder, cone, sphere, torus, wedge, 3d_face

注释与标注

工具	说明	annotation_type / dim_type
zwcad_add_annotation	添加注释对象	text, mtext, leader, tolerance, mleader, hatch, table
zwcad_add_dimension	添加标注（支持公差/配合代号）	aligned, rotated, diametric, radial, angular, ordinate
zwcad_insert_block	在指定位置插入图块	rotation 为弧度

标注公差与配合（zwcad_add_dimension 与 zwcad_modify_entity(entity_type="dimension") 通用，均放在 params 中，可选）：

参数	说明
tolerance_display	公差显示方式：none|symmetrical(对称)|deviation(偏差)|limits(极限)|basic(基本)，或 0-4
upper_deviation / lower_deviation	上/下偏差（带符号，如 0.021 / -0.05）
tolerance_precision	公差小数位数 0-8
tolerance_height_scale	公差字高系数（GB 常用 0.7）
fit_symbol	配合代号，如 "H7"、"H7/g6"（含 / 或 ^ 时默认堆叠为分数显示）
fit_stacked / fit_height_scale	配合代号是否堆叠（默认 True）/ 字高系数（默认 0.7）
text_prefix / text_suffix / text_override	标注文字前缀/后缀/替代（<> 表示测量值）

示例：直径50H7孔 → zwcad_add_dimension(dim_type="diametric", params={..., "fit_symbol": "H7"})； 50(+0.021/0)偏差 → params={..., "tolerance_display": "deviation", "upper_deviation": 0.021, "lower_deviation": 0}； 已有标注补公差 → zwcad_modify_entity(entity_type="dimension", handle="A3F", params={"tolerance_display": "limits", ...})。

实体操作

工具	说明	action / entity_type
zwcad_transform_entity	实体变换	copy, move, rotate, mirror, scale, delete, array_polar, array_rectangular
zwcad_modify_entity	修改实体几何属性（含标注公差/配合）	circle, arc, line, text, mtext, polyline, spline, dimension, offset, explode
zwcad_get_entity_info	获取实体详细信息（属性、几何数据、边界框）	-
zwcad_set_entity_properties	设置实体通用属性（图层/颜色/线型等）	-

实体定位方式统一：handle（优先，O(1)）或 object_type + property_name + property_value。

对象查询

工具	说明
zwcad_find_object	按类型/属性/句柄查找对象
zwcad_get_objects_in_model	获取模型空间对象列表（object_type 可选过滤，limit 默认 500）
zwcad_query_dimensions	快速查询所有标注（尺寸值/公差/文字覆盖等）；原生 DXF 过滤，远快于逐个迭代；detail=summary|full，可按 layer 过滤

样式管理

工具	说明	style_type × action
zwcad_manage_style	图层/线型/文字/标注样式 CRUD	style_type: layer, linetype, textstyle, dimstyle; action: list, add, set_active, set_properties

视图、布局与缩放

工具	说明	action / mode
zwcad_manage_view	布局/视图管理	list_layouts, get_active_layout, add_layout, set_active_layout, list_views, add_view, set_active_space
zwcad_zoom	视图缩放	extents, all, window, center, scale, previous

文档管理

工具	说明	action
zwcad_manage_document	文档新建/保存/关闭/导入/导出/打印	new, save, close, info, list, activate, export, import, plot, regen, start_undo, end_undo, wblock

表格、选择集与图块

工具	说明
zwcad_manage_table	表格单元格/行/列操作（set_cell, get_cell, insert_rows, delete_rows, set_column_width, set_row_height, merge_cells）
zwcad_select_entities	选择集操作（窗口/交叉/多边形/过滤器选择）
zwcad_manage_block	图块定义/信息/属性管理（list, info, create, get_attributes）

系统工具

工具	说明
zwcad_get_variable / zwcad_set_variable	读写系统变量（如 DIMSCALE, LTSCALE, OSMODE）
zwcad_get_app_info	获取应用信息。scope: cad（ZWCAD版本/路径/窗口）、mech_version、mech_cad_path、mech_zwm_path、mech_style_path、mech_about

诊断工具

工具	说明
zwcad_get_capabilities	查看当前可用的产品、连接状态、工具组和活动图纸
zwcad_diagnose	诊断平台和机械后端，并给出不修改系统的排障建议
zwcad_mech_diagnose	诊断机械模块连接与 ZwmToolKit 类型库加载状态。逐项探测：类型库加载、ZWCAD 应用、ZwmApp、ZwmDb、标题栏获取，返回各探测项状态与修复建议。每次调用自动重置连接缓存以获取最新状态

标题栏

工具	说明	action
zwcad_mech_manage_title_block	标题栏读取/设置/批量更新	get_info, set_field, update_batch, get_field_count, get_field_by_index

⚠️ 此工具依赖 ZwmToolKit 类型库，类型库未加载时将快速返回 TYPELIB_NOT_LOADED 错误。

图框

工具	说明	action
zwcad_mech_manage_frame	图框查询/切换/更新/刷新	list, get_info, get_count, get_name_by_index, get_name_by_point, get_next_name, switch, update, refresh
zwcad_mech_create_frame	新建图幅/图框（所有参数可选，默认从 XML 配置读取）	std_name（如 GB）、frame_size_name（如 A3）、orientation: landscape|portrait；have_*: 各栏开关(dhl/fjl/btl/csl/ggl)

⚠️ zwcad_mech_create_frame 以及 zwcad_mech_manage_frame 的 get_info/update 操作依赖类型库；list/get_count/switch/refresh 等操作不依赖类型库，在类型库未加载时仍可使用。

明细表（BOM）

工具	说明	action
zwcad_mech_manage_bom	明细表增删改查	get_row_count, get_row, add_row, update_row, insert_row, delete_row, set_field, get_field, get_field_count, batch_update, refresh
zwcad_mech_create_partlist	创建明细表实体	发送 _.ZwmPartlist 命令

⚠️ 除 refresh 外的所有操作依赖类型库。refresh 不依赖类型库，在类型库未加载时仍可使用。

💡 BOM 持久化说明：修改 BOM 数据后，update_row/set_field/batch_update 等操作会自动将更改写入 DWG 图纸。请勿在 BOM 修改后调用 zwcad_mech_manage_db 的 save 操作，save 会从图纸重载数据导致修改丢失。

机械模块

工具	说明
zwcad_mech_manage_db	机械数据库操作。action: open/save/close
zwcad_mech_doc	机械文档操作。action: open/new/new_named
zwcad_mech_cad_environment_init	初始化 CAD 标准环境（GB, ISO, DIN 等）
zwcad_mech_get_balloon	获取球标对象用于零件编号标注
zwcad_mech_insert_balloon	插入球标（零件序号标注），通过 LISP 命令 Zwm_BalloonInsert 实现。参数：箭头/符号位置、文字、序号类型(0-6)、是否带引线

以上工具不依赖类型库，在类型库未加载时仍可通过 late binding 正常工作。

扩展数据

工具	说明	action
zwcad_manage_dictionary	命名对象字典与 XRecord 管理	list, add, get_items, add_object, get_object, remove, rename, add_xrecord, get_xrecord
zwcad_manage_xdata	实体扩展数据(XData)读写	list_apps, register_app, get_xdata, set_xdata, delete_xdata
zwcad_manage_utility	CAD 工具方法（坐标转换/角度/距离计算）	translate_coordinates, polar_point, angle_to_real, angle_to_string, real_to_string, distance_to_real

ZwmToolKit 类型库加载机制

机械模块（标题栏/明细表/图框等）依赖 ZwmToolKit.tlb 类型库。pyzwcadmech.api 采用 5 级回退策略 加载类型库，确保在各种安装环境下都能成功加载：

优先级	策略	说明
1	文件系统 glob	在 C:\Program Files\ZWSOFT\ZWCAD Mechanical*\Zwcadm\ 下搜索 ZwmToolKit*.tlb，按版本年份排序优先选最新
2	环境变量	读取 PYZWCADMECH_TLB_PATH 环境变量指向的 .tlb 文件
3	本地路径	搜索当前工作目录和包目录下的 ZwmToolKit.tlb
4	预生成模块	复用已生成的 comtypes.gen.ZwmToolKitLib 模块（如预加载生成的）
5	GUID 注册表	按类型库 GUID {2F671C10-669F-11E7-91B7-BC5FF42AC839} 从 Windows 注册表加载

server.py 预加载

src/zwcad2d/server.py（MCP Server 主程序，入口见「快速开始」第 3 步）在导入时按上述 GUID 调用 comtypes.client.GetModule 预加载类型库。预加载成功时，后续 pyzwcadmech.api 即使文件搜索失败，也能通过策略 4 复用已生成的模块；同时将 comtypes.client.gen_dir 置空，使 COM 包装仅在内存中生成，避免某些中文版类型库触发 comtypes 的 mbcs 磁盘缓存解码错误。

运行时重试

如果类型库在 import 时加载失败（例如 ZWCAD 尚未启动），ZwCADMech.zwm_app 属性在首次访问时会自动调用 reload_typelib() 重试加载。也可通过 zwcad_mech_diagnose 工具触发重新诊断。

环境变量配置

如果类型库无法自动加载（如自定义安装路径），可设置环境变量：

{
  "mcpServers": {
    "zwcad": {
      "command": "uvx",
      "args": ["zwcad-mcp"],
      "env": {
        "PYTHONUTF8": "1",
        "PYZWCADMECH_TLB_PATH": "C:\\Program Files\\ZWSOFT\\ZWCAD Mechanical 2026 Chs\\Zwcadm\\ZwmToolKit.tlb"
      }
    }
  }
}

类型库依赖矩阵

工具	类型库未加载时	说明
zwcad_mech_manage_title_block	❌ 不可用	返回 TYPELIB_NOT_LOADED 错误
zwcad_mech_create_frame	❌ 不可用	返回 TYPELIB_NOT_LOADED 错误
zwcad_mech_manage_bom（除 refresh）	❌ 不可用	返回错误并附带修复提示
zwcad_mech_manage_frame（get_info/update）	❌ 不可用	返回错误并附带修复提示
zwcad_mech_manage_bom（refresh）	✅ 可用	通过 late binding 工作
zwcad_mech_manage_frame（list/switch/refresh 等）	✅ 可用	通过 late binding 工作
zwcad_mech_manage_db / zwcad_mech_doc / zwcad_mech_cad_environment_init / zwcad_mech_get_balloon / zwcad_mech_insert_balloon	✅ 可用	通过 late binding 工作
zwcad_get_app_info（mech_* scope）	✅ 可用	通过 late binding 工作
所有 pyzwcad 基础工具（绘图/标注/变换/查询等）	✅ 可用	完全不依赖类型库

示例：通过 AI 创建图框

在 Cursor / Claude Desktop / WorkBuddy 中，告诉 AI：

"创建一个A3横向图框，GB标准，包含标题栏和附加栏"

AI 会自动调用 zwcad_mech_create_frame 工具：

zwcad_mech_create_frame(
    frame_size_name="A3",
    orientation="landscape",
    std_name="GB",
    have_btl=True,
    have_fjl=True
)

项目结构

ZWCAD-MCP/
├── pyproject.toml            # 打包配置（hatchling），console script: zwcad-mcp
├── src/zwcad2d/
│   ├── __init__.py           # __version__
│   ├── __main__.py           # python -m zwcad2d 入口
│   ├── server.py         # MCP Server 主程序（39 个工具）
│   └── hatch_info.py         # 剖面线边界环提取（COM + LISP 回退）
├── requirements.txt          # Python 依赖
├── mcp.example.json          # MCP 客户端配置示例
├── install.bat               # Windows 一键安装脚本（创建 .venv 并以可编辑模式安装）
├── start.bat                 # Windows 一键启动脚本
├── verify.bat                # 本地验证脚本
├── connector/                # Connector 市场上架材料
│   ├── connector-meta.json   # 元信息
│   ├── mcp.json              # 上架配置（uvx zwcad-mcp）
│   ├── icon.svg
│   └── skills/SKILL.md       # AI 使用指南
├── tests/                    # 静态/运行时/stdio 三份测试
├── THIRD_PARTY_NOTICES.md
├── LICENSE
└── README.md

架构

AI 客户端（Cursor / Claude Desktop / WorkBuddy / 任意 MCP 客户端）
        │
        │ MCP 协议（stdio, JSON-RPC）
        ▼
   FastMCP Server（入口: src/zwcad2d/server.py, 39 个工具）
        │
        ├── pyzwcad ──────► ZWCAD.Application COM API（平台绘图/标注/变换/查询）
        │                   └── 不依赖类型库，始终可用
        │
        └── pyzwcadmech ──► ZwmToolKit COM API（机械功能）
                │
                ├── 类型库加载（5级回退策略）
                │   ├── 1. 文件 glob（版本感知排序）
                │   ├── 2. PYZWCADMECH_TLB_PATH 环境变量
                │   ├── 3. 本地路径
                │   ├── 4. 预生成 comtypes.gen 模块
                │   └── 5. GUID 注册表加载
                │
                ├── ZwmApp ──── 应用层（版本/路径/文档操作）── 不依赖类型库
                ├── ZwmDb ──── 数据库层（打开/保存/图框管理）
                │   ├── open_file/save/close/switch_frame ── 不依赖类型库
                │   ├── get_title() ──► ZwmTitle ── 依赖类型库
                │   ├── get_bom() ────► ZwmBom ─── 依赖类型库
                │   └── get_frame() ──► ZwmFrame ─ 依赖类型库
                │
                └── 运行时重试: zwm_app 属性在 ZWM=None 时自动调用 reload_typelib()

   连接缓存: get_cad_connection() 缓存 (ZwCAD, ZwCADMech) 实例，自动处理失效重连
   诊断工具: zwcad_diagnose / zwcad_mech_diagnose 每次调用自动重置连接缓存，逐项探测

重要说明

1. ZWCAD 必须运行：所有工具调用都要求 ZWCAD（或中望机械CAD）已启动并打开了 DWG 文件。

2. 单活动实例策略：同一时间只操作一个 ZWCAD 系列实例。多个 ZWCAD/机械实例并存时，Windows COM 可能连接到非预期实例。

3. 样式文件路径：zwcad_mech_create_frame 工具从 XML 配置文件读取默认样式：C:\Users\Public\Documents\ZWSoft\zwcadm\2026\zh-CN\styles

4. 类型库加载：机械模块（标题栏/明细表/图框）依赖 ZwmToolKit 类型库。正常安装环境下会自动加载；如遇加载失败，可使用 zwcad_mech_diagnose 工具诊断，或设置 PYZWCADMECH_TLB_PATH 环境变量指向 ZwmToolKit.tlb 文件。

5. 连接缓存：MCP Server 会缓存 CAD 连接实例以提高性能。zwcad_diagnose / zwcad_mech_diagnose 工具每次调用会自动重置缓存以获取最新状态。

6. 写入操作需人工确认：删除实体、覆盖保存、关闭文档、替换插件、修改系统变量等写操作会直接改变当前 DWG，调用前请先备份图纸。

7. 本地验证：安装完成后可运行 verify.bat，依次执行：可编辑安装校验 → Python 语法与 39 个本地工具注册、项目未夹带 EXE/ZRX/DLL → MCP stdio 端到端冒烟（不连 CAD）。真实 COM 和机械类型库仍需在对应产品环境中测试。

依赖

• pyzwcad - ZWCAD Python COM 封装
• pyzwcadmech >=0.3.0 - 中望机械 Python COM 封装（含 BOM 读写修复）
• FastMCP - MCP 协议服务框架
• comtypes - COM 类型库加载与接口调用
• pywin32 - Windows COM 初始化支持

License

MIT License - See LICENSE