build123d MCP

build123d-mcp

为你的 AI 提供 CAD 视觉能力。

build123d-mcp 不是独立的聊天机器人或 CAD 程序，而是一个可供 AI/大模型应用通过 MCP 使用的 CAD 工具箱。

借助 Claude、Cursor、VS Code、Continue、Cline 或 Codex CLI 等大模型应用，build123d-mcp 可让助手创建 build123d CAD 模型、渲染预览、测量几何体、修正错误，并导出 STEP、STL、SVG 和 DXF 等文件。助手无需盲目地编写完整 CAD 脚本，而是可以分小步构建零件，并在过程中检查结果。

在 2026 年 6 月的公开 CADGenBench 排行榜上，使用 build123d-mcp 后，同一模型的得分从 0.360 提升至 0.457，CAD 有效性也从 88% 提升至 100%。

选择你的配置

大多数用户应从本地 MCP 服务配置开始：

• 你在自己的机器上使用 Claude、Cursor、VS Code、Continue、Cline 或 Codex CLI。
• 你的 AI 应用会将 build123d-mcp 作为本地子进程启动。
• 你无需克隆此仓库。

如果你想在浏览器中试用，或使用已预装 Copilot Chat、Python、uv 和 CAD 依赖项的现成开发工作区，请改用 GitHub Codespaces。

仅在需要自行托管 MCP 服务的高级部署场景中使用 HTTP 模式。

快速入门

你需要：

• uv
• 支持 MCP 的 AI/大模型应用，例如 Claude Code、Claude Desktop、Cursor、VS Code、Continue、Cline 或 Codex CLI

正常使用时无需克隆仓库。首先检查软件包能否启动：

uv tool run --python 3.12 build123d-mcp@latest --version

然后将相同的命令添加到 AI 应用的 MCP 配置中。通用配置项如下：

command: uv
args:    ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]

支持 Python 3.11、3.12、3.13 和 3.14。示例使用 3.12，因为它是较为稳妥的默认版本；如果尚未安装，uv 可以下载该版本。

连接到你的 AI 应用

组成部分如下：

• 大模型应用是你与助手聊天的地方。
• MCP 是让助手调用工具的连接方式。
• build123d-mcp 是助手调用的 CAD 工具服务。

服务通常通过 stdio 运行。AI 应用需要使用 CAD 工具时，会将其作为本地子进程启动。

Claude Code

将以下内容添加到项目的 .mcp.json，或添加到 ~/.claude/mcp.json 以供全局使用：

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]
    }
  }
}

编辑后重启 Claude Code。

Claude Desktop

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，或在 Windows 上编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]
    }
  }
}

保存后重启 Claude Desktop。

Cursor

打开 Settings -> MCP 并添加新的服务条目，或编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]
    }
  }
}

VS Code、Continue、Cline、Codex CLI

在 AI 应用或扩展读取的 MCP 配置中使用相同的命令和参数。具体文件名因应用而异，但服务命令相同：

command: uv
args:    ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]

对于 VS Code 中的 GitHub Copilot MCP 支持，此仓库为开发检出和 Codespaces 提供了 .vscode/mcp.json。其他工作区的配置如下：

{
  "servers": {
    "build123d-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]
    }
  }
}

首次测试提示词

AI 应用连接到服务后，向助手提出一个具体问题：

Use build123d-mcp to make a 60 mm x 40 mm x 6 mm mounting plate with two
5 mm through holes 40 mm apart. Render it, measure it, then export STEP and STL.

实用的工作循环如下：

1. 一次构建一个功能。
2. 在重要步骤后进行渲染或测量。
3. 导出前进行验证。
4. 导出最终零件。

如果出现问题，请让助手检查 last_error，修复脚本，然后尝试下一个更小的步骤。

编辑导入的零件

导入 STEP 并建立有效基线后，使用 find_candidates(kind="hole", qualifiers='{"axis":"Z","side":"+X"}', stated_value=6) 列出所有已识别的候选项，并检查零件的字面坐标轴以及请求坐标系的每种适当旋转（按其选中的候选项分组）。interface_features() 会建议带孔的平面；选择要保护的孔句柄。对于普通通孔，edit_feature(handle, diameter=8, protected_refs='["@feature[...]"]') 会调整孔径，并报告预测和测得的增加或移除体积。只有孔、其他已识别的孔以及外包络均通过检查后，才会登记结果。对于带沉孔、锪面、埋头孔或由多个面构成的孔，将拒绝编辑；请在 execute() 中编辑，并使用 compare(kind="shape") 和 STEP 导出关卡进行验证。

好的提示词通常会要求助手明确使用 MCP 工具，并在导出前验证结果。例如：

Use build123d-mcp. Build this incrementally, render after the main features,
measure the final dimensions, run validate(), and export STEP if it passes.

在 GitHub Codespaces 中使用 Copilot 试用

你也可以通过 GitHub Codespaces 在浏览器中运行此项目：

在 GitHub Codespaces 中打开

对于初学者来说，这是最接近“GitHub 托管的大模型 + MCP”的方式：

• GitHub Codespaces 为你提供浏览器中的 VS Code。
• GitHub Copilot Chat 为你提供大模型助手。
• build123d-mcp 在 codespace 中作为 MCP CAD 工具服务运行。

使用大模型功能需要有 GitHub Copilot 访问权限。codespace 本身会提供一个临时工作区，其中已检出此项目，并安装了所需的 Python/CAD 依赖项。以下情况适合使用它：

• 无需更改笔记本电脑的设置即可试用此项目
• 在贡献代码前运行测试
• 在同一个浏览器工作区中同时使用 Copilot Chat 和 build123d-mcp

GitHub 的文档介绍了：

• 在 Codespaces 中使用 Copilot
• 使用 MCP 扩展 Copilot Chat

此代码库包含一个开发容器，其中安装了 Python 3.12、uv 和无头渲染所需的 Linux 显示软件包。它还会安装 GitHub Copilot VS Code 扩展，并在 .vscode/mcp.json 中包含工作区 MCP 配置。

codespace 打开时，会运行：

uv sync --all-groups

检查开发环境安装：

uv run build123d-mcp --version
uv run pytest

要将 Copilot 与本地 CAD 服务配合使用：

1. 打开 codespace。
2. 等待设置完成。
3. 打开 Copilot Chat 并选择 Agent 模式。
4. 打开 .vscode/mcp.json，如果 VS Code 尚未启动 build123d-mcp 服务，则手动启动。
5. 使用上一节中的第一个测试提示词提问。

Codespaces 的 MCP 配置指向本地检出目录，而不是 PyPI 软件包：

{
  "servers": {
    "build123d-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "build123d-mcp"]
    }
  }
}

Codespaces 非常适合试用此项目、贡献代码，或在一个远程环境中使用 GitHub Copilot 和 build123d-mcp。若要在自己的计算机上使用桌面 AI 应用，常规的 uv tool run ... build123d-mcp@latest 配置更简单，因为这些应用需要在本地启动 MCP 服务。

功能

build123d-mcp 为助手提供以下工具：

• 在持久化 CAD 会话中执行 build123d 代码
• 渲染 PNG、SVG 和 DXF 预览
• 测量体积、面积、边界框、拓扑和质心
• 查找孔、凸台、沉头孔和孔阵列
• 检查可打印性、配合/对齐情况，以及导出有效性
• 导入 STEP/STL 文件进行比较
• 导出 STEP、STL、DXF、SVG，或一次导出多种格式
• 保存和恢复会话快照
• 生成 2D 工程图预览

完整的工具和资源参考请参阅 llms.md。

给助手的指导

此服务包含工作流指导，可帮助助手正确使用 CAD 流程。这对会读取项目指导文件的编码 Agent 尤其有用。

连接服务后，请让助手为所需工作流调用 install_skill：

install_skill(target="agents-md", skill="modeling")
install_skill(target="agents-md", skill="drawing")
install_skill(target="agents-md", skill="repair")

install_skill 还支持 target="claude"、"cursor" 和 "windsurf"。3D 零件请使用 skill="modeling"，工程图请使用 skill="drawing"，实体未通过验证时请使用 skill="repair"。

你也可以将 default_prompt.md 粘贴到 AI 应用中，作为系统提示词。

开发环境设置

本地开发：

git clone https://github.com/pzfreo/build123d-mcp.git
cd build123d-mcp
uv sync --all-groups
uv run build123d-mcp --version
uv run pytest

要在 AI 应用中运行此检出目录中的服务，请使用：

command: uv
args:    ["run", "build123d-mcp"]

贡献指南请参阅 CONTRIBUTING.md。

高级用法

默认的 stdio 传输会为每个应用进程创建独立的会话。 Web、容器或远程部署可使用 HTTP 模式：

uv tool run --python 3.12 "build123d-mcp[http]@latest" \
  --transport http --host 127.0.0.1 --port 8000

支持 HTTP 的应用随后连接到：

http://localhost:8000/mcp

HTTP 模式没有内置身份验证，且使用一个共享的 CAD 会话，除非主机提供按请求区分的会话中间件。请勿直接向多个用户开放此模式。

其他高级主题：

• 安全模型和沙箱：security.md
• 完整工具参考：llms.md
• 实时会话查看器：docs/live-viewer.md
• 更新日志：CHANGELOG.md

状态

正在积极开发。