Blender MCP Bridge

A Python MCP (Model Context Protocol) server that connects Cursor IDE to Blender 5.1+, giving Cursor's AI full control over Blender via the official Blender MCP addon.

Built for Blender 5.1's official MCP addon (lab_blender_org/mcp). Incompatible with older community addons.

What It Does

Cursor's AI agent can directly control Blender through natural language:

• Create and modify 3D objects, materials, modifiers
• Set up animations, keyframes, shape keys, drivers
• Manage lighting, camera, world/HDRI
• Run particle systems, physics simulations, constraints
• Create and install Blender addons on the fly
• Import/export OBJ, FBX, glTF, STL
• Control every render setting (switch engines, samples, denoising, etc.)
• Execute any arbitrary bpy Python code inside Blender

53 dedicated tools + execute_blender_code (runs any Python) + call_operator (calls any of Blender's 2940+ operators).

Architecture

Cursor IDE (AI Agent)
      ↕  MCP JSON-RPC 2.0 over stdio
blender_mcp/  ← this package
      ↕  TCP :9876  null-byte-delimited JSON
Blender 5.1 Official MCP Addon  (lab_blender_org/mcp)
      ↕
bpy (Blender Python Engine)

The bridge speaks MCP to Cursor and translates to Blender's native TCP protocol. Blender's addon only accepts:

{"type": "execute", "code": "...", "strict_json": true}\x00

Requirements

| Component | Version | |-----------|---------| | Blender | 5.1 or newer | | Blender MCP Addon | Official lab_blender_org/mcp addon | | Python | 3.9+ (macOS system Python works) | | Cursor IDE | Any recent version |

Setup

Step 1 — Install Blender's Official MCP Addon

Go to blender.org/lab/mcp-server and follow the installation instructions.

You have two options:

Option A — Drag & Drop (recommended):

1. Download the addon from the Blender Lab MCP Server page
2. Drag & drop it into Blender — do it twice: first to add the Blender Lab repository, second to install the addon itself

Option B — Install from Disk:

1. Download the .zip from the Blender Lab MCP Server page
2. In Blender: Edit → Preferences → Add-ons → Install from Disk → select the zip

After install, the addon auto-starts when Blender opens (it listens on localhost:9876 by default).

To verify it's running: Edit → Preferences → Add-ons → search "MCP" → it should show "Server is running".

Step 2 — Clone This Repo

git clone https://github.com/nisimjoseph/blender-mcp-bridge
cd blender-mcp-bridge

No dependencies to install — uses Python standard library only.

Step 3 — Configure Cursor MCP

Open (or create) ~/.cursor/mcp.json and add the blender server entry:

{
  "mcpServers": {
    "blender": {
      "command": "/usr/bin/python3",
      "args": ["-m", "blender_mcp"],
      "env": {
        "BLENDER_HOST": "127.0.0.1",
        "BLENDER_PORT": "9876",
        "PYTHONPATH": "/path/to/blender-mcp-bridge"
      }
    }
  }
}

Replace /path/to/blender-mcp-bridge with the actual path where you cloned this repo.

macOS example:

"PYTHONPATH": "/Users/yourname/git/blender-mcp-bridge"

Windows example:

"command": "python",
"PYTHONPATH": "C:\\Users\\yourname\\git\\blender-mcp-bridge"

Step 4 — Reload MCP in Cursor

1. Open Cursor Settings (Cmd+, or Ctrl+,)
2. Navigate to MCP (or search "MCP")
3. Find the blender server and click Refresh / Reconnect

You should see it connect and list 53 tools.

Step 5 — Open Blender and Start Creating

Make sure Blender is running with a scene open. Then in Cursor chat, try:

Create a chrome sphere on a dark marble pedestal with a glowing neon ring orbiting around it

Available Tools

Core

| Tool | Description | |------|-------------| | execute_blender_code | Run any Python code inside Blender | | get_scene_info | List all objects, types, locations, active object | | get_object_info | Detailed info on a specific object |

Operators

| Tool | Description | |------|-------------| | call_operator | Call any bpy.ops.namespace.name(**kwargs) | | list_operators | List/search all 2940+ available operators | | get_operator_schema | Get parameter schema for any operator |

Objects

| Tool | Description | |------|-------------| | create_object | Add primitive: cube, sphere, cylinder, plane, cone, torus, monkey | | delete_object | Delete objects by name | | duplicate_object | Duplicate with optional linked data | | rename_object | Rename an object | | set_transform | Set location, rotation, scale | | set_parent | Parent/unparent objects | | join_objects | Join multiple objects into one | | select_objects | Select/deselect by name |

Mesh

| Tool | Description | |------|-------------| | add_modifier | Add SUBSURF, BEVEL, ARRAY, MIRROR, BOOLEAN, SOLIDIFY, etc. | | remove_modifier | Remove a modifier by name | | apply_modifier | Apply (bake) a modifier permanently | | list_modifiers | List all modifiers on an object | | set_origin | Set origin to geometry, cursor, mass, etc. | | set_shade_mode | Smooth or flat shading |

Materials

| Tool | Description | |------|-------------| | create_material | Create PBR material (base color, roughness, metallic, emission) | | assign_material | Assign a material to an object | | list_materials | List all materials in the file | | get_material_info | Get material node tree info | | set_texture | Load image texture and connect to Base Color |

Animation

| Tool | Description | |------|-------------| | set_keyframe | Insert keyframe on any property at a frame | | remove_keyframe | Delete a keyframe | | set_frame | Jump to a frame | | set_frame_range | Set start/end frame | | get_animation_data | Get all fcurves and keyframes for an object |

Rendering

| Tool | Description | |------|-------------| | get_render_settings | Get current engine, resolution, samples | | set_render_settings | Set engine (CYCLES/EEVEE), resolution, samples, output | | render_frame | Render current frame to file | | render_animation | Render full animation | | viewport_screenshot | Capture the 3D viewport to PNG |

Files

| Tool | Description | |------|-------------| | save_blend | Save .blend file | | open_blend | Open a .blend file | | import_file | Import OBJ, FBX, glTF/GLB, STL, SVG, Alembic | | export_file | Export OBJ, FBX, glTF/GLB, STL |

Addons

| Tool | Description | |------|-------------| | list_addons | List installed addons with enabled status | | enable_addon | Enable an addon by module name | | disable_addon | Disable an addon | | install_addon | Install from .py or .zip file | | create_addon | Write addon source code, install, and enable it | | reload_addon | Hot-reload after code changes |

Scripting

| Tool | Description | |------|-------------| | create_script | Create a script in Blender's Text Editor | | run_script | Run a named script | | list_scripts | List all scripts in the file |

Scene

| Tool | Description | |------|-------------| | set_world_background | Set solid color or HDRI environment | | add_light | Add POINT, SUN, AREA, or SPOT light | | set_camera | Set location, rotation, focal length, Track To target | | manage_collection | Create collections and move objects into them | | set_scene_units | Set METRIC, IMPERIAL, or NONE |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | BLENDER_HOST | 127.0.0.1 | Blender addon host | | BLENDER_PORT | 9876 | Blender addon port | | BLENDER_TIMEOUT | 60 | Socket timeout in seconds |

Example Prompts for Cursor

Build a brick wall with mortar, running-bond pattern, 8 rows × 10 columns

Create a bouncing ball animation with squash and stretch over 120 frames

Set up a 3-point lighting rig with key, fill, and rim lights

Switch the render engine to Cycles, enable GPU rendering, OIDN denoising, 256 samples

Create a Blender addon that adds a custom panel to the N-sidebar with a button that randomizes object colors

Export the scene as GLB, save the .blend file, and take a viewport screenshot

Analyze the scene for high-poly objects and suggest optimizations

Troubleshooting

"Connection refused" on port 9876

• Make sure Blender is running
• Check Edit → Preferences → Add-ons → MCP shows "Server is running"
• Try clicking "Start MCP Bridge Server" manually in the addon panel
• Check that "Online Access" is enabled in Blender's system preferences (required by the addon)

"Incomplete JSON response"

• You're using an old community blender-mcp package — this bridge requires the official Blender 5.1 addon from blender.org/lab/mcp-server

Tools not showing in Cursor

• Verify PYTHONPATH in mcp.json points to the repo root (the folder that contains blender_mcp/)
• Reload the MCP server in Cursor settings
• Test manually: PYTHONPATH=/your/path python3 -m blender_mcp — it should not crash on import

Timeout on long operations

• Increase BLENDER_TIMEOUT in mcp.json env (default 60s)
• Rendering and physics baking can take longer than 60 seconds

Project Structure

blender-mcp-bridge/
  blender_mcp/
    __main__.py         Entry point: python3 -m blender_mcp
    server.py           MCP JSON-RPC 2.0 stdio transport
    blender_client.py   TCP client — only file that knows the wire protocol
    registry.py         @register_tool decorator and tool registry
    session.py          Lightweight session state cache
    tools/
      __init__.py       Imports all tool modules (triggers registration)
      core.py           execute_blender_code, get_scene_info, get_object_info
      operators.py      call_operator, list_operators, get_operator_schema
      objects.py        create, delete, duplicate, rename, transform, parent...
      mesh.py           modifiers, shade mode, set_origin
      materials.py      create, assign, textures, shader nodes
      animation.py      keyframes, timeline, animation data
      rendering.py      render settings, render_frame, viewport_screenshot
      files.py          save/open .blend, import/export
      addons.py         list, enable, disable, install, create, reload
      scripting.py      text editor scripts
      scene.py          world, lights, camera, collections, units

License

MIT