mlolson/blender-orchestrator: Agentic orchestrator framework for blender. Includes blender MCP tools and integrations with mesh and image generators.

Create 3D models in Blender using natural language. MCP server lets agent directly control Blender, enabling you to build complex 3D scenes through conversation. Scene comprehension tooling and skills gives LLM improved spatial awareness for better results.

Spatial intelligence suite helps AI understand space.

• Natural language positioning — Say “place the lamp on the nightstand” and it figures out the coordinates, checks for collisions, and handles stacking.
• Real-world dimensions database — 55+ common objects (furniture, appliances, decor) with accurate real-world measurements. The AI knows a kitchen counter is 0.9m tall and a doorway is 2.1m × 0.9m.
• Collision detection & safe movement — Validate transforms before applying them. Query how far an object can move in each direction without hitting anything.
• Spatial queries — Ask “what’s on the table?” or “what’s near the door?” and get answers.
• Scene Building Guide — A comprehensive reference doc that AI agents can read before building a scene, covering room dimensions, placement rules, common mistakes, and worked examples.

ASCII visualizer tool gives the LLM a way to understand spatial relationships between objects. Renders the scene from any angle — top, bottom, front, back, left, right, or all six at once. Configurable resolution up to 120×120 cells.

--- Top (looking down, +Z) ---
Axes: horizontal=X, vertical=Y | 5.3m x 4.3m (cell: 0.25m, grid: 21x17)

WWWWWWWWWWWWWWWWWWWWW
W...................W
W...................W
W..TTTTTT..........W
W..TTTTTT..........W
W..TTTTTT....SS....W
W............SS....W
W...................W
W.......CCCC.......W
W.......CCCC.......W
W...................W
WWWWWWWWWWWWWWWWWWWWW

Legend: C=Couch, S=Shelf, T=Table, W=Wall_Back

Full control over all four Blender light types — point, sun, spot, and area lights. Set color, intensity, shadow properties, cone angles, and more. Previously only HDRI environment lighting was available; now you can build precise studio setups, dramatic spotlights, or warm interior scenes.

Create perspective, orthographic, and panoramic cameras. Auto-frame objects for product shots. Set depth of field, adjust lens focal length, and control clipping planes. Essential for rendering composed shots of your scenes.

One command creates a properly dimensioned room with floor and four walls. Specify width, depth, height, and wall thickness — then start furnishing. Combined with the dimensions database and spatial tools, the AI can furnish a realistic room from a single prompt.

Extensible architecture allows you to plug in texture and model gen services of your choice, including Replicate, Meshy, Stability.ai, and more.

Built in access to thousands of free CC0 assets from Poly Haven — no API key needed. Download HDRIs for environment lighting, PBR texture sets for realistic materials, and ready-to-use 3D models. All assets are CC0 licensed (free for any use, no attribution required).

• Spatial intelligence: AI understands real-world dimensions, detects collisions, and reasons about object relationships — not just coordinates.
• AI-powered generation: Generate 3D meshes from text descriptions or reference images using Meshy and Stability AI.
• Complete scene control: Lighting, cameras, materials, rendering — everything you need to go from empty scene to finished render.
• Rapid prototyping: Iterate on designs through conversation, getting immediate visual feedback.
• VR-ready exports: Optimize and export models for Meta Quest and Horizon Worlds with built-in platform presets.
• Free assets: Thousands of CC0 HDRIs, textures, and models from Poly Haven — no API key required.

• Blender 4.0+
• Python 3.10+
• uv (recommended) or pip

1. Install Python dependencies

cd /path/to/blender-orchestrator
uv venv && source .venv/bin/activate
uv pip install -e .

2. Install the Blender add-on

python scripts/install_addon.py

Or manually: Blender → Edit → Preferences → Add-ons → Install → select blender_addon folder → enable “Blender MCP Bridge”

3. Configure Agent

Add to your Agent Desktop config (~/Library/Application Support/Agent/Agent_desktop_config.json on macOS):

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["--directory", "/path/to/blender-orchestrator", "run", "blender-mcp"]
    }
  }
}

For Claude Code CLI, add the same to .claude/settings.json.

1. Open Blender
2. Press N in the 3D Viewport → MCP tab → Click “Start Server”
3. Start talking to Claude about your 3D scene

Create and manipulate basic shapes with full control over position, rotation, and scale.

Modify geometry with professional modeling operations.

Create complex organic and geometric forms.

Full PBR material support with AI-powered texture generation.

Create and control lights for realistic or stylized scene illumination.

Create and position cameras for rendering and visualization.

Tools for understanding and manipulating scene layout with real-world spatial awareness.

See the Scene Building Guide for detailed usage patterns and examples.

Generate complete 3D models from text or images using cloud AI APIs.

Tools for optimizing 3D assets for VR platforms.

Access thousands of free CC0 assets from Poly Haven.

Generate 3D meshes using Meshy and textures using Replicate.

Set API keys via environment variables:

export MESHY_API_KEY="msy_your_key_here"
export REPLICATE_API_TOKEN="r8_your_token_here"

Or create ~/.config/blender-mcp/ai_providers.json:

{
  "meshy": { "api_key": "msy_your_key_here", "timeout": 600 },
  "replicate": { "api_key": "r8_your_token_here", "timeout": 300 }
}

"Generate a wooden treasure chest"
"Create a cartoon dog in the scene"
"Make a realistic medieval castle tower"

Art styles: realistic, cartoon, sculpture, pbr

• Use images with a single object on a clean background
• Ensure good lighting and centered composition
• Avoid cluttered scenes

Built-in tools for optimizing 3D assets for VR platforms, with presets for Meta Horizon Worlds.

Check if your model is VR-ready:

validate_for_vr(
    object_name="Chair",
    platform="horizon_worlds"
)

Returns warnings for poly count, texture size, and material issues.

Automatically optimize models:

optimize_for_vr(
    object_name="Chair",
    platform="horizon_worlds",
    target_triangles=10000,
    merge_by_distance=True
)

Create level-of-detail variants:

generate_lod_chain(
    object_name="Chair",
    lod_levels=[1.0, 0.5, 0.25, 0.1]
)

Export optimized scenes:

export_vr_scene(
    output_path="/path/to/scene.glb",
    platform="horizon_worlds",
    include_all_objects=True
)

Access thousands of free CC0 assets from Poly Haven — no API key required.

search_polyhaven(
    query="brick",
    asset_type="texture",
    limit=10
)

Asset types: hdri, texture, model

Apply realistic environment lighting:

download_polyhaven_hdri(
    asset_id="industrial_sunset_02",
    resolution="4k",
    apply_to_scene=True
)

Get complete PBR texture sets:

download_polyhaven_texture(
    asset_id="brick_wall_02",
    resolution="2k",
    apply_to_object="Cube"
)

Import ready-to-use 3D models:

download_polyhaven_model(
    asset_id="wooden_chair",
    import_to_scene=True,
    location=[0, 0, 0]
)

list_polyhaven_categories(asset_type="textures")

All Poly Haven assets are CC0 licensed — free for any use, no attribution required.

“Cannot connect to Blender server”

• Ensure Blender is running with the MCP Bridge add-on enabled
• Click “Start Server” in the MCP panel (press N → MCP tab)
• Check that port 8765 is available

“Object not found”

• Object names are case-sensitive
• Use list_objects to see exact names

Test the connection manually:

curl http://localhost:8765/health

blender-orchestrator/
├── blender_addon/          # Blender add-on (HTTP server + handlers)
│   ├── server/             # Non-blocking HTTP server
│   ├── handlers/           # Operation implementations
│   └── templates/          # Character templates
│
├── mcp_server/             # MCP server
│   ├── server.py           # FastMCP entry point
│   ├── blender_client.py   # HTTP client for Blender communication
│   ├── tools/              # Tool definitions (one module per category)
│   └── ai_clients/         # AI provider implementations
│
└── scripts/                # Installation helpers

1. Create handler in blender_addon/handlers/
2. Register in blender_addon/handlers/__init__.py
3. Create MCP tool in mcp_server/tools/
4. Register in mcp_server/tools/__init__.py

MIT