Skip to main content
Glama
deenesjakozh
tattooinmtl

Blender MCP

by tattooinmtl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Blender MCP — Streamable-HTTP bridge for Blender 5.2 LTS

A Model Context Protocol bridge that lets any MCP client (Antigravity, Cursor, Claude Desktop, VS Code 1.101+, MiniMax Code, Windsurf, Continue, Cline, OpenCode, Codex, MCP Inspector, …) drive Blender 5.2 LTS through natural language.

The add-on runs an MCP Streamable-HTTP server inside Blender on a background thread. The client just points at it — no subprocess is spawned, no socket pair to babysit.

Why this shape

  • Single install path inside Blender. The MCP server runs in-process using bpy, so there's no uvx/pipx dance and no socket pair to keep in sync.

  • Streamable HTTP on localhost. Works with every modern MCP client.

  • Hand-rolled MCP server in the add-on. Blender 5.2 LTS bundles Python 3.13 with no external packages by default. A ~300-line MCP server is more portable than dragging in mcp[cli] and editing sys.path.

  • Client-agnostic. No proprietary plugin format. Any MCP client that can hit an HTTP endpoint (or a stdio proxy that does) works.

Related MCP server: blender-mcp

Project layout

blender_addon_mcp/
├── README.md                      ← you are here
├── LICENSE                        ← MIT
├── pyproject.toml                 ← dev tooling for the add-on (ruff, mypy, pytest)
├── .gitignore
├── addon/
│   └── blender_mcp_addon/         ← zips into a Blender-installable .zip
│       ├── __init__.py            ← bl_info, register/unregister, preferences
│       ├── server/
│       │   ├── __init__.py
│       │   ├── mcp_server.py      ← MCP protocol (initialize, tools/list, tools/call, ping)
│       │   ├── transport.py       ← stdlib http.server, runs on a daemon thread
│       │   └── protocol.py        ← JSON-RPC 2.0 + MCP 2025-03-26 types
│       ├── tools/
│       │   ├── __init__.py        ← tool registry
│       │   ├── scene.py           ← scene_info, frame control
│       │   ├── objects.py         ← list, get, create, delete, transform
│       │   ├── materials.py       ← create, assign, modify
│       │   ├── modifiers.py       ← add, set params, remove
│       │   ├── render.py          ← render_image, screenshot_viewport
│       │   └── code.py            ← execute_python (with confirmation)
│       └── utils/
│           ├── __init__.py
│           ├── bpy_helpers.py     ← bpy → JSON serialization
│           └── safe_eval.py       ← ast-validated code execution
├── scripts/
│   ├── install_addon.ps1          ← zip and install into Blender
│   ├── blender_mcp_proxy.js       ← optional stdio/socket ↔ HTTP bridge for
│   │                                Antigravity builds that don't accept `url`
│   └── start_blender_mcp_bridge.ps1  ← start/stop/status lifecycle for the bridge
├── examples/
│   ├── mcp-configs.md             ← copy-paste configs for every major MCP client
│   ├── basic_scene.md
│   ├── material_setup.md
│   └── render_workflow.md
└── docs/
    ├── architecture.md
    ├── blender_5_2_notes.md
    └── tools_reference.md

Quickstart

1. Install the add-on

# clone
git clone https://github.com/tattooinmtl/Blender_MCP.git
cd Blender_MCP

# install the add-on into every Blender version on this machine
pwsh ./scripts/install_addon.ps1

2. Enable the server in Blender

  1. Open Blender.

  2. Edit → Preferences → Add-ons → search "Blender MCP" → check the box.

  3. Set the port (default 8765) and click Start Server (or use the Blender MCP panel in the 3D Viewport sidebar).

  4. The console should print:

    [Blender MCP] Server listening on http://127.0.0.1:8765/mcp

3. Wire up your MCP client

Pick the client you use and paste the matching snippet from examples/mcp-configs.md. The Antigravity url form is the simplest:

{
  "mcpServers": {
    "blender": { "url": "http://127.0.0.1:8765/mcp" }
  }
}

Snippets for Cursor, Claude Desktop, VS Code, MiniMax Code, Windsurf, Continue, Cline, and the MCP Inspector are all in that file.

4. Verify

In any MCP client chat:

Use the blender server: ping.

You should see the agent call tools/call on ping and report an empty successful result. From a terminal:

curl -s -X POST http://127.0.0.1:8765/mcp `
  -H "Content-Type: application/json" `
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

Tools exposed

Tool

Purpose

Read-only

get_addon_info

Capability handshake — name, version, protocol, tools list. Call this first.

yes

scene_info

Scene summary (objects, lights, cameras, frame)

yes

list_objects

List scene objects, optional type filter

yes

get_object

Full object details (location, rotation, scale, modifiers, materials)

yes

create_object

Create primitive (cube, sphere, plane, cylinder, cone, torus, empty, camera, light)

no

delete_object

Delete an object by name

no

transform_object

Set location/rotation/scale

no

set_material

Create or assign a material with a Principled BSDF

no

set_texture

Apply an image file to a material input (base_color, roughness, normal, etc.)

no

import_asset

Import GLB/GLTF/FBX/OBJ/STL/PLY/DAE/USD/X3D/ABC

no

add_modifier

Add a modifier (subdivision, mirror, solidify, array, bevel)

no

remove_modifier

Remove a modifier by name

no

frame_get / frame_set

Read / move the timeline

mixed

render_image

Render the current frame to a file

no

screenshot_viewport

Capture the current viewport

no

execute_python

Run arbitrary bpy code (guarded by ast validation)

no

ping

Health check

yes

See docs/tools_reference.md for the full schema and examples.

Development

# syntax-check the add-on (Blender's Python is at <blender>/python/bin/python.exe)
python -m py_compile addon/blender_mcp_addon/__init__.py
python -m py_compile addon/blender_mcp_addon/server/mcp_server.py
# ...etc

# lint
ruff check addon/
mypy addon/

# test the MCP server in isolation (no bpy required)
pytest addon/tests/ -v

License

MIT. See LICENSE.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Blender MCP VXAI

    VxASI
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables natural language control of Blender 3D through MCP clients, allowing creation, modification, and manipulation of 3D models, animations, and scenes.
    299
    MIT

  • blender-mcp

    sandraschi
    A
    license
    C
    quality
    A
    maintenance
    Enables AI-powered control of Blender through natural language, allowing users to create, manipulate, and automate 3D scenes, objects, materials, animations, and more via Claude or other MCP clients.
    71
    44
    MIT

  • Blender MCP

    tattooinmtl
    A
    license
    Not graded
    quality
    C
    maintenance
    This server enables natural language control of Blender 5.2 LTS through any MCP client, allowing scene inspection, object and material manipulation, rendering, and safe Python execution.
    1
    MIT

  • Blender MCP

    tattooinmtl
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables any MCP client to control Blender 5.2 LTS via natural language, including scene creation, object manipulation, material assignment, rendering, and Python execution.
    MIT