Instant Meshes MCP

A 3D model processing server for automatic retopology, simplification, and quality analysis of OBJ/GLB models.

View on GitHub →

instant-meshes-mcp

本项目用于通过MCP协议提供3D模型处理服务，基于Instant Meshes和pymeshlab对3D模型（OBJ/GLB）进行自动重拓扑、减面和质量分析，支持批量处理、URL输入、材质贴图保留、归档管理等功能。

功能特色

🔧 模型处理功能

  • 智能减面：支持渐进式减面，避免模型破碎，保护UV坐标和贴图
  • 重拓扑：使用Instant Meshes进行网格重构，修复拓扑问题
  • 自动选择：根据模型质量自动选择最佳处理方式（减面/重拓扑）
  • 格式支持：支持GLB/OBJ输入，统一GLB输出

📁 文件处理能力

  • 多种输入：支持本地文件、文件夹、远程URL
  • 材质保留：自动处理MTL文件和贴图文件，保持材质完整性
  • 包完整性：验证OBJ包的完整性，检查缺失的MTL和贴图文件

📊 质量分析

  • 网格质量检查：分析面数、顶点数、拓扑问题
  • 模型诊断：检测破洞、分离组件、边长异常等问题
  • 处理建议：根据模型特征提供减面建议和参数推荐

🗂️ 归档管理

  • 自动归档：处理完成后自动创建包含模型、贴图、日志的归档文件夹
  • 归档管理：支持列出、清理、复制归档文件夹
  • 结构化存储：model/、textures/、logs/分类存储，包含详细元数据

环境要求

  • Python 3.8+
  • Windows 10/11
  • 需放置Instant Meshes.exe于项目根目录
  • Blender 3.6（用于GLB文件处理和贴图提取）

安装依赖

pip install -r requirements.txt

Blender 3.6 配置

系统会自动检测Blender 3.6安装位置，支持多种安装方式：

自动检测路径：

  • 标准安装：C:\Program Files\Blender Foundation\Blender 3.6\
  • 便携版：[用户自定义路径]\Blender\3.6\（如 D:\Software\Blender\3.6\）
  • Steam版：C:\Program Files (x86)\Steam\steamapps\common\Blender\

手动配置（可选）：

# 设置环境变量（根据实际安装路径修改）
set BLENDER_EXECUTABLE=D:\Software\Blender\3.6\blender.exe

验证安装：

# 测试Blender检测
result = await test_blender_detection_tool()

MCP工具函数

1. process_model - 统一模型处理

主要的模型处理工具，支持减面和重拓扑：

# 自动处理（智能选择减面或重拓扑）
result = await process_model(
    input_model="model.glb",
    target_faces=5000,
    operation="simplify"  # auto/simplify/remesh
)

# 纯减面处理
result = await process_model(
    input_model="model.obj",
    target_faces=3000,
    operation="simplify",
    preserve_uv=True
)

# 重拓扑处理
result = await process_model(
    input_model="broken_model.obj",
    target_faces=8000,
    operation="remesh",
    mode="fine"  # balanced/fine/coarse/fix_holes
)

参数说明：

  • input_model: 输入模型路径（支持GLB/OBJ文件、文件夹或URL）
  • target_faces: 目标面数
  • operation: 操作类型
    • auto: 自动选择（水密模型用simplify，有问题的用remesh）
    • simplify: 纯减面，保持原有网格结构
    • remesh: 重拓扑，修复网格问题
  • mode: 重拓扑模式（balanced/fine/coarse/fix_holes）
  • preserve_boundaries: 是否保持边界特征
  • preserve_uv: 是否保持UV坐标
  • create_archive: 是否创建归档文件夹（默认true）

2. analyze_model - 模型质量分析

分析模型质量和文件结构：

# 自动分析
analysis = await analyze_model(
    input_path="model.obj",
    analysis_type="auto"
)

# 完整分析
analysis = await analyze_model(
    input_path="model_folder/",
    analysis_type="full"
)

# 仅质量分析
quality = await analyze_model(
    input_path="model.glb",
    analysis_type="quality"
)

分析类型：

  • auto: 自动检测输入类型并选择合适分析
  • quality: 网格质量分析（面数、拓扑、建议等）
  • folder: OBJ文件夹结构分析
  • validation: OBJ包完整性验证
  • full: 执行所有可用分析

3. manage_archives - 归档管理

管理处理后的模型归档：

# 列出归档
archives = await manage_archives(action="list", limit=10)

# 清理旧归档（预览模式）
cleanup = await manage_archives(
    action="clean", 
    days_to_keep=30, 
    dry_run=True
)

# 实际清理
cleanup = await manage_archives(
    action="clean", 
    days_to_keep=30, 
    dry_run=False
)

# 复制归档
copy_result = await manage_archives(
    action="copy",
    archive_name="model_20241201_143022",
    copy_to="./extracted_models/"
)

# 获取归档目录信息
info = await manage_archives(action="info")

使用方法

1. 启动MCP服务

python server.py

2. 通过MCP客户端调用

{
  "method": "tools/call",
  "params": {
    "name": "process_model",
    "arguments": {
      "input_model": "https://example.com/model.glb",
      "target_faces": 5000,
      "operation": "auto",
      "create_archive": true
    }
  }
}

3. mcp.json配置示例

{
  "mcpServers": {
    "instant-meshes-mcp": {
      "command": "python",
      "args": [
        "your_abs_dir/instant-meshes-mcp/server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "BLENDER_PATH":"your_blender3.6.abs_dir"
      }
    }
  }
}

工作流程示例

基础模型简化

# 1. 分析模型
analysis = await analyze_model("input.glb", "auto")
print(f"原始面数: {analysis['mesh_quality']['faces']}")
print(f"推荐目标: {analysis['mesh_quality']['recommended_target_faces']}")

# 2. 处理模型
result = await process_model(
    input_model="input.glb",
    target_faces=analysis['mesh_quality']['recommended_target_faces'],
    operation="simplify"
)

# 3. 管理归档
archives = await manage_archives("list")
print(f"已创建归档: {result}")

批量文件夹处理

# 分析文件夹结构
folder_analysis = await analyze_model("model_folder/", "folder")

# 处理主模型
result = await process_model(
    input_model="model_folder/",
    target_faces=5000,
    operation="simplify"
)

主要依赖包

  • trimesh: 3D模型格式转换和几何处理
  • pymeshlab: 网格简化和修复
  • requests: 远程文件下载
  • psutil: 进程管理
  • mcp: MCP协议支持

系统要求

Blender 3.6

本系统需要 Blender 3.6 来处理GLB文件的转换和贴图提取：

自动检测功能：

  • 系统会自动检测Blender 3.6安装位置
  • 支持标准安装、便携版、Steam版等多种安装方式
  • 支持Windows注册表查找和通配符路径展开

检测优先级：

  1. BLENDER_EXECUTABLE 环境变量（完整可执行文件路径）
  2. BLENDER_PATH 环境变量（Blender安装目录）
  3. 自动检测常见安装位置
  4. PATH环境变量搜索

常见安装路径：

  • 标准安装：C:\Program Files\Blender Foundation\Blender 3.6\blender.exe
  • 便携版：[用户自定义路径]\Blender\3.6\blender.exe（如 D:\Software\Blender\3.6\blender.exe）
  • Steam版：C:\Program Files (x86)\Steam\steamapps\common\Blender\blender.exe

手动配置（可选）：

# 设置环境变量指定Blender路径（根据实际安装路径修改）
set BLENDER_EXECUTABLE=D:\Software\Blender\3.6\blender.exe
# 或设置Blender安装目录
set BLENDER_PATH=D:\Software\Blender\3.6

功能说明：

  • GLB文件转换为OBJ格式（含MTL材质文件）
  • 自动提取GLB中的嵌入贴图（颜色、法线、ORM等）
  • 支持PBR材质的完整转换
  • 生成与第三方工具兼容的OBJ/MTL文件

检测诊断： 可使用内置的检测工具验证Blender配置：

# 测试Blender检测功能
result = await test_blender_detection_tool()

如果自动检测失败，请：

  1. 确认已安装Blender 3.6
  2. 设置相应的环境变量
  3. 检查Blender可执行文件权限

目录结构

instant-meshes-mcp/
├── server.py              # 主服务与MCP工具实现
├── Instant Meshes.exe     # 重拓扑核心程序
├── output_remesh/         # 输出模型目录
├── archives/              # 归档文件夹目录
├── temp/                  # 临时文件目录（自动清理）
├── logs/                  # 运行日志目录
├── requirements.txt       # Python依赖
└── README.md             # 项目说明

归档结构

每次处理完成后创建的归档文件夹结构：

archives/model_20241201_143022/
├── model/                 # 主模型文件和MTL
│   ├── model.glb
│   └── model.mtl
├── textures/              # 贴图文件
│   ├── diffuse.jpg
│   └── normal.png
├── logs/                  # 处理日志
│   └── process_model_20241201_143022.log
└── info.json             # 处理元数据和配置信息

特色功能

渐进式减面

  • 大幅减面时自动分步进行，避免模型破碎
  • 特别保护带UV坐标的模型
  • 智能边界保护和拓扑保持

智能材质处理

  • 自动检测和复制MTL文件
  • 支持多种贴图类型（diffuse、normal、specular等）
  • 修正文件引用路径，确保材质正确加载

质量监控

  • 实时检测模型质量问题
  • 提供处理建议和参数推荐
  • 自动生成质量报告

注意事项

  • 仅支持Windows平台（依赖Instant Meshes.exe）
  • 需要安装Blender 3.6（用于GLB文件处理和贴图提取）
  • 输入支持OBJ和GLB格式
  • 输出统一为GLB格式，保留材质和贴图
  • GLB文件会自动通过Blender转换为OBJ进行处理，然后转回GLB
  • 所有临时文件在处理完成后自动清理
  • 日志文件按时间戳命名，便于追踪处理历史
  • Blender进程独立运行，不会阻塞主程序

错误处理

  • 明确的错误信息和日志记录
  • 自动清理临时文件，即使在异常情况下
  • 超时保护，防止Instant Meshes进程卡死
  • 模型质量验证，确保输出结果可用

Related Servers