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注册表查找和通配符路径展开
检测优先级：
BLENDER_EXECUTABLE环境变量（完整可执行文件路径）BLENDER_PATH环境变量（Blender安装目录）- 自动检测常见安装位置
- 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()
如果自动检测失败，请：
- 确认已安装Blender 3.6
- 设置相应的环境变量
- 检查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进程卡死
- 模型质量验证，确保输出结果可用