Skip to main content
Glama

Blender MCP Reconstruction Harness & Multi-Project Pipeline

Windows Antigravity Blender Python

A production-grade, multi-modal 2D Reference Image to 3D Blender Reconstruction & Self-Refining Harness with integrated Model Context Protocol (MCP) server for AI-driven 3D modeling in Google Antigravity.


🌟 Architecture Overview

The codebase is split into two cleanly separated tiers:

  1. The Reusable Harness (harness/): An analysis, comparison, and iterative self-refining engine that is completely object-agnostic.

  2. Isolated Project Workspaces (projects/<name>/): Standalone project directories containing reference inputs, Blender scripts, and generated outputs.

Blender-MCP/
β”œβ”€β”€ harness/                           # Reusable Reconstruction Engine
β”‚   β”œβ”€β”€ __main__.py                    # CLI: python -m harness run <project>
β”‚   β”œβ”€β”€ config.py                      # Global defaults & convergence thresholds
β”‚   β”œβ”€β”€ project_loader.py              # Manifest parser & workspace discovery
β”‚   β”œβ”€β”€ pipeline/                      # 6-Stage Orchestration
β”‚   β”‚   β”œβ”€β”€ stage_analyze.py           # Stage 1: Computer vision & feature extraction
β”‚   β”‚   β”œβ”€β”€ stage_generate.py          # Stage 2: Blender model synthesis
β”‚   β”‚   β”œβ”€β”€ stage_capture.py           # Stage Capture: Multi-viewport 360Β° orbit & montage
β”‚   β”‚   β”œβ”€β”€ stage_compare.py           # Stage 3: Render vs reference multi-modal comparison
β”‚   β”‚   β”œβ”€β”€ stage_refine.py            # Stage 4: Closed-loop parameter correction
β”‚   β”‚   └── stage_report.py            # Stage 5: Diagnostics, verdicts & summary docs
β”‚   β”œβ”€β”€ capture/                       # Multi-Viewport 360Β° Capture Engine
β”‚   β”‚   β”œβ”€β”€ multi_viewport_renderer.py # 14-camera orbit controller & socket bridge
β”‚   β”‚   β”œβ”€β”€ contact_sheet_generator.py # 4x4 visual montage builder (PIL)
β”‚   β”‚   └── blender_scripts/           # Inside-Blender bpy camera scripts
β”‚   β”‚       └── multi_viewport_render.py
β”‚   β”œβ”€β”€ analyzers/                     # Vision & Profiling Modules
β”‚   β”‚   β”œβ”€β”€ gemini_analyzer.py         # Multi-modal semantic & typography extraction
β”‚   β”‚   β”œβ”€β”€ geometry_analyzer.py       # Radial profile mesh, aspect ratios, landmarks
β”‚   β”‚   β”œβ”€β”€ structural_geometry_analyzer.py # 7-Step BMesh profiling, symmetry & primitives
β”‚   β”‚   β”œβ”€β”€ color_texture_analyzer.py  # CIE L*a*b* K-Means, Gabor filters, BSDF synthesis
β”‚   β”‚   β”œβ”€β”€ placement_report_generator.py # Multi-viewpoint spatial element placement
β”‚   β”‚   └── viewport_analyzer.py       # 360Β° silhouette, coverage & symmetry analyzer
β”‚   β”œβ”€β”€ comparators/                   # Verification Engine
β”‚   β”‚   └── render_geometry_comparator.py # 100-level radial mesh, CIEDE2000 Ξ”E, Procrustes
β”‚   β”œβ”€β”€ materials/                     # PBR Texture Retrieval & Synthesis Engine
β”‚   β”‚   β”œβ”€β”€ pbr_engine.py              # PolyHaven / ambientCG REST client & ranking
β”‚   β”‚   └── material_node_builder.py   # Procedural bpy Principled BSDF node trees
β”‚   β”œβ”€β”€ refiners/                      # Closed-Loop Feedback Optimization Engine
β”‚   β”‚   β”œβ”€β”€ base_refiner.py            # Abstract controller, render triggers & convergence
β”‚   β”‚   β”œβ”€β”€ refiner_generator.py       # Spec-driven refiner synthesizer (zero hardcoding)
β”‚   β”‚   └── template_refiner.py        # LLM generation blueprint for projects
β”‚   β”œβ”€β”€ blender/                       # Blender Communication Layer
β”‚   β”‚   β”œβ”€β”€ client.py                  # Socket client (port 9876)
β”‚   β”‚   └── addon.py                   # Blender MCP connect addon
β”‚   └── utils/                         # Shared Mathematics & Tools
β”‚       └── color_math.py              # Canonical sRGB ↔ XYZ ↔ Lab & CIEDE2000
β”‚
β”œβ”€β”€ projects/                          # Per-Project Workspaces
β”‚   └── bottle/                        # Example: Water Bottle Project
β”‚       β”œβ”€β”€ project.yaml               # Project manifest declaring scripts & tolerances
β”‚       β”œβ”€β”€ reference/                 # Input reference imagery
β”‚       β”‚   └── reference_bottle.jpg
β”‚       β”œβ”€β”€ scripts/                   # Procedural Blender construction & tuning
β”‚       β”‚   β”œβ”€β”€ generate_bottle_3d.py  # 3D scene construction (bpy)
β”‚       β”‚   β”œβ”€β”€ refine_geometry.py     # Closed-loop tuner (subclasses BaseRefinementEngine)
β”‚       β”‚   └── verify_and_refine_bottle.py
β”‚       └── outputs/                   # Generated artifacts
β”‚           β”œβ”€β”€ renders/               # Viewport & Cycles renders (plus viewports/ 14 angles)
β”‚           β”œβ”€β”€ specs/                 # JSON design specifications
β”‚           β”œβ”€β”€ reports/               # Markdown summaries, contact sheets & collages
β”‚           └── textures/              # Downloaded / synthesized PBR textures
β”‚
└── mcp_server/                        # Antigravity Model Context Protocol Server
    β”œβ”€β”€ server.py                      # Windows-native binary stdio server
    └── addon.py                       # Blender socket add-on

Related MCP server: Blender MCP

πŸš€ Quick Start

1. Installation

Clone the repository and install dependencies:

pip install -r requirements.txt

2. Configure Blender Add-on

  1. Open Blender (4.0+ recommended).

  2. Go to Edit > Preferences > Add-ons > Install....

  3. Select mcp_server/addon.py (or root addon.py).

  4. Enable "3D Gen: Blender MCP Connect".

  5. Ensure the add-on server is running (defaults to localhost:9876).

3. Connect Antigravity MCP Server

Add the following to your Antigravity MCP configuration (mcp_config.json):

{
  "mcpServers": {
    "blender": {
      "command": "C:/Path/To/Your/python.exe",
      "args": [
        "C:/Users/PC/myapps/Blender works/mcp_server/server.py"
      ],
      "env": {
        "PYTHONUTF8": "1"
      }
    }
  }
}

⚑ Using the Harness CLI

Discover Projects

python -m harness list

Output:

Found 1 project(s):
  - bottle: Abhinav Bottle (v1.0.0) [bottle]

Inspect Project Configuration

python -m harness info bottle

Execute the Full 5-Stage Pipeline

python -m harness run bottle

Execute a Specific Stage

# Stage 1: Computer Vision & Feature Extraction
python -m harness run bottle --stage analyze

# Stage 2: Blender 3D Model Generation
python -m harness run bottle --stage generate

# Stage: Multi-Viewport 360Β° Capture & Analysis
python -m harness run bottle --stage capture

# Stage 3: Render vs Reference Comparison
python -m harness run bottle --stage compare

# Stage 4: Closed-Loop Refinement Loop
python -m harness run bottle --stage refine

# Stage 5: Final Quality Report & Metrics
python -m harness run bottle --stage report

Dry Run

python -m harness run bottle --dry-run

πŸ”¬ The 6-Stage Pipeline Explained

Stage

Name

Key Algorithms & Operations

Output Artifacts

Stage 1

Analyze

β€’ Radial profile mesh (100 elevation slices)β€’ CIE L*a*b* K-Means palette clusteringβ€’ Gabor filter anisotropy & frequency analysisβ€’ Spatial coordinate mapping from 6 orthographic views

geometry_design_doc.jsoncolor_texture_design_doc.jsonplacement_report.json / .mdmaster_3d_design_specification.json

Stage 2

Generate

β€’ Procedural mesh synthesis in Blenderβ€’ Principled BSDF shader setupβ€’ Procedural PBR texture bakingβ€’ Studio lighting & camera framing

Active 3D Blender sceneinitial_render.png

Stage Capture

Capture

β€’ 14-camera spherical orbit (6 ortho + 8 perspective)β€’ Transparent film background capture with headlight fillβ€’ Lateral & anterior-posterior silhouette symmetry IoUβ€’ 4Γ—4 visual contact sheet montage generation

renders/viewports/*.pngviewport_manifest.jsonviewport_analysis_report.jsonviewport_contact_sheet.png

Stage 3

Compare

β€’ 100-level radial mesh MAEβ€’ Component-wise CIEDE2000 color delta ($\Delta E_{00}$)β€’ Height IoU & Procrustes shape metricβ€’ Visual diagnostic collage generation

comparison_report.jsonrender_geometry_annotated.pngcomparison_side_by_side.png

Stage 4

Refine

β€’ Closed-loop feedback controllerβ€’ Automated bidirectional parameter tuningβ€’ Multi-zone perceptual color optimization

Updated Blender scenerefinement_log.json

Stage 5

Report

β€’ Multi-metric aggregationβ€’ Pass/Fail verdicts against configurable tolerancesβ€’ Actionable recommendations for human review

final_report.jsonfinal_report.md


πŸ“ Creating a New Project

Creating a new reconstruction project is as simple as creating a directory under projects/:

  1. Create directory projects/<your_project>/ with subfolders:

    projects/<your_project>/
    β”œβ”€β”€ project.yaml
    β”œβ”€β”€ reference/
    β”‚   └── reference.jpg
    └── scripts/
        └── generate_model.py
  2. Define project.yaml:

    name: "My Custom Model"
    version: "1.0.0"
    object_type: "custom"
    reference_image: "reference/reference.jpg"
    blender_scripts:
      generate: "scripts/generate_model.py"
    convergence:
      max_iterations: 6
      ciede2000_threshold: 4.0
      ssim_threshold: 0.85
      geometry_score_threshold: 0.85
    render:
      resolution: [1920, 1080]
      view_transform: "Standard"
      samples: 128
    viewport_capture:
      enabled: true
      resolution_scale: 0.5
      samples: 64
      padding_factor: 1.25
      camera_distance_factor: 3.2
  3. Run the harness:

    python -m harness run <your_project>

πŸ› οΈ Testing & Quality Verification

# Verify harness project discovery
python -c "from harness.project_loader import discover_projects; print(discover_projects())"

# Verify color math canonical functions
python -c "from harness.utils.color_math import srgb_to_xyz, xyz_to_lab, compute_ciede2000; print('Color math OK')"

# Verify stage execution
python -m harness run bottle --stage analyze

πŸ“„ License & Credits

Personal Use & Non-Commercial License. Strictly for personal, educational, and non-monetized hobbyist use. Commercial use, resale, and monetization are strictly prohibited. See LICENSE for full legal terms.

Available Tools

21 tools
download_polyhaven_assetB

Download and import a PolyHaven asset into Blender

Inputs: asset_id (required), asset_type (required), resolution, file_format.

download_sketchfab_modelA

Download and import a Sketchfab model by UID

Inputs: uid (required).

execute_blender_codeC

Execute Python code in Blender. Break complex operations into smaller steps.

Inputs: code (required).

generate_hunyuan3d_modelC

Generate 3D asset using Hunyuan3D from text or image

Inputs: text_prompt, input_image_url.

generate_hyper3d_model_via_imagesB

Generate 3D asset using Hyper3D from images

Inputs: bbox_condition, input_image_urls, input_image_paths.

generate_hyper3d_model_via_textA

Generate 3D asset using Hyper3D from text description

Inputs: text_prompt (required), bbox_condition.

get_hunyuan3d_statusA

Check if Hunyuan3D integration is enabled in Blender

Inputs: no named parameters.

get_hyper3d_statusA

Check if Hyper3D Rodin integration is enabled in Blender

Inputs: no named parameters.

get_object_infoB

Get detailed information about a specific object in the scene

Inputs: object_name (required).

get_polyhaven_categoriesB

Get categories for a specific asset type on PolyHaven

Inputs: asset_type.

get_polyhaven_statusA

Check if PolyHaven integration is enabled in Blender

Inputs: no named parameters.

get_scene_infoB

Get detailed information about the current Blender scene

Inputs: no named parameters.

get_sketchfab_statusA

Check if Sketchfab integration is enabled in Blender

Inputs: no named parameters.

get_viewport_screenshotA

Capture a screenshot of the current Blender 3D viewport

Inputs: max_size.

import_generated_assetC

Import asset generated by Hyper3D Rodin

Inputs: name (required), task_uuid, request_id.

import_generated_asset_hunyuanB

Import asset generated by Hunyuan3D

Inputs: name (required), zip_file_url (required).

poll_hunyuan_job_statusC

Check if Hunyuan3D generation task is completed

Inputs: job_id (required).

poll_rodin_job_statusC

Check if Hyper3D Rodin generation task is completed

Inputs: request_id, subscription_key.

search_polyhaven_assetsC

Search for assets on PolyHaven with optional filtering

Inputs: asset_type, categories.

search_sketchfab_modelsB

Search for models on Sketchfab

Inputs: query (required), count, categories, downloadable.

set_textureB

Apply a downloaded PolyHaven texture to an object

Inputs: texture_id (required), object_name (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools target distinct provider/action pairs, and status, search, generate, download, and poll tools are generally separable. The main ambiguity is import_generated_asset vs import_generated_asset_hunyuan, and generate_hunyuan3d_model combines text/image inputs while Hyper3D splits them into two tools.

    Naming Consistency4/5

    Tool names mostly follow a consistent snake_case verb_noun pattern with get_, search_, download_, generate_, poll_, and import_ prefixes. Deviations include import_generated_asset lacking a provider prefix, generate_hunyuan3d_model without a via_text/via_images suffix, and poll_rodin_job_status using 'rodin' instead of 'hyper3d'.

    Tool Count3/5

    At 21 tools, the server sits in the heavy range and presents a large surface for agents to navigate. The breadth of four asset integrations justifies most entries, but the set would benefit from consolidation or clearer grouping.

    Completeness4/5

    Core workflows are well covered: status checks, search/generate, download/import, async polling, and Blender scene introspection/code execution. Minor gaps include no cancel-job tools for generation tasks and set_texture being limited to PolyHaven textures, though execute_blender_code provides a workaround.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to control Blender 3D modeling software through a stable, goal-oriented tool API for safer and more reliable 3D scene manipulation.
      66
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to create, inspect, and animate 3D scenes in Blender through natural language and structured tool calls.
      6
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables AI agents to control Blender through 150+ tools across 24 modules, including modeling, materials, lighting, animation, rendering, mesh quality analysis, and visual feedback, plus expert prompts and goal-first workflow management.
      209
      2
      MIT