CADCraft MCP：AI 辅助 CAD 实用指南

01 / 定义

CADCraft MCP 是什么？

CADCraft MCP 是 CADCraft 命令行工具提供的本地 MCP 服务端。它无需单独下载，也不是托管服务或云端 API，而是将用于文件转换的同一个 cadcraft-cli 程序启动为支持模型上下文协议（Model Context Protocol）的服务端。

MCP 是 AI 智能体发现并调用其他程序工具的协议。CADCraft 通过它将命令输入、实体查询、预览渲染和图纸保存等 CAD 操作开放为可调用工具。Claude Code、Claude Desktop、Cursor 等支持 MCP 的客户端可以据此操作图纸。

在这个流程中，你用文字描述零件，智能体将需求转换成 CAD 命令，检查实际绘制的图形、渲染预览，再写入文件。官方 MCP 指南介绍客户端配置、工具参数和示例会话；docs/control-protocol.md介绍桌面应用提供的 JSON 控制通道。

它提供哪些 MCP 工具？

官方 MCP 指南和工具参数定义介绍了以下操作。界面工具需要连接桌面应用；绘图和文件操作也可在无窗口模式中使用。

请以客户端从已安装服务端发现的 MCP 工具参数定义为准。在会话内，list_commands 返回的是 CAD 命令目录，与 MCP 工具列表不同。参数定义可查阅官方工具源码。

02 / 客户端配置

连接 MCP 客户端

从官方下载页面获取适合你系统的 CLI，或按仓库说明自行构建。请使用与已安装版本对应的文档。

服务端有两种运行方式，可用工具有所不同。无窗口模式配置较简单，适合多数自动化场景；连接桌面应用则可以让你看到智能体正在操作的图纸。

无窗口模式：最小配置

cadcraft-cli mcp

这条命令通过 stdio 启动 MCP 服务端。对于负责启动 stdio 服务端的客户端，配置需要指定可执行程序及启动参数。CADCraft 对应的程序是 cadcraft-cli，参数是 mcp。

官方 MCP 指南提供了以下 Claude Code / Claude Desktop 配置示例。其他客户端的配置字段和文件位置可能不同，请遵循其各自的 MCP 配置文档。

{
  "mcpServers": {
    "cadcraft": {
      "command": "cadcraft-cli",
      "args": ["mcp"]
    }
  }
}

如果 cadcraft-cli 不在 PATH 中，请将 command 改为下载的可执行程序的完整路径。

桌面连接模式：操作正在运行的应用

如果希望智能体查看并点击应用，请先启动桌面程序并开放控制端口，再将 CLI 连接到该地址：

# Terminal 1: launch the desktop app with its control channel
cadcraft --control 7979

# Terminal 2: attach the MCP server to that session
cadcraft-cli mcp --connect 127.0.0.1:7979

这是 docs/mcp.md 中记录的启动方式。如果程序不在 PATH 中，请使用实际安装路径。桌面会话中应保持需要编辑的图纸为当前活动图纸。

此模式可以使用 screenshot、ui_inspect 和 ui_click。未启用延迟连接选项时，若无法访问应用，服务端启动会失败。缺少 --connect 地址也会报错，不会自动切换到另一个独立的无窗口图纸会话。

客户端早于桌面应用启动时

本次核对的文档介绍了 --lazy：将连接推迟到第一次工具调用；以及 --launch：在 macOS 上，当工具调用发现应用未运行时启动桌面应用。应用响应前，调用会失败并返回提示。官方 macOS 启动配置如下：

{
  "mcpServers": {
    "cadcraft": {
      "command": "cadcraft-cli",
      "args": ["mcp", "--connect", "127.0.0.1:7979", "--launch"]
    }
  }
}

这些选项来自上方链接的仓库快照。添加选项前，请确认你已安装的版本支持它们。

cadcraft-cli run --sample --script 'CIRCLE 22,3 1
' \
  --save out.dxf --export out.png

cadcraft-cli info drawing.dxf
cadcraft-cli convert drawing.dxf drawing.svg
cadcraft-cli commands    # list the commands this build supports

03 / 基本流程

绘图、检查、渲染、保存

让图纸始终处于同一个 MCP 会话中：创建几何、读取检查、渲染预览，最后保存该图纸。单独启动的 CLI 进程拥有自己的会话，不会自动保存智能体当前正在操作的图纸。

不要跳过第 3 步。inspect_drawing 和 query_entities 可读取图纸并与需求进行对照。命令没有报错，并不证明几何已经绘制在预期位置。

编辑已有 DXF

打开工作副本，查询实体，并在编辑时使用返回的句柄。官方工具定义记录了 move 的 handles 和 delta 参数。下方示例句柄 10A 来自该来源；调用前，请将其替换为查询结果中目标实体的真实句柄。

open {"path":"/absolute/path/input-copy.dxf"}
query_entities {"type":"Circle","limit":10}
list_commands {"filter":"move"}
execute {"command":"move","params":{"handles":["10A"],"delta":[5,0]}}
inspect_drawing {"entities":true,"limit":100}
render {"fit":true}
save {"path":"/absolute/path/edited-copy.dxf"}

这是依据文档整理的编辑方式，尚未执行测试。替换原始图纸前，请检查几何，并在目标应用中重新打开保存的副本。

CADCraft 可以读写哪些文件？

智能体的输出最终需要采用你实际可用的格式。产品页列出了较广的 DXF 支持范围；仓库中的格式指南则记录了随版本变化的具体限制。请同时核对发行版本和目标文件格式。

能够打开图纸，不代表保存时能完整保留内容。部分实体和自定义数据可能丢失或变化。本次核对的快照记录了对部分未知 DXF 原始记录的保留，而 DWG 转换还会丢失更多数据。格式指南记录了这些限制；较早的 v0.5.0 指南有不同约束。依赖文件往返兼容性前，请先在目标应用中测试自己的文件。

04 / 示例工作流

一个 2D 零件：从需求到保存 DXF

零件需求

绘制一块 100 × 60 mm 的简单矩形安装板，采用直角边，带四个 Ø6 mm 孔。孔中心分别为 (10, 10)、(90, 10)、(10, 50) 和 (90, 50)。使用公制图纸，包含 OUTLINE 和 HOLES 图层。标注 100 mm 宽度，渲染供审阅并保存 DXF。

智能体如何处理需求

为示例启动一个新的无窗口会话。如果使用桌面连接模式，new_drawing 会改变当前桌面图纸，请先保存正在进行的工作。智能体应通过 list_commands 查询命令参数，然后创建公制图纸和轮廓图层：

list_commands {"filter":"layer.new"}
list_commands {"filter":"circle"}
new_drawing {"metric":true}
execute {"command":"layer.new","params":{"name":"OUTLINE","color":"red","current":true}}
command_line {"text":"rectang 0,0 100,60"}
command_line {"text":"dimlinear 0,0 100,0 50,-8"}

创建并设定当前孔图层，然后使用文档中的结构化圆命令，在每个指定中心创建半径为 3 个绘图单位的圆。图层命令定义和圆参数来自官方工具源码；尺寸与坐标则按本示例零件需求调整。

execute {"command":"layer.new","params":{"name":"HOLES","color":"red","current":true}}
execute {"command":"circle","params":{"center":[10,10],"radius":3}}
execute {"command":"circle","params":{"center":[90,10],"radius":3}}
execute {"command":"circle","params":{"center":[10,50],"radius":3}}
execute {"command":"circle","params":{"center":[90,50],"radius":3}}

这里约定 1 个绘图单位代表 1 mm。请在图纸数据及下游 CAD 应用中核实单位，不能仅凭公制模板就认定比例正确。此示例使用直角边，未演示圆角、加工公差，也不证明结果可以直接用于制造。

读取图纸并检查：轮廓尺寸是否为 100 × 60 个单位，宽度标注是否存在，两个图层是否都存在，以及孔查询是否返回位于指定中心、半径为 3 的四个圆。以下是预期检查项，并非实际观察结果：

inspect_drawing {"entities":true,"limit":100}
query_entities {"type":"Circle","layer":"HOLES","limit":10}
query_entities {"layer":"OUTLINE","limit":20}

确认几何后，智能体渲染预览供人工审阅，再进行保存。render 是官方记录的 MCP 工具，返回 PNG：

render {"width":1200,"height":800,"fit":true}

审阅后，在同一会话内使用 save 工具。请将示例路径改为服务端所在机器上的绝对路径，并确保可写。保存 PNG 是导出预览；保存 DXF 才是写入可编辑图纸。

save {"path":"/absolute/path/plate.dxf"}
save {"path":"/absolute/path/plate.png"}
open {"path":"/absolute/path/plate.dxf"}
inspect_drawing {"entities":true,"limit":100}
query_entities {"type":"Circle","layer":"HOLES","limit":10}

将重新打开的图纸与上述检查项对照，再在目标工作流中打开 DXF，确认单位、尺寸、图层和几何。记录 CADCraft 版本、输出 DXF 版本和测试日期后，才能评估这个流程是否可重复使用。

处理错误后再继续

官方文档规定：无效工具参数返回 JSON-RPC -32602；工具执行失败则返回 isError: true。遇到任一情况都应停止后续操作，检查当前图纸并修正原因后再重试。即使工具返回成功，仍需几何检查和人工审阅。

我们尚未运行此示例，因此没有提供由 CADCraft 生成的输出文件。它不证明尺寸和图层在保存后会保留，也不证明其他 CAD 应用能正确读取结果。下方可选测试文件是独立的文件保真度测试输入，不是此安装板示例的输出。

该文件是原创 DXF 2018 测试图纸，包含轮廓、文字、已渲染的尺寸、五个命名图层、块引用和 ANSI31 填充。它使用 ezdxf 独立制作，以 CC0-1.0 许可发布，不含客户图纸或第三方图片。你可以用它检查当前 CADCraft 版本能否打开、编辑和保存已知图纸。制作测试文件本身不等于完成 CADCraft 实测，我们没有声称任何往返测试结果。

05 / 浏览器集成

AI 二维生成如何连接 CADCraft

浏览器集成已经可用。CAD DESIGN X 将提示词转换为受约束的结构化几何，完成校验并导出 R12 DXF，再通过同源宿主桥接将文件传给嵌入的 CADCraft 编辑器。

这条链路不使用 CADCraft MCP。生成的 DXF 会自动在 Web 编辑器中打开，你可以检查和修改实体，再使用 CADCraft 的保存命令下载编辑后的文件。

用于生产前，请务必检查尺寸，并在下游应用中重新打开导出的 DXF。下方待验证事项针对更深入的 MCP 和文件保真度，不影响当前浏览器文件交接。

06 / 待验证事项

需要先验证什么？

发布可复现的集成教程前，需要为以下每个问题取得验证依据。

1. 生成服务是否提供 API？

   确认是否存在可调用接口、需要何种认证，以及返回图片、几何还是文件。现有浏览器生成器并不能证明已具备供 MCP 使用的 API 约定。

2. 输出能否进入 CADCraft 支持的文件工作流？

   概念图不是可编辑 DXF 几何。需要确认生成服务能否返回几何，或是否需要转换步骤，再在已安装 CADCraft 版本中验证生成的格式。

3. 尺寸与图层结构是否保留？

   只有几何还不等于完整图纸。单位、图层名称、尺寸对象和块引用需要在交接后保留，避免下游编辑继承信息损失。

4. 步骤失败时如何处理？

   官方 MCP 文档区分无效参数和以 isError: true 返回的工具执行失败。集成需要处理两者，检查部分结果，并明确何时重试或回滚。

5. 验证了哪个 CADCraft 构建和版本？

   测试结果需要对应具体版本才有意义。ArtCraft 标注 CADCraft 为“开发中”，未经测试的发布说明不能充当验证依据。

在这些问题都有对应 CADCraft 版本和日期的验证记录前，CAD DESIGN X 连接仍属于计划。验证完成后，本页才会提供真正的集成教程和经过验证的命令及配置。

07 / 常见问题与依据

CADCraft MCP 常见问题

以下回答依据官方 MCP 指南、控制协议文档和 ArtCraft 产品页，核对日期为 2026 年 10 月 14 日。它们描述文档记录的行为，不是本站实测结果。