Mcp_3d_relief

MCP STL 3D 浮雕生成器

本项目提供一个 MCP 服务，可将 2D 图像转换为 STL 格式的 3D 浮雕模型，适用于 3D 打印或渲染。

功能

• 将任意图像转换为 3D 浮雕模型
• 控制模型尺寸（宽度、厚度）
• 为 3D 模型添加可选底座
• 反转深度以实现不同的浮雕效果
• 快速处理并立即提供下载链接

安装

前置条件

• Python 3.10+
• uv

选项 1：本地安装

1. 克隆代码仓库：

git clone https://github.com/bigchx/mcp_3d_relief.git
cd mcp_3d_relief

2. 安装依赖：

uv pip sync requirements.txt

3. 运行/检查服务：

mcp run server.py
mcp dev server.py

使用方法

JSON 配置

{
  "mcpServers": {
    "mcp_3d_relief": {
      "command": "uv",
      "args": ["--directory", "{fill_in_your_path_here}", "run", "server.py"]
    }
  }
}

MCP 工具参数

• image_path：输入图像文件的本地路径或网络 URL
• model_width：3D 模型的宽度，单位为 mm（默认值：50.0）
• model_thickness：3D 模型的最大厚度/高度，单位为 mm（默认值：5.0）
• base_thickness：底座的厚度，单位为 mm（默认值：2.0）
• skip_depth：是否直接使用图像或生成深度图（默认值：true）
• invert_depth：反转浮雕效果（亮部变低而非变高）（默认值：false）
• detail_level：控制处理后图像的分辨率（默认值：1.0）。当 detail_level = 1.0 时，图像以 320px 分辨率处理，生成的 STL 文件通常小于 100MB。较高的值可提升细节质量，但会显著增加处理时间和 STL 文件大小。例如，将 detail_level 加倍可能会使文件大小增加 4 倍或更多。请谨慎使用。

响应

MCP 工具会返回一个 JSON 响应，其中包含：

{
  "status": "success",
  "depth_map_path": "path/to/yourimage_depth_map.png",
  "stl_path": "path/to/yourimage.stl"
}

大模型可以使用提供的 URL 从此 MCP 服务访问生成的文件。

命令行

你也可以直接从命令行使用此脚本，根据图像生成浮雕模型：

python3 relief.py path/to/your/image.jpg

外部深度图生成

若要获得质量更高的深度图，可以使用 Depth-Anything-V2 等外部深度图生成服务。此类服务可以生成更准确的深度图，然后你可以在本项目中使用：

1. 访问 https://huggingface.co/spaces/depth-anything/Depth-Anything-V2
2. 上传图像以生成深度图
3. 下载生成的深度图
4. 设置 skip_depth=false，使用此深度图运行我们的转换器

这种方法可以生成效果更好的 3D 浮雕模型，尤其适用于复杂图像。

工作原理

1. 处理图像以创建深度图（较暗的像素 = 较低，较亮的像素 = 较高）
2. 将深度图转换为由三角面片组成的 3D 网格
3. 在模型底部添加底座
4. 将模型保存为 STL 文件

Our partners