build123d-mcp

一个 MCP（模型上下文协议）服务器，将 build123d CAD 操作公开为工具，使 AI 助手能够以交互方式构建、检查和迭代 3D 几何体。

为什么使用它

当使用 AI 编写 build123d 脚本时，AI 是“盲写”的——它无法看到自己生成的几何体。该服务器闭合了反馈循环：AI 可以增量地创建几何体、渲染视图、查询尺寸并捕获错误，而不是编写完整的脚本并祈祷它们是正确的。

Related MCP server: 3D MCP Server

工具

• execute — 在持久会话中运行 build123d Python 代码；使用 show(shape, name) 注册命名部件

• render_view — 将一个或多个形状渲染为 PNG 或 SVG；支持装配体合成、高质量细分和横截面裁剪平面

• measure — 查询边界框、体积、表面积、拓扑结构、最小壁厚或两个命名实体之间的间隙

• export — 在一次调用中导出为 STEP、STL 或两者；针对命名对象或当前形状

• session_state — 活动形状、命名对象和快照名称的完整 JSON 快照

• health_check — 在开始工作前验证 VTK/SVG/STEP/STL 依赖项是否端到端正常工作

• save_snapshot / restore_snapshot / diff_snapshot — 对几何状态进行检查点设置、恢复和比较

• interference — 检查两个命名形状之间的相交体积

• list_objects — 列出所有带有几何统计信息的命名形状

• version — 返回服务器版本

• reset — 将会话重置为空状态

请参阅 llms.md 获取完整的工具参考和使用模式。

要求

• uv

• 兼容 MCP 的客户端（Claude Code、Claude Desktop、Cursor 等）

所有 Python 依赖项（build123d、vtk 等）均由 uv 自动安装。

安装

无需克隆。直接从 PyPI 安装：

pip install build123d-mcp

或者直接使用 uv tool run — 它可以在无需预先安装的情况下一步获取并运行包（见下文）。

添加到 MCP 客户端

服务器通过 stdio 运行 — 客户端使用 uv tool run build123d-mcp 将其作为子进程启动。

关于 Python 版本的说明。 下面的所有示例都传递了 --python 3.12。VTK 和 cadquery-ocp 尚未发布适用于 Python 3.13+ 的 wheel，因此必须固定为 3.12。如果您还没有 Python 3.12，uv 将自动下载一个托管的 Python 3.12。

Claude Code

添加到项目的 .mcp.json（或全局使用的 ~/.claude/mcp.json）：

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

编辑后重启 Claude Code。连接后工具会自动出现。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

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

保存后重启 Claude Desktop。

Cursor

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

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

VS Code (GitHub Copilot / Continue)

对于 Continue 扩展，添加到 .continue/config.json：

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

对于支持 MCP 的 GitHub Copilot，添加到工作区中的 .vscode/mcp.json：

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

系统提示词

为获得最佳效果，请将 default_prompt.md 的内容作为系统提示词粘贴到您的 AI 客户端中。这会告诉助手以增量方式工作，在每一步之后验证几何体，并按正确的顺序使用工具。

状态

活跃开发中 (v0.1.0)。