OpenSCAD MCP Server

OpenSCAD MCP 服务

本地 MCP 服务，可将 OpenSCAD 源码或明确的基本体尺寸转换为可编辑的 SCAD、STL 几何体和四张 PNG 预览图。连接的助手可以编写复杂设计所需的 SCAD；本服务会使用已安装的 OpenSCAD 可执行文件编译并渲染。

**状态：**受支持的实现位于 src/openscad_mcp。此前的图像生成、CUDA 重建、远程处理和打印机代码已归档在 legacy/ 中。这部分尚未完成，不属于已安装的服务。请参阅审计和机器测试结果。

安装

需要 Python 3.11+ 和 OpenSCAD。无需 API 密钥、CUDA、Open3D 或单独的图像渲染器。

使用官方下载页面安装 OpenSCAD。在 macOS 上，可通过以下方式获取当前原生 Apple Silicon/Intel 版本：

brew install --cask openscad@snapshot
openscad --version

在 Debian/Ubuntu 上，sudo apt-get install openscad 会安装发行版软件包。Linux PNG 渲染可能需要 X 显示；在无头机器上运行服务或测试时，请使用 xvfb-run -a。Windows 用户可以将 OPENSCAD_EXECUTABLE 设置为 openscad.exe 的完整路径。

git clone https://github.com/jhacksman/OpenSCAD-MCP-Server.git
cd OpenSCAD-MCP-Server
uv sync --locked
uv run openscad-mcp --help

或者，使用 python -m pip install . 安装到虚拟环境中，然后运行 openscad-mcp。requirements.txt 会安装同一个软件包。uv.lock 固定了经过测试的依赖解析结果；项目元数据允许兼容更新。

在无法创建符号链接的外部文件系统上，请将环境放在内部磁盘：

export UV_PROJECT_ENVIRONMENT="$HOME/.cache/openscad-mcp-venv"
uv sync --locked

Docker 和 Jetson

根目录中的 Dockerfile 提供无头 stdio 镜像。有关构建命令、MCP 客户端配置、持久化模型存储和 Glama 列表要求，请参阅 Docker 设置和验证。该镜像不需要 GPU。

关于 issue #19 中的硬件问题，请参阅 Jetson Orin Nano 和 CUDA。受支持的服务不使用 CUDA；Docker 支持不会恢复已归档的重建原型。

连接 MCP 客户端

默认使用 stdio。配置客户端以启动服务进程，并使用绝对路径：

{
  "mcpServers": {
    "openscad": {
      "command": "/absolute/path/to/venv/bin/openscad-mcp",
      "args": ["--output-dir", "/absolute/path/to/models"]
    }
  }
}

对于支持 Streamable HTTP 的客户端：

uv run openscad-mcp --transport http --port 8000

MCP 端点为 http://127.0.0.1:8000/mcp。/ 提供服务信息；/health 报告 OpenSCAD 版本和基本体默认值。HTTP 还会提供预览页面和下载文件。使用 stdio 模式时，请使用返回的绝对文件路径或 get_model_preview；此模式不会启动 HTTP 监听器。

工具

工具	用途
get_capabilities	OpenSCAD 版本和支持的基本体及其默认参数
create_3d_model	使用 model_type 和 parameters 创建基本体，或通过有限的描述创建
create_model_from_scad	编译可信的 scad_code，创建自定义 3D 模型
modify_3d_model	更改基本体参数或替换模型的 scad_code
get_model	读取已保存的模型及其工件路径
get_model_source	读取已保存的 SCAD 源码及其修订版本，包括在 Docker 内读取
get_model_preview	将 PNG 图像作为 MCP 图像内容返回
export_model	导出 scad、stl、csg 或 3mf

create_3d_model 的示例参数：

{
  "model_type": "box",
  "parameters": {"width": 40, "depth": 30, "height": 20, "thickness": 2}
}

尺寸单位为毫米。支持的类型：cube（也包括长方体）、sphere、cylinder、box（开口空心盒）、rounded_box（实心）、tube、cone、torus、prism（直角三角形截面）、hexagonal_prism 和 text。调用 get_capabilities 可查看每种类型的确切参数名称。环面使用管截面中心到圆心的半径（major_radius）和管截面半径（minor_radius）。

可选的描述解析器可识别命名尺寸，例如 hollow box width 40 mm depth 30 mm height 20 mm thickness 2 mm 或 cube 2 cm wide 1 inch high。支持 mm、cm、m 和英寸；未注明单位时默认为 mm。这是一个小型解析器，并非通用自然语言模型。未指定的尺寸使用返回的默认值。要获得精确结果，请优先使用显式参数。对于任意物体，可让助手编写自包含的 SCAD，并调用 create_model_from_scad。

{
  "scad_code": "difference() { cube([40,30,8]); translate([20,15,-1]) cylinder(h=10,r=5,$fn=48); }",
  "description": "Mounting plate with a through hole"
}

修改基本体：

{"model_id": "ID_FROM_CREATION", "parameters": {"height": 25}}

对于自定义模型，调用 get_model_source 并传入模型 ID，通过 MCP 直接获取 scad_code 和 revision。编辑返回的源码，然后调用 modify_3d_model，传入新的 scad_code，并将 expected_revision 设为读取到的修订版本。无需访问服务端文件系统即可读取源码。

对基本体参数进行编辑时，也可使用相同的可选修订版本检查：

{
  "model_id": "ID_FROM_CREATION",
  "parameters": {"height": 25},
  "expected_revision": "REVISION_FROM_GET_MODEL"
}

如果另一项编辑已提交，该操作会在渲染或更改文件之前失败。MCP 会报告工具错误；HTTP /tool_call API 会返回带有 current_revision 的 409。读取最新源码/参数，并纳入期间发生的更改后再重试。省略 expected_revision 则会保留原有的无条件编辑行为。

只有 SCAD 会保留可编辑的源参数。CSG 是经过求值的几何树。STL 和 3MF 是网格，不会保留设计的参数化关系。不提供 AMF（当前 OpenSCAD 版本已移除）、STEP、OBJ、2D 导出、图像重建和打印功能。

HTTP 冒烟测试

HTTP 服务运行时：

curl --fail http://127.0.0.1:8000/tool_call \
  -H 'Content-Type: application/json' \
  -d '{"tool_name":"create_3d_model","tool_params":{"model_type":"box","parameters":{"width":40,"depth":30,"height":20,"thickness":2}}}'

在同一服务上打开返回的 preview_url。下载 /download/MODEL_ID?format=stl 或 ?format=scad。/tool_call 是便捷的 JSON API，与 /mcp 上实际的 MCP 协议相互独立。此 API 通过 /preview/VIEW/MODEL_ID 获取图像。

行为和限制

• 仅当成功生成真实的 STL 文件和全部 4 个 PNG 文件后，创建才算成功。渲染器故障、输出为空以及 OpenSCAD 警告或错误都会报告为失败；不会替换为占位几何体或预览图。
• 编辑会创建新版本，并且仅在渲染成功后更新清单。较早的版本会保留在磁盘上。服务器重启后模型仍会保留。
• 默认存储路径为 ~/.local/share/openscad-mcp/models。可通过 --output-dir 或 OPENSCAD_OUTPUT_DIR 覆盖。每个渲染子进程的超时时间为 120 秒，可通过 --timeout 配置。一个模型需要启动 5 个子进程，因此整个请求可能耗时更久。
• 每个输出目录仅运行一个服务器进程。渲染和编辑会按顺序执行。没有自动磁盘清理、分布式作业队列或多进程存储协调机制。
• 这是一个受信任的本地工具。自定义 SCAD 会以当前用户的文件访问权限执行，包括 OpenSCAD 的 import、include 和 use；它并未经过沙箱隔离。HTTP 仅绑定到环回地址，并拒绝非本地的 Host/Origin 标头。它没有身份验证机制，也不支持公开或局域网部署。
• 已在 macOS arm64 本地环境和 Ubuntu 24.04 CI 的 Xvfb 下进行测试。Windows 以及其他平台和显示配置尚未验证。未使用硬件打印机或远程 GPU 进行测试。

开发和验证

uv sync --locked --group dev
uv run ruff check src/openscad_mcp tests scripts
uv run ruff format --check src/openscad_mcp tests scripts
uv run pytest -q

完整测试套件需要 OpenSCAD；如果无法使用 OpenSCAD，测试将失败。测试会启动真实的 stdio 和 HTTP 服务器进程，使用官方 MCP 客户端、下载导出文件、解码 PNG、检查网格拓扑、尺寸和体积、测试持久化和失败的编辑，并验证无效请求。uv run pytest -m 'not integration' 只运行单元检查，不能证明端到端功能正确。

许可证

MIT，版权归 Jack Hacksman 所有，2026 年。