BlenderMCP Pro

A secure MCP (Model Context Protocol) server for AI-driven 3D modeling in Blender. Connects any MCP-compatible AI client (Claude, etc.) to Blender through a safe, validated tool interface.

Architecture

AI Client (Claude, etc.)
    |
    | MCP Protocol (stdio)
    v
server/          -- FastMCP server with async TCP client
    |
    | TCP (127.0.0.1:9876, JSON-RPC 2.0, length-prefixed)
    v
addon/           -- Blender addon with TCP server & dispatcher
    |
    v
Blender Python API (bpy)

Key design principle: Zero exec()/eval() -- every operation maps to a static handler function with per-parameter input validation. No arbitrary code execution.

Tools (37)

| Category | Count | Tools | |----------|-------|-------| | Scene | 7 | get_info, list_objects, get_object, get_hierarchy, set_unit_system, manage_collection, set_active_object | | Mesh | 9 | create_primitive, create_custom, edit_geometry, get_geometry, set_smooth_shading, separate, join, set_origin, analyze_profile | | Object | 8 | set_transform, get_transform, duplicate, delete, parent, unparent, move_to_collection, apply_transform | | Material | 4 | create, assign, get_info, update | | Modifier | 3 | add, configure, apply | | Viewport | 5 | screenshot, set_camera, auto_screenshot, screenshot_cleanup | | Selection | 1 | set |

Notable Tools

mesh_edit_geometry -- Chained edit-mode operations (extrude, bevel, loop cut, scale, etc.) with smart selection (by position, normal, Z-range)
mesh_analyze_profile -- Deep mesh analysis for reverse-engineering construction (Z-slice profiles, symmetry detection, material zones, loose parts)
mesh_create_custom -- Create meshes from raw vertex/face data
auto_screenshot -- Automatic viewport captures after every modifying operation

Setup

1. Install the Blender Addon

# Build the addon zip
python build_addon.py

# Or install directly (finds Blender automatically)
python install_addon.py

Then enable "BlenderMCP Pro" in Blender Preferences > Add-ons.

2. Install the MCP Server

pip install -e .

3. Configure Your AI Client

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "blendermcp": {
      "command": "blendermcp"
    }
  }
}

See claude_desktop_config_example.json for a full example.

4. Connect

Open Blender
In the addon panel, click "Start Server"
Start your MCP client
The AI can now control Blender

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

Project Structure

addon/              Blender addon (TCP server, handlers, UI)
  handlers/         One module per tool category
  connection.py     TCP server & message framing
  dispatcher.py     Method routing
  validation.py     Input validation
server/             MCP server (FastMCP, async TCP client)
  tools/            One module per tool category
  blender_client.py Async TCP client
  auto_screenshot.py Screenshot management
shared/             Wire protocol, constants, error codes
tests/              pytest unit tests
training/           Training data tools (bulk analyzer, generators)

Training Data Tools

The training/ directory contains tools for generating and analyzing 3D modeling data:

bulk_analyze.py -- Headless Blender script to batch-analyze FBX/OBJ/GLB files into JSON profiles
generate_training_data.py -- Procedural generator for MCP tool-call training sequences (38 object categories, no LLM needed)
fbx_to_recipe.py -- Converts 3D files into exact mesh_create_custom reconstruction recipes

# Analyze a directory of FBX files
blender --background --python training/bulk_analyze.py -- --input ./models/ --output ./templates/

# Generate 10K training samples
python training/generate_training_data.py --count 10000 --format chatml --split --output ./generated/

License

MIT

MCP Servers