Blender MCP

Enhanced MCP developer preview

This branch packages an enhanced Blender MCP workflow for agentic Blender work. It keeps the upstream live Blender add-on/server model and adds saved-file/headless execution, selectable command-line backends, runtime Blender Python API lookup, subprocess/capture hardening, and benchmark tooling.

This is a modified distribution of Blender Lab’s Blender MCP project. See NOTICE.md for provenance and SECURITY.md for the execution-risk model. Public bpy.dev website assets will live in a separate repository.

BlenderBench result

The compilation covers 27 tasks / 270 rounds. Its on-video “CLIP accuracy” label means CLIP image-embedding cosine similarity, not literal accuracy. The linked immutable H.264 video is 848×464, 134.9 seconds, and 10,161,884 bytes; SHA-256: 04966320de680203baed6c01c3e211059350454139dc8a802c557cce24815c17.

What is enhanced

• Saved-file tools: _for_cli tools operate on .blend files in fresh subprocesses without requiring a live Blender UI session.
• Backend selection: use a Blender executable backend or a standalone bpy Python backend with BLENDER_MCP_CLI_BACKEND.
• Runtime API lookup: agents can query exact signatures, enums, defaults, and availability from the active Blender/bpy runtime instead of relying only on bundled docs.
• Process isolation: command-line executions are bounded by explicit timeouts, output caps, compact JSON framing, and source-file overwrite checks. This is crash/process-state isolation, not an OS sandbox.
• Benchmark tooling: deterministic token-efficiency tasks, exploratory creative comparison harnesses, and a portable model-neutral full-27 BlenderBench runner with pinned inputs and post-generation scoring.

Current publication status

Developer-preview cleanup is in progress. Before publishing, complete PUBLICATION_CHECKLIST.md, especially package naming, fresh-clone install smoke tests, and tracked-file secret scanning.

Overview

A lightweight MCP (Model Context Protocol) server for Blender. It offers a natural language interface with Blender’s Python API, improving access to documentation, and allowing users to explore and understand complex setups.

Read the documentation at blender.org/lab/mcp-server

---

The project is deliberately small, maintainable, and does no more than necessary. It has two components that communicate over a TCP socket:

• A Blender add-on that runs inside Blender and executes live-scene requests.
• An MCP server that runs as a separate process, launched by the MCP client (e.g. Llama.cpp).

The data flow is:

MCP Client  ⇐ MCP/stdio ⇒  blender-mcp  ⇐ TCP socket ⇒  Blender Add-on

Blender Add-on

Located in addon/blender_mcp_addon/.

A Blender extension that allows the MCP server to communicate with a running Blender instance. It must be installed and enabled for connected live-scene tools; saved-file _for_cli tools run without it.

The add-on provides a preferences panel for configuring the host, port, and an optional auto-start setting.

Functionality Overview

Note that this is intended to be a fairly minimal add-on.

Connectivity

• Auto-start (optional), is non-blocking any issues can be viewed from the preferences.
• Configurable polling intervals (active and idle rates) from preferences to avoid excessive overhead.
• Client timeout protection - stalled connections are evicted.
• Start/stop operators accessible from the preferences panel.
• Deferred responses are supported only by the interactive add-on server; background mode requires requests to complete synchronously and rejects deferred results.

MCP Server

Located in mcp/blmcp/, installed as a Python package with the entry point blender-mcp.

An MCP client launches this process and communicates with it over stdio. The server connects to the add-on’s TCP socket to relay requests to Blender.

mcp/blmcp/data/ Data files bundled with the package.

• prompts.yml provides instructions sent to the LLM at connection time.
• api/ contains Blender Python API reference in RST format.
• manual/ contains Blender user manual excerpts in RST format.

mcp/blmcp/tools/ Each tool is a single module, auto-discovered at startup. Modules ending in _toolcode contain code that runs inside Blender (sent to the add-on for execution) and are skipped during discovery.

mcp/blmcp/tools_helpers/ Shared utilities used by tools. Tools should not import from each other; shared logic lives here instead.

Command-line Backends

Tools whose names end in _for_cli open a saved .blend file in a fresh subprocess. They use the Blender executable by default, or a standalone bpy Python when selected with environment variables. Live tools such as execute_blender_code still use the add-on and the open Blender session.

This native MCP client configuration launches the server with the standalone backend. Replace both absolute placeholders for your installation:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/blender_mcp/mcp",
        "run",
        "blender-mcp"
      ],
      "env": {
        "BLENDER_MCP_CLI_BACKEND": "bpy",
        "BLENDER_MCP_BPY_PYTHON": "/absolute/path/to/python-with-bpy"
      }
    }
  }
}

See Command-line Blender and standalone bpy backends for installation, compatibility, runtime boundaries, troubleshooting, and security guidance.

Tools

See readme_tools.rst for the tools the MCP server exposes.