ZWCAD机械版 MCP Server

中文 | English

---

中望机械CAD自动化 MCP 服务，让大模型通过 MCP 协议直接操控中望机械CAD完成绘图、编辑标题栏、管理图框和明细表等操作。

演示视频

https://github.com/user-attachments/assets/827604ac-3e79-47f8-8655-71bd306c33cb

绘制渐开线直齿圆柱齿轮示例

https://github.com/user-attachments/assets/489ec032-c238-4d7f-8d69-bb894ef1b40b

功能概览

共计 43 个工具

系统要求

• 操作系统: Windows 10/11
• CAD 软件: 中望机械CAD 2026 已安装并运行
• Python: 3.10+（FastMCP 2.x 起要求 Python 3.10 及以上）

快速开始

最简单的安装MCP方法：打开Agent，在里面输入:安装上此MCP服务: https://github.com/john0909/ZWCAD-Mechanical-MCP

1. 安装依赖

pip install -r requirements.txt

2. 启动中望机械CAD

确保中望机械CAD 2026 已启动并打开了一个 DWG 文件。

3. 启动 MCP Server

python server.py

或使用一键启动脚本：

start.bat

默认 ZWMECH_USE_ZRX=0，机械功能优先使用 pyzwcadmech；如果 ZwmToolKit COM 接口不可用，服务会通过活动 ZWCAD 的 Application.LoadZrx() 自动加载 ZWMechMCP.zrx 并回退到本机桥接。将 ZWMECH_USE_ZRX 设为 1（也接受 true/on/yes）可强制所有机械功能直接走 ZRX。

4. 配置 MCP 客户端

Cursor

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

{
  "mcpServers": {
    "zwcadmech": {
      "command": "python",
      "args": ["path/to/zwcad-mechanical-mcp-server/server.py"]
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "zwcadmech": {
      "command": "python",
      "args": ["path/to/zwcad-mechanical-mcp-server/server.py"]
    }
  }
}

Qoder

参考 mcp-config.json 进行配置。

工具详细说明

绘图工具

注释与标注

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

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

实体操作

对象查询

样式管理

视图、布局与缩放

文档管理

表格、选择集与图块

系统工具

诊断工具

标题栏

默认 auto 模式会先使用 pyzwcadmech，探测失败后自动切换到 ZRX；只有两条路径都不可用时才返回机械后端错误。

图框

图框操作使用当前选定的机械后端。默认优先 pyzwcadmech，故障时自动切换到 ZRX 桥接。

明细表（BOM）

BOM 操作使用当前选定的机械后端；默认模式下无需预先加载 ZRX。ZRX 缺失、端口被占用或 PID 不匹配时，错误详情可在 mech_diagnose 中查看。

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

机械模块

机械符号标注（ZwmToolKit LISP）

以下工具通过 lisp_bridge.py 向 ZWCAD 发送 Zwm_* AutoLISP（Get/Set 经命名字典 ZWM_MCP 临时 XRECORD 回传；Insert 以 ModelSpace 新增实体句柄为准）。插入前建议先 cad_environment_init("GB")。各工具 params 字段见 MCP 工具说明（server.py 中对应 docstring）。

以上机械模块与符号工具使用当前选定的机械后端。ZRX 回退覆盖当前 MCP 暴露的调用面，不承诺覆盖 pyzwcadmech 未被 MCP 使用的全部公开 API。

扩展数据

机械后端自动回退

mechanical_backend.py 在 MCP 开始接受请求前选择机械后端。ZWMECH_BACKEND 支持以下模式：

启动探测为只读操作，检查类型库、机械版本、当前机械 DB、标题栏、BOM 和图框；没有相应图纸对象属于正常结果，调用异常才判定失败。探测放在带超时的子进程中，避免异常 COM 阻塞 MCP 启动。

ZRX 回退流程如下：

1. 将 ZWMECH_ZRX_PATH 按项目目录解析相对路径；默认使用 zrx\ZWMechMCP.zrx。也支持填写绝对路径覆盖默认值。
2. 通过活动 ZWCAD.Application.LoadZrx() 加载插件。
3. 轮询 ZWMECH_BRIDGE_HOST:ZWMECH_BRIDGE_PORT 的 ping。
4. 校验插件标识 ZWMechMCP、版本和 process_id；PID 必须与 Application.HWND 所属 ZWCAD 进程一致。

运行期只从 pyzwcadmech 单向切换到 ZRX。只读操作切换成功后自动重试一次；写操作不会盲目重放，返回 MECHANICAL_BACKEND_SWITCHED_RETRY_REQUIRED，确认图纸状态后重新调用。参数错误、对象不存在和业务错误不会触发切换。两条路径均失败时服务仍启动，机械工具返回 MECHANICAL_BACKEND_UNAVAILABLE，基础 CAD 工具保持可用。

环境变量

PowerShell 中可临时强制一路径：

$env:ZWMECH_BACKEND = "zrx"
python server.py

默认 auto 不要求预先手工加载插件。若需恢复或调试，可在 ZWCAD 中执行 ZRXLOAD/APPLOAD，然后执行 ZWMMECHSTATUS。使用 mech_diagnose 可查看当前后端、探测步骤、切换原因、ZRX 路径、桥接信息以及两条路径的错误。

调试两条路线时，建议分别使用 ZWMECH_USE_ZRX=0（默认，优先 COM）和 ZWMECH_USE_ZRX=1（强制 ZRX）。ZWMECH_BACKEND 仍可用于兼容旧配置或启用 auto、pyzwcadmech、zrx 模式。

示例：通过 AI 创建图框

在 Cursor / Claude Code 中，告诉 AI：

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

AI 会自动调用 create_frame 工具：

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

项目结构

zwcad-mechanical-mcp-server/
├── server.py                 # MCP Server 主程序（43个工具）
├── lisp_bridge.py            # AutoLISP SendCommand 与 XRECORD 回传
├── mech_symbols.py           # 机械符号 LISP 编排（manage_* 符号工具）
├── mechanical_backend.py     # 机械探测、选路与运行期回退
├── mech_bridge.py            # ZRX HTTP/JSON 兼容层
├── hatch_info.py             # Hatch 边界环顶点解析
├── requirements.txt          # Python 依赖
├── mcp-config.json           # MCP 客户端配置示例
├── start.bat                 # Windows 一键启动脚本
├── zrx/
│   └── ZWMechMCP.zrx         # ZRX 回退插件（进程内机械接口）
├── tests/                    # 后端选路与工具路由测试
├── .gitignore
├── LICENSE
└── README.md

架构

AI Client (Cursor/Claude/Qoder)
        │
        │ MCP Protocol (STDIO)
        ▼
   FastMCP Server (server.py, 43 tools)
        │
        ├── pyzwcad ──────► ZWCAD.Application COM API (基础绘图/标注/变换/查询)
        │                   └── 不依赖类型库，始终可用
        │
        ├── lisp_bridge.py ─► Zwm_* LISP（符号 Get/Set 经 ZWM_MCP XRECORD）
        │
        └── mechanical_backend.py ──► 机械后端自动选路
                ├── pyzwcadmech ──► ZwmToolKit COM（默认主路径）
                └── mech_bridge.py ──► HTTP/JSON ──► ZWMechMCP.zrx
                                             LoadZrx 自动回退，插件/版本/PID 校验
                                             ZWCAD 进程内调用 ZwmToolKit

   连接缓存: CAD/机械 COM 代理按工作线程缓存，后端切换后按代次重建
   诊断工具: mech_diagnose() 自动重置当前线程缓存并报告两条路径状态

重要说明

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

2. 样式文件路径：create_frame 工具从 ZWCAD 的 XML 配置目录读取默认样式；实际目录随安装位置和语言版本变化。

3. 机械后端：默认先探测 pyzwcadmech，失败后自动对活动 ZWCAD 调用 LoadZrx()。手工 ZRXLOAD/APPLOAD 和 ZWMMECHSTATUS 仍可用于恢复、调试或强制 ZWMECH_BACKEND=zrx 验收。

4. 连接缓存：连接按 MCP 工作线程隔离，避免跨 STA 复用 COM 代理。mech_diagnose 会重置当前线程缓存以获取最新状态。

依赖

• pyzwcad - ZWCAD Python COM 封装
• pyzwcadmech >=0.3.0 - 中望机械 Python COM 封装（含 BOM 读写修复）
• FastMCP - MCP 协议服务框架
• comtypes - COM 类型库加载与接口调用
• pywin32 - Windows COM 初始化；manage_xdata 读取 XData 时绕开 comtypes 代理签名问题

License

MIT License - See LICENSE

---

English

ZWCAD Mechanical MCP Server

A ZWCAD Mechanical CAD automation MCP service that allows AI models to directly control ZWCAD Mechanical via the MCP protocol for drawing, title block editing, frame management, BOM operations, and more.

Feature Overview

Total: 43 tools

System Requirements

• OS: Windows 10/11
• CAD Software: ZWCAD Mechanical 2026 installed and running
• Python: 3.10+ (FastMCP 2.x requires Python 3.10 or newer)

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Start ZWCAD Mechanical

Ensure ZWCAD Mechanical 2026 is running with a DWG file open.

3. Start MCP Server

python server.py

Or use the launcher:

start.bat

ZWMECH_USE_ZRX defaults to 0, so mechanical tools prefer pyzwcadmech. If the ZwmToolKit COM interfaces are unavailable, the server calls Application.LoadZrx() on the active ZWCAD instance and falls back to the local ZRX bridge. Set ZWMECH_USE_ZRX to 1 (also accepts true/on/yes) to force every mechanical tool through ZRX.

4. Configure MCP Client

Cursor

Create .cursor/mcp.json in the project root:

{
  "mcpServers": {
    "zwcadmech": {
      "command": "python",
      "args": ["path/to/zwcad-mechanical-mcp-server/server.py"]
    }
  }
}

Claude Desktop

Edit ~/AppData/Roaming/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zwcadmech": {
      "command": "python",
      "args": ["path/to/zwcad-mechanical-mcp-server/server.py"]
    }
  }
}

Qoder

Refer to mcp-config.json for configuration.

Tool Reference

Drawing

Annotation & Dimension

Dimension tolerance & fit (optional keys in params of add_dimension, or modify_entity with entity_type="dimension"):

Examples: a ø50H7 hole (diametric) -> add_dimension(dim_type="diametric", params={..., "fit_symbol": "H7"}); 50(+0.021/0) deviation -> params={..., "tolerance_display": "deviation", "upper_deviation": 0.021, "lower_deviation": 0}; add tolerance to an existing dimension -> modify_entity(entity_type="dimension", handle="A3F", params={"tolerance_display": "limits", ...}).

Entity Operations

Object Query

Style Management

View, Layout & Zoom

Document Management

Table, Selection, Block

System

Diagnostics

Title Block

In default auto mode this first uses pyzwcadmech and then falls back to ZRX after a failed probe. A mechanical backend error is returned only when both routes are unavailable.

Frame

Frame actions use the selected mechanical backend: pyzwcadmech by default, then the ZRX bridge after a qualifying failure.

BOM (Bill of Materials)

BOM actions use the selected mechanical backend. The default mode does not require preloading ZRX; missing artifacts, occupied ports, or PID mismatches are reported by mech_diagnose.

💡 BOM Persistence: After modifying BOM data, update_row/set_field/batch_update automatically call refresh_bom() to write changes to the DWG. Do NOT call manage_mech_db’s save after BOM modifications, as save reloads data from the drawing and discards changes.

Mechanical Module

Mechanical symbol annotation (ZwmToolKit LISP)

These tools send Zwm_* AutoLISP through lisp_bridge.py (Get/Set round-trip via temporary XRECORD in named dictionary ZWM_MCP; Insert resolves new entity handles from ModelSpace). Call cad_environment_init("GB") before insert when possible. See each tool’s params in the MCP tool descriptions (server.py docstrings).

Mechanical module and symbol tools use the selected mechanical backend. The ZRX fallback covers the MCP call surface, not every public API exposed by pyzwcadmech.

Extended Data

Automatic Mechanical Backend Fallback

Before accepting MCP requests, mechanical_backend.py selects one process-wide mechanical backend. ZWMECH_BACKEND supports:

The startup probe is read-only and checks the type library, mechanical version, current mechanical database, title block, BOM, and frame. Missing objects in the drawing are valid results; call exceptions are failures. Running the probe in a subprocess with a timeout prevents a stuck COM server from blocking MCP startup.

ZRX fallback:

1. Resolve ZWMECH_ZRX_PATH relative to the project directory; the default is zrx\\ZWMechMCP.zrx. An absolute path may also be supplied to override it.
2. Call Application.LoadZrx() on the active ZWCAD.Application instance.
3. Poll ZWMECH_BRIDGE_HOST:ZWMECH_BRIDGE_PORT for ping.
4. Validate plugin ZWMechMCP, version, and process_id; the bridge PID must match the PID resolved from Application.HWND.

Runtime switching is one-way from pyzwcadmech to ZRX. Read-only operations retry once after a successful switch. Writes are not replayed and return MECHANICAL_BACKEND_SWITCHED_RETRY_REQUIRED; inspect the drawing before deliberately retrying. Parameter, missing-object, and ordinary business errors do not trigger a switch. If both routes fail, MCP still starts, mechanical tools return MECHANICAL_BACKEND_UNAVAILABLE, and basic CAD tools remain available.

Environment Variables

PowerShell example:

$env:ZWMECH_BACKEND = "zrx"
python server.py

In auto mode, preloading the plugin is normally unnecessary. For recovery or debugging, run ZRXLOAD/APPLOAD in ZWCAD and then ZWMMECHSTATUS. mech_diagnose reports the active backend, probe steps, fallback reason, ZRX path, bridge metadata, and errors from both routes.

For route comparison, use ZWMECH_USE_ZRX=0 (default, prefer COM) and ZWMECH_USE_ZRX=1 (force ZRX). ZWMECH_BACKEND remains available for legacy configuration and explicit auto, pyzwcadmech, or zrx modes.

Example: Creating a Frame via AI

In Cursor / Claude Code, tell the AI:

“Create an A3 landscape frame with GB standard, including title block and additional block”

The AI will automatically call the create_frame tool:

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

Project Structure

zwcad-mechanical-mcp-server/
├── server.py                 # MCP Server main program (43 tools)
├── lisp_bridge.py            # AutoLISP SendCommand and XRECORD round-trip
├── mech_symbols.py           # Mechanical symbol LISP dispatch (manage_* tools)
├── mechanical_backend.py     # probe, route selection, and runtime fallback
├── mech_bridge.py            # ZRX HTTP/JSON compatibility client
├── hatch_info.py             # Hatch boundary loop vertex extraction
├── requirements.txt          # Python dependencies
├── mcp-config.json           # MCP client configuration example
├── start.bat                 # Windows one-click launcher
├── zrx/
│   └── ZWMechMCP.zrx         # ZRX fallback plugin (in-process mechanical API)
├── tests/                    # Backend routing and tool dispatch tests
├── .gitignore
├── LICENSE
└── README.md

Architecture

AI Client (Cursor/Claude/Qoder)
        │
        │ MCP Protocol (STDIO)
        ▼
   FastMCP Server (server.py, 43 tools)
        │
        ├── pyzwcad ──────► ZWCAD.Application COM API (basic drawing)
        │                   └── No type library dependency, always available
        │
        ├── lisp_bridge.py ─► Zwm_* LISP (symbol Get/Set via ZWM_MCP XRECORD)
        │
        └── mechanical_backend.py ──► mechanical backend selection
                ├── pyzwcadmech ──► ZwmToolKit COM (default primary route)
                └── mech_bridge.py ──► HTTP/JSON ──► ZWMechMCP.zrx
                                             LoadZrx fallback, plugin/version/PID validation
                                             in-process ZwmToolKit calls

   Connection cache: CAD/mechanical COM proxies are per-worker and rebuilt after switching
   Diagnostics: mech_diagnose() resets the current worker cache and reports both routes

Important Notes

1. ZWCAD Must Be Running: All tool calls require ZWCAD Mechanical to be running with a DWG file open.

2. Style File Path: The create_frame tool reads default styles from the ZWCAD XML configuration directory; the actual location depends on the installation and language.

3. Mechanical backend: The default flow probes pyzwcadmech first, then calls LoadZrx() on the active ZWCAD instance if the probe fails. Manual ZRXLOAD/APPLOAD and ZWMMECHSTATUS remain available for recovery, debugging, or forced ZWMECH_BACKEND=zrx validation.

4. Connection Cache: Connections are isolated per MCP worker to avoid cross-STA COM reuse. mech_diagnose resets the current worker cache for fresh diagnostics.

Tests

python -m unittest discover -s tests -v

The tests do not require a running ZWCAD instance. They cover mechanical backend selection, the ZWMECH_USE_ZRX switch, failover decisions, and tool dispatch.

Dependencies

• pyzwcad - ZWCAD Python COM wrapper
• pyzwcadmech >=0.3.0 - ZWCAD MFG Python COM wrapper (includes BOM read/write fixes)
• FastMCP - MCP protocol server framework
• comtypes - COM type library loading and interface invocation
• pywin32 - Windows COM initialization; also used by manage_xdata to read XData around a comtypes proxy signature mismatch

License

MIT License - See LICENSE