项目简介

OpenSCAD MCP 是一个基于 Model Context Protocol (MCP) 的服务器，专门用于将 OpenSCAD 代码渲染成图片。它将 OpenSCAD 的 3D 模型设计能力封装为一个可供大型语言模型 (LLM) 调用的工具，使得 LLM 能够直接生成和处理 CAD 图形。该服务器支持并发渲染、渲染结果持久化以及基于令牌的访问控制。

主要功能点

OpenSCAD 代码渲染: 将用户提供的 OpenSCAD 代码渲染成 2D 图像（如 PNG 格式），支持多种视角（如 3D、顶视图、前视图、左视图）和自定义图像尺寸。
上下文交互: 作为一个 MCP 服务器，它以标准化的方式向 LLM 客户端提供“渲染 OpenSCAD 脚本”这一工具，使 LLM 能够理解并调用此功能。
并发控制与持久化: 服务器限制同时进行的 OpenSCAD 渲染任务数量，防止服务器因高负载而崩溃。渲染结果（原始 SCAD 代码和生成的图像）会被持久化保存到本地文件系统，方便后续查阅。
安全性: 支持基于令牌 (token) 的身份验证机制，确保只有经过授权的客户端才能访问服务器提供的服务。

安装步骤

安装必要软件: 在您的 Linux 系统上安装 'openscad' 和 'certbot'（用于 SSL 证书）。

sudo apt install certbot openscad

（可选）如果需要 SSL 证书，请运行以下命令并按提示操作：

sudo certbot certonly --standalone -d your.domain.com
# 配置证书自动续期：
sudo crontab -e
# 添加一行：0 12 * * * /usr/bin/certbot renew --quiet

克隆仓库:

git clone https://github.com/format37/openscad-mcp.git
cd openscad-mcp

配置环境变量:

进入 'mcp' 目录：'cd mcp'
编辑 '.env.production' 文件，定义您的 MCP 访问令牌。

MCP_TOKENS=您的安全令牌,另一个令牌 # 多个令牌用逗号分隔
MCP_REQUIRE_AUTH=true             # 建议开启，强制验证令牌
MCP_ALLOW_URL_TOKENS=true         # 允许通过 URL 参数或路径传递令牌

重要提示: '您的安全令牌' 是用于验证客户端请求的秘密字符串，请务必设置一个强随机字符串。

启动服务: 确保您的系统已安装 Docker 和 Docker Compose。
```
./production.sh
```
此脚本将使用 Docker Compose 启动服务，并通过 Caddy 服务器处理 SSL 证书和反向代理，将 OpenSCAD MCP 服务器暴露在指定的域名和路径下。

服务器配置 (供 MCP 客户端使用)

您的 MCP 客户端需要以下信息才能连接到 OpenSCAD MCP 服务器。通常，这些配置会以 JSON 格式提供给客户端。

{
  "mcpServers": {
    "openscad": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://您的域名/openscad/您的令牌/"
      ],
      "description": "用于渲染 OpenSCAD 3D 模型并生成图像的 MCP 服务器。"
    }
  }
}

'openscad': 这是您为该 MCP 服务器定义的名称，客户端将通过此名称引用它。
'command': 这是客户端启动用于连接 MCP 服务器的本地进程的命令。此处为 'npx'。
'args': 'command' 命令的参数列表。
- 'mcp-remote': 一个用于连接到远程 MCP 服务器的工具。
- 'https://您的域名/openscad/您的令牌/': MCP 服务器的完整访问 URL。请将 '您的域名' 替换为实际部署的服务器域名（例如 'service.dnk-technologies.com'），并将 '您的令牌' 替换为您在 '.env.production' 中配置的一个有效 'MCP_TOKENS'。
'description': 对服务器功能的简要描述，供客户端界面显示。

基本使用方法

一旦服务器部署完成并配置到您的 MCP 客户端（例如 Claude），您就可以通过客户端与 LLM 交互来调用服务器提供的 'render_scad_script' 工具。例如，您可以在 LLM 客户端中这样描述您的需求：

"请使用 OpenSCAD 渲染一个半径为 5 的球体，代码是 'sphere(5);'，并给我一张 3D 视图的图片。"

MCP 客户端将根据您的指令，将其翻译成对 'render_scad_script' 工具的调用，并提交给 OpenSCAD MCP 服务器进行处理。服务器完成渲染后，会将生成的图片以 MCP 图像格式返回给客户端，供您在 LLM 界面中查看。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (供 MCP 客户端使用)

基本使用方法

信息