Blender MCP

Blender MCP connects Blender to AI assistants through the Model Context Protocol (MCP), allowing AI to directly interact with and control Blender. This enables prompt-assisted 3D modelling, scene creation, and manipulation.

Features

• Two-way communication — Connect AI assistants to Blender through a socket-based server
• Scene inspection — Get detailed information about the current Blender scene and objects
• Object manipulation — Create, modify, and delete 3D objects via AI-generated Python code
• Material control — Apply and modify materials and colours
• Viewport screenshot — Let the AI see the current state of your 3D viewport
• Code execution — Run arbitrary Python / bpy code in Blender from your AI client

Components

blender-mcp/
├── addon.py                  ← Blender addon (install inside Blender)
├── src/
│   └── blender_mcp/
│       ├── __init__.py
│       └── server.py         ← MCP bridge server (runs on your machine)
├── pyproject.toml
├── LICENSE
└── README.md

The system has two parts:

1. Blender Addon (addon.py) — creates a socket server inside Blender that receives and executes commands
2. MCP Server (src/blender_mcp/server.py) — implements the Model Context Protocol and connects to the Blender addon

---

Prerequisites

Requirement	Version
Blender	3.0 or newer
Python	3.10 or newer
uv	latest

Install uv

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal after installing.

Windows (PowerShell)

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Then add uv to your PATH (windows only, restart terminal after):

$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")

Verify uv is installed:

uv --version

---

Installation

Step 1 — Clone the repo

git clone https://github.com/jagathgj/BlenderMCP.git
cd BlenderMCP

Step 2 — Set up the Python environment

uv venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows

Step 3 — Install dependencies

uv pip install mcp

Verify the install:

python3 -c "import mcp; print('mcp installed ok')"

Step 4 — Install the Blender Addon

1. Open Blender
2. Go to Edit → Preferences → Add-ons → Install…
3. Select addon.py from this repo
4. Enable it by checking the box next to Interface: Blender MCP

Step 5 — Start the addon in Blender

1. In the 3D Viewport press N to open the sidebar
2. Click the BlenderMCP tab
3. Click Connect to MCP Server

Step 6 — Configure your AI client

Find the full path to the venv Python:

which python3   # after activating the venv
# e.g. path/to/BlenderMCP/.venv/bin/python3

IBM Bob IDE

IBM Bob IDE uses a specialized mode that provides an optimized workflow for Blender 3D development. It includes scene analysis, viewport inspection, and intelligent code generation for bpy operations.

Step 1: Configure MCP Server in IBM Bob IDE

1. Go to Settings → MCP

2. Add the BlenderMCP server configuration:

{
    "mcpServers": {
        "blender-mcp": {
            "command": "path/to/BlenderMCP/.venv/bin/python3",
            "args": ["path/to/BlenderMCP/src/blender_mcp/server.py"],
            "description": "Connect Blender to AI assistants for 3D scene creation and manipulation"
        }
    }
}

Replace path/to/BlenderMCP with your actual clone path(Refer step 6) in both command and args .

Step 2: Import Bob Mode

1. Go to Settings → Modes

2. Click Import button

3. Select the blender-bob-mode.yaml file from this repository

4. Select "🧊 Blender for 3D" mode from the mode selector in Bob IDE

The Bob mode will automatically use the BlenderMCP server configured in your MCP settings.

---

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "blender-mcp": {
            "command": "path/to/BlenderMCP/.venv/bin/python3",
            "args": ["path/to/BlenderMCP/src/blender_mcp/server.py"]
        }
    }
}

Replace path/to/BlenderMCP with your actual clone path.

Cursor

Go to Settings → MCP and add:

{
    "mcpServers": {
        "blender-mcp": {
            "command": "/path/to/BlenderMCP/.venv/bin/python3",
            "args": ["/path/to/BlenderMCP/src/blender_mcp/server.py"]
        }
    }
}

Windows (Cursor):

{
    "mcpServers": {
        "blender-mcp": {
            "command": "C:\\path\\to\\BlenderMCP\\.venv\\Scripts\\python.exe",
            "args": ["C:\\path\\to\\BlenderMCP\\src\\blender_mcp\\server.py"]
        }
    }
}

VS Code

{
    "mcpServers": {
        "blender-mcp": {
            "type": "stdio",
            "command": "/path/to/BlenderMCP/.venv/bin/python3",
            "args": ["/path/to/BlenderMCP/src/blender_mcp/server.py"]
        }
    }
}

⚠️ Run only one instance of the MCP server at a time (either IBM Bob or Claude Desktop, not both).

Restart your AI client after saving the config.

---

Environment Variables

Variable	Default	Description
BLENDER_HOST	localhost	Host where the Blender addon is running
BLENDER_PORT	9876	Port configured in the Blender addon panel

For a remote Blender instance, add to your MCP config:

{
    "mcpServers": {
        "blender-mcp": {
            "command": "/path/to/.venv/bin/python3",
            "args": ["/path/to/server.py"],
            "env": {
                "BLENDER_HOST": "192.168.1.100",
                "BLENDER_PORT": "9876"
            }
        }
    }
}

---

Available Tools

Tool	Description
ping	Check connectivity with the Blender addon
get_scene_info	Scene name, object count, render engine, frame range
list_objects	All objects; optional type filter (MESH, CAMERA, LIGHT…)
get_object_info	Location, rotation, scale, mesh stats, bounding box
get_viewport_screenshot	Capture the 3D viewport as an image
execute_blender_code	Run arbitrary Python / bpy code inside Blender

---

Example Prompts

• "What objects are in my current Blender scene?"
• "Take a screenshot of the viewport so I can see what's there"
• "Create a red metallic sphere at position (0, 0, 2)"
• "Point the camera at the origin and set it to isometric projection"
• "Add a sun light above the scene and set its strength to 3"
• "List all mesh objects and show their bounding box dimensions"

---

Troubleshooting

ModuleNotFoundError: No module named 'mcp'
The venv Python isn't being used. Make sure the command in your config points to .venv/bin/python3 inside the repo, not a system Python. Run uv pip install mcp inside the activated venv.

Connection closed / MCP error -32000
Usually means the server crashed on startup. Check that mcp is installed and the path to server.py in your config is correct.

Could not connect to Blender
Make sure you clicked Connect to MCP Server in the BlenderMCP panel inside Blender before issuing any commands.

Connection refused on port 9876
Check the port in Blender's panel matches BLENDER_PORT (both default to 9876).

Addon not visible in the sidebar
Press N in the 3D Viewport to reveal the sidebar, then look for the BlenderMCP tab.

Tool calls time out
Break complex requests into smaller steps. Code execution has a 180-second timeout.

Still stuck?
Disable and re-enable the addon in Blender Preferences, then click Connect again.

---

Technical Details

Communication Protocol

Simple JSON over TCP sockets:

• Request: { "type": "<command>", "params": { ... } }
• Response: { "status": "success"|"error", "result": <any> | "message": <str> }

---

Security

The execute_blender_code tool runs arbitrary Python code inside Blender. Always save your work before using it, and only connect to AI services you trust.

---

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

License

MIT © Jagath Jayakumar