OpenSCAD

OpenSCAD MCP Server

一个 MCP（Model Context Protocol）服务，可从 OpenSCAD（SCAD）源代码渲染 PNG 预览图和 STL 几何体。它旨在支持由 Agent 驱动的迭代式 CAD 工作流，让模型能够以可视化方式预览，并导出供后续使用（例如制造、仿真或检查）。

⚠️ 测试版
此 MCP 服务目前处于测试阶段。性能、API 和功能可能会发生变化。欢迎提交问题和贡献。

使用场景

• 由 Agent 驱动的迭代式建模
  Agent 生成或修改 OpenSCAD 源代码，渲染 PNG 预览图以评估形状和比例，并在多轮交互中不断完善模型。

• 在 MCP 上下文中生成几何产物
  Agent 将 STL 文件导出为具体的几何产物，以便传递给下游工具、存储、检查，或交给其他支持 MCP 的系统。

• 为参数化设计提供视觉依据
  PNG 预览图可为参数化或程序化的 SCAD 代码提供视觉依据，减少幻觉，并使 Agent 能够推理空间变化。

• 设计验证与比较
  Agent 可以渲染模型的多个变体（例如参数扫描），并在决定保留或导出哪种几何体之前，以可视化方式比较结果。

可用工具

• render_scad_png：从 SCAD 源代码渲染 PNG 预览图像。
  • 输入：scadCode（字符串）、可选的 width/height（数字）、可选的 cameraPreset 和可选的 cameraPosition
    • cameraPreset：以下值之一：isometric、front、back、left、right、top、bottom
    • cameraPosition：{ x, y, z }
  • 输出：MCP ImageContent
• export_scad_stl：导出由 SCAD 源代码生成的 STL。
  • 输入：scadCode（字符串）、可选的 filename（字符串）
  • 输出：MCP 嵌入式资源（STL）

技能

此代码库还包含一项 OpenSCAD 迭代式建模技能，演示如何使用此 MCP 服务支持 SCAD → PNG → 评估 → 优化的迭代循环。

限制

• 性能：渲染复杂的 SCAD 模型可能较慢，在 WASM 环境中尤其如此。
• 功能支持：并非所有 OpenSCAD 功能都能得到完整支持，或在 WASM 版本中可能存在限制。
• 字体：目前不支持文本渲染。计划在未来版本中提供支持。

安装

已发布的软件包旨在通过 stdio 运行。使用 npx 在 MCP 客户端中进行配置：

{
  "mcpServers": {
    "openscad": {
      "command": "npx",
      "args": ["-y", "openscad-mcp-server"]
    }
  }
}

若要改为通过 HTTP 运行（例如在 Docker 中），请传入 --http：

MCP_PORT=3000 npx -y openscad-mcp-server --http

该服务提供 GET /health，并在 POST /mcp 提供无状态的可流式 HTTP MCP 端点。

使用技能

Agents skills 是一种简单、开放的格式，可用于为 Agent 提供新能力和专业知识。

使用 OpenSCAD 迭代式建模技能最简单的方法是通过 skills CLI 安装：

npx skills add fboldo/openscad-mcp-server --skill openscad-iterative-modeling

本地开发

• 安装依赖：bun install
• Stdio（与客户端的运行方式一致）：bun index.ts --stdio
• HTTP（适合手动测试）：bun index.ts（或 --http）
  • 端口：MCP_PORT（默认值为 3000）
  • 端点：GET /health，MCP 端点为 POST /mcp
• MCP Inspector：bun run dev

类似项目

• jhacksman/OpenSCAD-MCP-Server 该项目采用了不同的方法：根据用户提示词生成图像，然后进行 3D 重建，甚至还能发现 3D 打印机。这是一个非常有趣的项目，如果你对 OpenSCAD 和 MCP 服务感兴趣，我建议你去了解一下。

• petrijr/openscad-mcp 与本项目类似，但它使用基于 Python 的服务，并依靠 OpenSCAD CLI 进行渲染。

相关链接

• OpenSCAD
• OpenSCAD WASM
• Model Context Protocol（MCP）
• Bun

许可证

MIT — 参见 LICENSE。