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):

Download the addon from the Blender Lab MCP Server page
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:

Download the .zip from the Blender Lab MCP Server page
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

Open Cursor Settings (Cmd+, or Ctrl+,)
Navigate to MCP (or search "MCP")
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

MCP Servers