Content
# instant-meshes-mcp
This project provides 3D model processing services via the MCP protocol, utilizing Instant Meshes and pymeshlab for automatic retopology, decimation, and quality analysis of 3D models (OBJ/GLB). It supports batch processing, URL input, material texture preservation, archive management, and more.
## Features
### 🔧 Model Processing Functions
- **Intelligent Decimation**: Supports progressive decimation to avoid model fragmentation while preserving UV coordinates and textures.
- **Retopology**: Uses Instant Meshes for mesh reconstruction to fix topological issues.
- **Automatic Selection**: Automatically selects the best processing method (decimation/retopology) based on model quality.
- **Format Support**: Supports GLB/OBJ input and unified GLB output.
### 📁 File Handling Capabilities
- **Multiple Inputs**: Supports local files, folders, and remote URLs.
- **Material Preservation**: Automatically processes MTL files and texture files to maintain material integrity.
- **Package Integrity**: Validates the integrity of OBJ packages, checking for missing MTL and texture files.
### 📊 Quality Analysis
- **Mesh Quality Check**: Analyzes face count, vertex count, and topological issues.
- **Model Diagnosis**: Detects holes, separated components, and abnormal edge lengths.
- **Processing Suggestions**: Provides decimation suggestions and parameter recommendations based on model features.
### 🗂️ Archive Management
- **Automatic Archiving**: Automatically creates an archive folder containing models, textures, and logs after processing is complete.
- **Archive Management**: Supports listing, cleaning, and copying archive folders.
- **Structured Storage**: Categorized storage in model/, textures/, logs/ with detailed metadata.
## Environment Requirements
- Python 3.8+
- Windows 10/11
- Place `Instant Meshes.exe` in the project root directory.
- **Blender 3.6** (for GLB file processing and texture extraction).
## Install Dependencies
```bash
pip install -r requirements.txt
```
## Blender 3.6 Configuration
The system will automatically detect the installation location of Blender 3.6, supporting various installation methods:
**Automatic Path Detection:**
- Standard Installation: `C:\Program Files\Blender Foundation\Blender 3.6\`
- Portable Version: `[User Custom Path]\Blender\3.6\` (e.g., `D:\Software\Blender\3.6\`)
- Steam Version: `C:\Program Files (x86)\Steam\steamapps\common\Blender\`
**Manual Configuration (Optional):**
```bash
# Set environment variable (modify according to actual installation path)
set BLENDER_EXECUTABLE=D:\Software\Blender\3.6\blender.exe
```
**Verify Installation:**
```python
# Test Blender detection
result = await test_blender_detection_tool()
```
## MCP Tool Functions
### 1. process_model - Unified Model Processing
The main model processing tool, supporting decimation and retopology:
```python
# Automatic processing (intelligent selection of decimation or retopology)
result = await process_model(
input_model="model.glb",
target_faces=5000,
operation="simplify" # auto/simplify/remesh
)
# Pure decimation processing
result = await process_model(
input_model="model.obj",
target_faces=3000,
operation="simplify",
preserve_uv=True
)
# Retopology processing
result = await process_model(
input_model="broken_model.obj",
target_faces=8000,
operation="remesh",
mode="fine" # balanced/fine/coarse/fix_holes
)
```
**Parameter Explanation:**
- `input_model`: Input model path (supports GLB/OBJ files, folders, or URLs).
- `target_faces`: Target face count.
- `operation`: Operation type.
- `auto`: Automatically selects (use simplify for watertight models, remesh for problematic ones).
- `simplify`: Pure decimation, maintaining the original mesh structure.
- `remesh`: Retopology, fixing mesh issues.
- `mode`: Retopology mode (balanced/fine/coarse/fix_holes).
- `preserve_boundaries`: Whether to preserve boundary features.
- `preserve_uv`: Whether to preserve UV coordinates.
- `create_archive`: Whether to create an archive folder (default true).
### 2. analyze_model - Model Quality Analysis
Analyzes model quality and file structure:
```python
# Automatic analysis
analysis = await analyze_model(
input_path="model.obj",
analysis_type="auto"
)
# Complete analysis
analysis = await analyze_model(
input_path="model_folder/",
analysis_type="full"
)
# Quality analysis only
quality = await analyze_model(
input_path="model.glb",
analysis_type="quality"
)
```
**Analysis Types:**
- `auto`: Automatically detects input type and selects appropriate analysis.
- `quality`: Mesh quality analysis (face count, topology, suggestions, etc.).
- `folder`: OBJ folder structure analysis.
- `validation`: OBJ package integrity validation.
- `full`: Executes all available analyses.
### 3. manage_archives - Archive Management
Manages processed model archives:
```python
# List archives
archives = await manage_archives(action="list", limit=10)
# Clean old archives (preview mode)
cleanup = await manage_archives(
action="clean",
days_to_keep=30,
dry_run=True
)
# Actual cleanup
cleanup = await manage_archives(
action="clean",
days_to_keep=30,
dry_run=False
)
# Copy archive
copy_result = await manage_archives(
action="copy",
archive_name="model_20241201_143022",
copy_to="./extracted_models/"
)
# Get archive directory information
info = await manage_archives(action="info")
```
## Usage Instructions
### 1. Start the MCP Service
```bash
python server.py
```
### 2. Call via MCP Client
```json
{
"method": "tools/call",
"params": {
"name": "process_model",
"arguments": {
"input_model": "https://example.com/model.glb",
"target_faces": 5000,
"operation": "auto",
"create_archive": true
}
}
}
```
### 3. Example mcp.json Configuration
```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"
}
}
}
}
```
## Workflow Example
### Basic Model Simplification
```python
# 1. Analyze the model
analysis = await analyze_model("input.glb", "auto")
print(f"Original face count: {analysis['mesh_quality']['faces']}")
print(f"Recommended target: {analysis['mesh_quality']['recommended_target_faces']}")
# 2. Process the model
result = await process_model(
input_model="input.glb",
target_faces=analysis['mesh_quality']['recommended_target_faces'],
operation="simplify"
)
# 3. Manage archives
archives = await manage_archives("list")
print(f"Created archive: {result}")
```
### Batch Folder Processing
```python
# Analyze folder structure
folder_analysis = await analyze_model("model_folder/", "folder")
# Process main model
result = await process_model(
input_model="model_folder/",
target_faces=5000,
operation="simplify"
)
```
## Main Dependencies
- **trimesh**: 3D model format conversion and geometric processing.
- **pymeshlab**: Mesh simplification and repair.
- **requests**: Remote file downloading.
- **psutil**: Process management.
- **mcp**: MCP protocol support.
## System Requirements
### Blender 3.6
This system requires **Blender 3.6** for GLB file conversion and texture extraction:
**Automatic Detection Features:**
- The system will automatically detect the installation location of Blender 3.6.
- Supports standard installation, portable version, Steam version, and more.
- Supports Windows registry lookup and wildcard path expansion.
**Detection Priority:**
1. `BLENDER_EXECUTABLE` environment variable (full executable file path).
2. `BLENDER_PATH` environment variable (Blender installation directory).
3. Automatic detection of common installation locations.
4. PATH environment variable search.
**Common Installation Paths:**
- Standard Installation: `C:\Program Files\Blender Foundation\Blender 3.6\blender.exe`
- Portable Version: `[User Custom Path]\Blender\3.6\blender.exe` (e.g., `D:\Software\Blender\3.6\blender.exe`)
- Steam Version: `C:\Program Files (x86)\Steam\steamapps\common\Blender\blender.exe`
**Manual Configuration (Optional):**
```bash
# Set environment variable to specify Blender path (modify according to actual installation path)
set BLENDER_EXECUTABLE=D:\Software\Blender\3.6\blender.exe
# Or set Blender installation directory
set BLENDER_PATH=D:\Software\Blender\3.6
```
**Functionality Description:**
- Converts GLB files to OBJ format (including MTL material files).
- Automatically extracts embedded textures from GLB (color, normal, ORM, etc.).
- Supports complete conversion of PBR materials.
- Generates OBJ/MTL files compatible with third-party tools.
**Detection Diagnostics:**
You can use the built-in detection tool to verify Blender configuration:
```python
# Test Blender detection functionality
result = await test_blender_detection_tool()
```
If automatic detection fails, please:
1. Ensure Blender 3.6 is installed.
2. Set the appropriate environment variables.
3. Check the permissions of the Blender executable file.
## Directory Structure
```
instant-meshes-mcp/
├── server.py # Main service and MCP tool implementation
├── Instant Meshes.exe # Core program for retopology
├── output_remesh/ # Output model directory
├── archives/ # Archive folder directory
├── temp/ # Temporary file directory (automatically cleaned)
├── logs/ # Run log directory
├── requirements.txt # Python dependencies
└── README.md # Project description
```
## Archive Structure
The structure of the archive folder created after each processing completion:
```
archives/model_20241201_143022/
├── model/ # Main model files and MTL
│ ├── model.glb
│ └── model.mtl
├── textures/ # Texture files
│ ├── diffuse.jpg
│ └── normal.png
├── logs/ # Processing logs
│ └── process_model_20241201_143022.log
└── info.json # Processing metadata and configuration information
```
## Featured Functions
### Progressive Decimation
- Automatically performs stepwise decimation during significant face reduction to avoid model fragmentation.
- Specially protects models with UV coordinates.
- Intelligent boundary protection and topology preservation.
### Intelligent Material Handling
- Automatically detects and copies MTL files.
- Supports various texture types (diffuse, normal, specular, etc.).
- Corrects file reference paths to ensure materials load correctly.
### Quality Monitoring
- Real-time detection of model quality issues.
- Provides processing suggestions and parameter recommendations.
- Automatically generates quality reports.
## Notes
- Only supports Windows platform (depends on Instant Meshes.exe).
- **Requires Blender 3.6** (for GLB file processing and texture extraction).
- Input supports OBJ and GLB formats.
- Output is uniformly in GLB format, preserving materials and textures.
- GLB files are automatically converted to OBJ for processing and then back to GLB.
- All temporary files are automatically cleaned after processing is complete.
- Log files are timestamped for easy tracking of processing history.
- Blender processes run independently and will not block the main program.
## Error Handling
- Clear error messages and log records.
- Automatically cleans temporary files even in exceptional circumstances.
- Timeout protection to prevent Instant Meshes processes from hanging.
- Model quality validation to ensure output results are usable.
