Blender MCP Server

Control Blender from any AI assistant using the Model Context Protocol (MCP).

27 tools across 7 namespaces — create objects, assign materials, render images, export scenes, execute Python scripts, manage async jobs, and more.

How It Works

┌─────────────┐      stdio       ┌──────────────────┐    JSON/TCP     ┌─────────────────┐
│  MCP Client  │ ◄──────────────► │  MCP Server      │ ◄─────────────► │  Blender Add-on │
│  (any host)  │                  │  (Python)        │  localhost:9876 │  (runs in bpy)  │
└─────────────┘                  └──────────────────┘                 └─────────────────┘

1. The Blender add-on runs inside Blender and listens on localhost:9876.

2. The MCP server connects to your AI client via stdio and forwards tool calls to Blender over TCP.

3. You ask the AI → it calls MCP tools → Blender executes commands → results flow back.

Related MCP server: BlenderMCP

Quick Start

1. Install the MCP Server

git clone https://github.com/djeada/blender-mcp-server.git
cd blender-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

This creates the executable .venv/bin/blender-mcp-server.

2. Install the Blender Add-on

Build the add-on zip:

./scripts/build_addon_zip.sh

Then in Blender:

1. Go to Edit → Preferences → Add-ons → Install.

2. Select dist/blender_mcp_bridge.zip and enable Blender MCP Bridge.

3. In the 3D Viewport, press N → open the MCP tab.

4. Confirm it shows Listening on 127.0.0.1:9876.

3. Connect Your MCP Client

Add to your config file:

{
  "mcpServers": {
    "blender": {
      "command": "/absolute/path/to/blender-mcp-server/.venv/bin/blender-mcp-server"
    }
  }
}

Replace the path with the actual location of your clone.

Register the server once:

codex mcp add blender -- /absolute/path/to/blender-mcp-server/.venv/bin/blender-mcp-server

Verify with codex mcp list. Then start Codex from any directory — it launches the server automatically.

Point any MCP-compatible client at the server executable:

/absolute/path/to/blender-mcp-server/.venv/bin/blender-mcp-server

The server uses stdio transport. No additional flags are needed.

4. Start Using It

Make sure Blender is open with the add-on listening, then ask your AI assistant:

• "What objects are in my Blender scene?"

• "Create a cube named TestCube at [0, 0, 1]"

• "Render the scene to /tmp/render.png"

The AI calls MCP tools like blender_scene_list_objects and blender_object_create, which the server forwards to Blender.

Example Prompts

• "What objects are in my scene?"

• "Show me the transform of the Camera object"

• "List all materials in the file"

• "Create a sphere named 'Earth' at position [0, 0, 2] with size 3"

• "Add a cylinder at the origin, then scale it to [0.5, 0.5, 4] to make a tall pillar"

• "Create 5 cubes in a row spaced 3 units apart"

• "Create a red material and assign it to the Cube"

• "Make a material called 'Ocean' with color [0.0, 0.3, 0.8] and assign it to the Sphere"

• "Change the color of 'RedMaterial' to orange"

• "Move the Cube up 2 units on the Z axis"

• "Rotate the Cylinder 45 degrees on the Z axis"

• "Scale the Sphere to [2, 2, 2]"

• "Render the scene at 1920×1080 and save it to /tmp/render.png"

• "Export the scene as a GLB file to /tmp/scene.glb"

• "Run this Blender Python: bpy.ops.mesh.primitive_monkey_add(location=(0,0,2))"

• "Execute the fluid_domain.py script from the library with resolution 128"

• "Start an async bake job for the fluid simulation and tell me the job ID"

• "Undo the last change"

• "Redo what was just undone"

Tool Reference

Scene Inspection

Object Manipulation

Materials

Rendering & Export

History

Python Execution

Script Library

Pre-built scripts in scripts/library/ for use with blender_python_exec via script_path:

See scripts/library/README.md for full argument docs and a dam-break walkthrough.

Tips for physics workflows:

• Prefer create_mesh.py (data API) over bpy.ops.mesh.primitive_*_add in live sessions — the operator path can destabilize view-layer updates around fluid setup.

• Keep Mantaflow liquid modifiers hidden in the viewport to avoid crashes in Blender 4.x.

• Use transport="headless" for heavy physics bakes — this runs scripts in a separate blender -b process.

Safety & Security

Add-on Preferences

In Blender → Edit → Preferences → Add-ons → Blender MCP Bridge:

Advanced Usage

The helper scripts in scripts/ connect directly to the Blender add-on on 127.0.0.1:9876, bypassing the MCP server entirely. Useful for verifying the add-on works:

python3 scripts/blender_scene_info.py
python3 scripts/blender_create_test_cube.py --name TestCube --x 0 --y 0 --z 1 --size 2
python3 scripts/blender_bridge_request.py scene.get_info
python3 scripts/blender_bridge_request.py object.translate --params '{"name":"TestCube","offset":[0,0,2]}'

All scripts accept --host, --port, and --timeout flags.

Run Blender without a GUI for automation:

blender -b --python your_script.py

Where your_script.py starts the MCP bridge:

import sys
sys.path.insert(0, "/path/to/blender-mcp-server")
from addon import CommandHandler, BlenderMCPServer

server = BlenderMCPServer()
server.start()

import socket
s = socket.socket()
s.bind(("127.0.0.1", 9877))
s.listen(1)
s.accept()  # Blocks until shutdown signal

Inline code — create a fluid domain:

{
  "tool": "blender_python_exec",
  "args": {
    "code": "import bpy\nbpy.ops.mesh.primitive_cube_add(size=4, location=(0,0,2))\ndomain = bpy.context.active_object\ndomain.name = 'FluidDomain'\nbpy.ops.object.modifier_add(type='FLUID')\ndomain.modifiers['Fluid'].fluid_type = 'DOMAIN'\nsettings = domain.modifiers['Fluid'].domain_settings\nsettings.domain_type = 'LIQUID'\nsettings.resolution_max = 64\n__result__ = {'domain': domain.name, 'resolution': 64}",
    "args": {"resolution": 64}
  }
}

Script file — set up colliders:

{
  "tool": "blender_python_exec",
  "args": {
    "script_path": "scripts/library/effector.py",
    "args": {
      "objects": ["Ground", "Building_01", "Building_02"],
      "effector_type": "COLLISION"
    }
  }
}

Async bake and poll:

{"tool": "blender_python_exec_async", "args": {"code": "import bpy\nbpy.ops.fluid.bake_all()\n__result__ = {'baked': True}", "timeout_seconds": 1800}}

→ {"job_id": "job-f8e2a1b3"}

{"tool": "blender_job_status", "args": {"job_id": "job-f8e2a1b3"}}

Development

git clone https://github.com/djeada/blender-mcp-server.git
cd blender-mcp-server
pip install -e ".[dev]"

pytest tests/ -v

Project Structure

blender-mcp-server/
├── addon/                        # Blender add-on (TCP server + command handlers + job manager)
├── src/blender_mcp_server/       # MCP server (stdio transport + tool definitions)
├── scripts/
│   ├── library/                  # Reusable Blender scripts for common tasks
│   ├── demos/                    # End-to-end demo scenes
│   └── blender_bridge_request.py # Direct bridge test helpers
├── tests/                        # Unit tests (mocked bpy, no Blender required)
├── docs/                         # Architecture & design docs
├── pyproject.toml
└── README.md

Contributing

1. Fork the repository.

2. Create a feature branch.

3. Add tests for your changes.

4. Run pytest tests/ -v to verify all tests pass.

5. Submit a pull request.

License

MIT