best-cad-mcp

best-cad-mcp

面向处理真实 AutoCAD 图纸的 Agent，提供本地、以句柄为先的 MCP 服务。

检查 DWG，基于结构化几何进行推理，规划受控编辑，验证结果，并导出可视化证据，同时不将 Agent 状态隐藏在图纸中。

简体中文 · 在线演示 · 安装 · 工作流 · 工具配置 · 安全性 · 已知限制

这是一份由经过验证的试运行 CADPlan 生成的真实 AutoCAD 模型空间导出图：包含主视图和俯视图、剖切侧视图、中心线、尺寸、特征标注、剖面线和标题栏。下载 源 DWG 或查看已执行的 CADPlan。

重要

best-cad-mcp 是 Beta 软件，旨在用于受控的本地工作流，由操作人员审查计划和证据，而非在无人值守的情况下修改重要的生产图纸。

为什么选择 best-cad-mcp

大多数 CAD 自动化仅能处理绘图图元。实用的 Agent 工作流还需要准确了解修改什么、为何选中该目标，以及结果是否正确。

该服务与 AutoCAD 在同一个 Windows 账户下运行，并通过 MCP stdio 通信。它基于官方 MCP Python SDK 2.x 原生运行，协商使用 2026-07-28 协议，同时保留对旧版客户端的协商支持。AutoCAD 仍是事实来源；SQLite 会在工作区中存储模型私有上下文、扫描结果和审查材料。面向 AutoCAD 的工具调用会有意在单个事件循环线程上串行执行，以确保 COM 单元安全。

实时 AutoCAD 演示

提示词： 创建一张符合生产要求的 A3 横向螺栓法兰联轴器 装配图，按真实 1:1 比例绘制，包含纵向半剖视图、对齐的 端视图、爆炸示意图、真实尺寸、不同的剖面线、八项 BOM、 对应的零件序号引线、技术要求和受控标题栏。

这是实时 AutoCAD 会话的结果，并非手工编写的 SVG。MCP 客户端加载了随附的 precise_draw_from_spec 提示词，然后运行了 18 个受限生成阶段（162 个步骤）。其自主视觉修复循环使用了两个布局修复计划（4 个步骤）；另外，三个单独记录且经操作人员授权的仅涉及出图效果的发布 QA 计划增加了 10 个步骤。每个计划都经过验证和试运行，然后才进行事务性执行。最终重新扫描索引了 91 个实体；结构化验证检测到 129 个语义对象，处理了 7 个真实尺寸标注，并检查了 134 项约束（127 项满足、7 项未知，且没有违反项）。修复后的几何验证报告显示问题数量为零。发布用打印图经过独立检查，确认为一页横向 A3 PDF。

为确保可复现，仓库中提供的 MCP 客户端会构建本次记录运行所用的确定性 CADPlans。演示展示的是经过优化的提示词所采用的受保护工作流的实时执行，并非一次未经脚本控制的大模型生成。

DXF · A3 PDF · 确切提示词 · CADPlan 包 · 验证报告 · MCP 客户端

该图遵循仓库的通用机械装配惯例，并标注为 DEMO - NOT FOR MANUFACTURE；它不声称符合正式的 ISO、GB、ASME 或其他标准。

快速开始

要求

• Windows
• 推荐使用 AutoCAD 2020 或更高版本，且已安装并获得许可
• AutoCAD 和 MCP 客户端以同一 Windows 用户身份运行
• Python 3.11 或更高版本
• 与 MCP 兼容的本地客户端

安装软件包

python -m pip install --upgrade best-cad-mcp
cad-mcp-doctor --check-autocad

如需渲染叠加层和视觉审查辅助工具：

python -m pip install --upgrade "best-cad-mcp[visual]"
cad-mcp-doctor --check-autocad --require-visual-export

保持 AutoCAD 处于打开状态，然后配置 MCP 客户端以启动 cad-mcp。

Codex

Codex 同时支持全局 ~/.codex/config.toml 和受信任的项目级 .codex/config.toml 文件。此最简安装包配置使用精选的 core 工具配置：

[mcp_servers.best-cad-mcp]
command = "cad-mcp"
cwd = 'C:\CAD\your-project'
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

[mcp_servers.best-cad-mcp.env]
CAD_MCP_TOOL_PROFILE = "core"
CAD_MCP_WORKSPACE_ROOT = 'C:\CAD\your-project'

编辑文件后重启 Codex，然后使用 /mcp 检查已连接的服务。有关配置范围和当前选项，请参阅官方 Codex MCP 配置指南。

Claude Code 和其他使用 JSON 配置的客户端

{
  "mcpServers": {
    "best-cad-mcp": {
      "command": "cad-mcp",
      "env": {
        "CAD_MCP_TOOL_PROFILE": "core",
        "CAD_MCP_WORKSPACE_ROOT": "C:\\CAD\\your-project"
      }
    }
  }
}

将其保存为 CAD 项目根目录下的 .mcp.json，并从该项目启动客户端。CAD_MCP_WORKSPACE_ROOT 应指向正在处理的 CAD 项目，而不是本仓库。安装软件包后，将进程的 cwd 和工作区根目录都设为项目目录，可使运行时文件集中存放。

git clone https://github.com/LokmenoWer/best-cad-mcp.git
cd best-cad-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[visual]"
.\.venv\Scripts\python.exe -m src.doctor --check-autocad

1. 预检 — 运行 check_runtime_environment(check_autocad=true) 或 cad-mcp-doctor --check-autocad；如果结果报告 ok=false，则停止。
2. 扫描 — 在分析现有 DWG 前运行 scan_all_entities。 对于基本图元定位或跨实体轮廓，使用 topology_detail="full"。
3. 理解 — 构建 CAD-IR、概述图纸、查询语义，并通过 explain_entity 确认重要目标。
4. 规划 — 将多步变更表示为 CADPlan，然后调用 validate_cad_plan 和 dry_run_cad_plan。
5. 明确执行 — 只有在获得授权且试运行结果可接受后，才调用 execute_cad_plan(..., allow_modify=true, transactional=true)。
6. 验证 — 重新扫描，运行几何验证，导出清晰视图和叠加图；只有在操作人员打算保留 DWG 更改时才保存。

对于精确编辑，优先使用 AutoCAD 返回的句柄，而不是根据屏幕截图推断名称。对于视觉发现，应将定位结果视为证据：在修改前确认候选实体及其几何形状。

功能

工具配置

随附的客户端配置和示例推荐使用 core，因为它在覆盖常见受保护工作流的同时，能确保工具选择可靠。未设置配置环境变量时，Python 服务会为保持向后兼容而回退到 full。

使用 CAD_MCP_TOOL_PROFILE=lean|core|full 选择配置。也可以通过 CAD_MCP_TOOLS_INCLUDE 和 CAD_MCP_TOOLS_EXCLUDE 进行细粒度的允许/拒绝控制。

从视觉理解到有依据的 CAD 证据

这张主视觉并非用于说明的示意图。它是在一个新的 AutoCAD 文档中通过 90 步 CADPlan 绘制而成，扫描得到 81 个真实实体，验证结果为零几何问题，随后导出为 WMF，并栅格化为上方所示的 PNG。源 DWG、计划、试运行、验证输出、像素/世界坐标映射和 VLM 审查均作为可供审阅的工件保留。

VLM 审查返回的内容不应只有说明文字。以下是同一快照中的真实工件：模型检查的干净 AutoCAD 瓦片，以及其实际句柄叠加图。这些是由映射工具生成的栅格裁剪图，并非重新绘制的文档插图。

干净的 AutoCAD 栅格瓦片	同一快照中的句柄叠加图

叠加图与 WMF 选择导出框对齐，而非与活动视口对齐。AutoCAD 测得的比例框边距得以保留，同时排除了旧版通用视口留白。在此捕获中，映射后的正视图原点为 (734.870, 331.032) px，而真实栅格中观测到的青色中心线交点为 (735, 331) px：最大误差为 0.13 px。

真实的 vlm_review_drawing/v3 结果已通过架构验证并提交，未预先声称任何句柄。其四个区域根据栅格图创建，并锁定到该栅格图的尺寸和 SHA-256；如果 AutoCAD 生成不同的图像，捕获脚本会拒绝这些区域。依据证据的识别将中心孔确定为句柄 8A，将圆角安装槽轮廓确定为 115，并将标题栏语义组确定为 236。剖面填充仍正确地保持为有歧义状态，因为两个真实的填充候选项得分差距很小。

{
  "central_bore":  {"status": "grounded",  "handles": ["8A"]},
  "mounting_slot": {"status": "grounded",  "handles": ["115"]},
  "section_hatch": {"status": "ambiguous", "handles": []},
  "title_block":   {"status": "grounded",  "handles": ["236"]}
}

查看哈希锁定的视觉观测、提交的 VLM 返回结果、依据证据得出的结果、像素/世界坐标对齐检查、CADPlan 试运行，以及零问题几何验证。

从一张图像复制机械图纸

完整流程将非修改性理解与唯一明确授权的 DWG 修改阶段分开，最后以重新扫描和视觉差异对比收尾。 本 README 不会把生成的流程示意图作为追踪证据；实际运行应保留源栅格图像、ImageDrawingSpec、已验证且经过试运行的 CADPlan、生成的 DWG，以及最终的 AutoCAD 导出文件。

典型的描摹循环如下：

1. 调用 prepare_image_trace(image_path, domain="mechanical")；
2. 使用 prepare_visual_semantic_context 和 get_trace_source_image 检查全局源图像和分块源图像；
3. 生成 ImageDrawingSpec/v1，并回显每张已观察图像的 source_ref_template，用于测量坐标；
4. 调用 validate_image_drawing_spec，然后调用 submit_image_drawing_spec；
5. 调用 compile_image_spec_to_cad_plan；
6. 调用 validate_image_fidelity_contract(spec, cad_plan)；
7. 调用 validate_cad_plan，然后调用 dry_run_cad_plan；
8. 获得授权后，才调用 execute_cad_plan(..., allow_modify=true, transactional=true)；
9. 重新扫描并验证，然后将最终的 AutoCAD 导出文件与源图像进行比较。

不要仅仅因为追踪 JSON 有效就执行追踪。应先检查视图数量、对称性、尺寸、中心线、孔位，以及源图像与渲染结果的保真度。

v1.6 中的视觉定位

v1.6 版新增了图纸级拓扑，可描述由多个实体组成的边界，包括线线交点、受支持的线曲线交点，以及闭合环形轮廓。需要获取图元关系时，请使用 scan_all_entities(topology_detail="full")。定位功能现在包含真实路径／多边形几何、多个句柄候选项、自适应叠加层，以及支持分块的像素／世界坐标契约。

这提升了机械轮廓的选择质量，但视觉识别并非万无一失。重要编辑仍应遵循：

visual finding -> grounding candidates -> explain_entity -> handle-targeted edit

默认的 VLM 审查提示词为 vlm_review_drawing/v3。工具结果会返回快照架构版本；叠加层架构版本则存储在引用的旁车文件中，以便严格的使用方检测契约变更。

安全模型

• 编辑现有图纸前，先读取并扫描。
• 将原始命令执行、删除、清理、审计、保存、关闭和 execute_cad_plan 限制在客户端明确批准后执行。
• 修改前验证计划并进行试运行。
• 使用返回的句柄和结构化几何来精确定位目标。
• 修改后重新扫描；不要依赖过时的 SQLite 行。
• 将模型私有备注和空间注释保存在 .cad_mcp/ 中，不要放入可见的 DWG 几何、XData 或隐藏图层。
• 将保存和关闭视为需要操作人员分别决定的操作。
• 将顶视／平面模型空间视图视为最可靠的定位情形。视图扭转、自定义 UCS、3D 几何和复杂的布局视口都可能降低置信度。

事务和回滚支持可以降低风险，但无法保证从所有 AutoCAD 或 COM 故障中恢复。图纸价值较高时，请使用副本。

已知限制

• 视图定位仅对平面／顶部模型空间视图精确。 未旋转的平面视图可提供数值稳定的世界坐标↔像素映射。视图旋转会纳入计算并标记；对于非平面视图和 3D 视图，会回退到 2D 平面视图近似，并将 transform_confidence=low，同时给出明确警告；尚未完全支持图纸空间／布局视口映射。在这些情况下，应保留返回的 limitations 和置信度，不要声称定位精确。
• 栅格叠加层需要 [visual] extra。 如果没有 Pillow/cairosvg，叠加层会降级为 SVG 回退方案，并显示警告；WMF 导出依赖原生 Windows GDI+ 转换路径。
• 尺寸绑定采用启发式方法。 尺寸会根据证据和置信度与候选几何图形匹配；有歧义或未绑定的尺寸会按设计保留为 unknown，绝不会被误报为已满足。
• 语义检测是确定性的，且基于规则。 对于更复杂的对象（槽、螺栓圆周阵列、墙、门、导线、标题栏、BOM 表格），系统会将其报告为带置信度的候选项，而非保证分类准确；服务内不会运行外部模型。
• CADPlan 执行固定的一组操作。 高级 3D 实体、布尔运算、修剪／延伸、布局编辑、打印和保存／打开不属于平面操作；这些操作请使用直接的 MCP 工具。
• 回滚尽力而为。 事务执行使用 AutoCAD 撤销标记（StartUndoMark/EndUndoMark + undo）；无法保证从所有 COM 或 AutoCAD 故障中恢复，且计划执行失败时总会报告 completed_steps 以供检查。
• 扫描范围有限。 scan_all_entities 遵循 max_entities 限制；如果图纸超出上限，会报告 truncated。大型图纸上使用 topology_detail="full" 开销很大，因此默认应使用摘要拓扑。
• 图像描摹取决于 Agent 端的 VLM 和校准。 服务负责准备、验证、编译并确保保真度；它不会调用模型提供方。如果尺寸校准不可靠，描摹的图纸会带有比例警告，不得声称其具有真实的工程比例。
• 仅支持 Windows + AutoCAD COM。 工具调用会在单个 COM 线程上串行执行；服务必须与 AutoCAD 运行在同一 Windows 账户下；托管 CI 无法测试实时 COM 路径——实时冒烟基准测试需在本地通过 scripts/verify_cad_understanding_workflow.py 运行。

工作区和数据

CAD_MCP_WORKSPACE_ROOT 控制 <workspace>/.cad_mcp/workspace.db。默认日志、可视化导出文件和图像描摹资源会相对于 MCP 进程的 cwd 写入，路径分别为 cad_mcp.log、 cad_visual_exports/ 和 cad_image_traces/。

外部 CAD 项目不会自动忽略。如果项目使用 Git，请将以下条目添加到项目的 .gitignore 中：

.cad_mcp/
cad_mcp.log
cad_visual_exports/
cad_image_traces/

数据库有助于关联各轮交互和工具，但 AutoCAD 仍是权威来源。如果图纸在服务外发生更改，请在使用已存储的实体前重新扫描。关于旧版根目录 autocad_data.db 的警告表示存在较旧的数据库；请验证迁移情况，然后单独归档。

故障排查

查看机器可读的诊断信息：

cad-mcp-doctor --json

开发

git clone https://github.com/LokmenoWer/best-cad-mcp.git
cd best-cad-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev,visual]"
python -m pytest -q -m "not autocad_com"

发布时会验证版本、运行非 COM 测试套件（将 autocad_com 标记留作本地实时 CAD 检查），验证原生新版和旧版 MCP stdio，构建并全新安装 wheel，使用 Twine 检查，通过 PyPI 发布，随后发布 MCP 服务元数据。实时 AutoCAD 发布前检查和 CADPlan 检查必须在本地运行，因为托管运行器没有 AutoCAD。

欢迎贡献。请让修改范围保持明确，为行为变更添加回归测试，并遵循 scan → plan → validate → verify 安全模型。

进行模型比较时，请使用 Agent 循环实验指南，固定图形、源代码、技能和提示词，并记录经过独立审核的实时运行。离线台账会将待定结果保留为未知，不会将合成的落地测试或确定性的演示计划视为模型评估。

致谢

模型私有的标注和指针式 CAD 上下文设计参考了公开的 Pointer-CAD 项目及其论文。本仓库未复制任何 Pointer-CAD 源代码。

许可证

MIT。请参阅 LICENSE。