Blender Toolset MCP

Control Blender through one self-contained Model Context Protocol server. Create and edit geometry, build materials, animate objects, configure physics, render images, inspect scenes, search Blender documentation, and work with asset services from an MCP-compatible client.

The Python distribution and executable are named blender-unified. All implementation modules, Blender bridges, and searchable documentation ship in this repository and its wheel.

• 243 distinct Blender tools, organized by task.

• 3 discovery tools for finding operations and reading their exact schemas.

• 270 implementation routes, including alternatives for overlapping operations.

• One public stdio MCP endpoint controlling a shared Blender scene.

• Local scene operations work without provider accounts. External asset and generation services have their own requirements.

Installation · Client setup · Capabilities · Examples · Configuration · Testing · Troubleshooting

Requirements

Other operating systems and Blender versions have not received the same live audit. The combined host requires Blender's GUI event loop; do not launch it in background mode. Individual background inspection tools start separate Blender processes when needed.

Related MCP server: blender-lab-mcp-client

Installation

1. Get the project

git clone https://github.com/sajjadbeygi/blender-toolset-mcp.git
cd blender-toolset-mcp
uv sync

2. Generate a local configuration

uv run blender-unified-configure --output local.json

This creates the settings for the MCP server and its Blender host. It records the Python interpreter's absolute path. Regenerate it if you move the checkout or replace the environment; preserve custom settings before regenerating.

3. Start Blender

uv run blender-unified-host --config local.json

The launcher finds blender on PATH or uses the standard macOS application path. To choose an executable explicitly:

uv run blender-unified-host --config local.json --blender /path/to/blender

The launcher opens a new factory-startup Blender window, registers the packaged bridges for that session, and prints BLENDER_UNIFIED_READY when they are ready. It does not install persistent addons or save Blender preferences. Close this window to stop the bridges.

Open your project in that window after startup, or use the file tools. Save work explicitly before closing Blender.

Install from a wheel

Build from this checkout:

uv build
python -m pip install dist/blender_unified-0.3.0-py3-none-any.whl
blender-unified-configure --output local.json
blender-unified-host --config local.json

The installed package includes the code, bridges, documentation corpus, and license notices. A Git checkout is not needed to run the installed wheel. This guide does not assume a PyPI release is available.

Connect your MCP client

Keep the Blender host running, then configure your client to launch the MCP endpoint. On macOS or Linux, a typical configuration is:

{
  "mcpServers": {
    "blender-unified": {
      "command": "/ABSOLUTE/PATH/blender-toolset-mcp/.venv/bin/blender-unified",
      "args": [
        "--config",
        "/ABSOLUTE/PATH/blender-toolset-mcp/local.json"
      ]
    }
  }
}

Use your client's configuration format and real absolute paths. On Windows, the environment's executable is under .venv/Scripts/. Restart or reconnect the client after changing settings.

The host and endpoint are separate processes: the host opens Blender; the endpoint exposes MCP over stdin/stdout. Both must read the same configuration. Client configuration is not installed automatically.

Check the connection

Ask your client to call:

system.status()
scene.inspect()
viewport.screenshot(max_size=800)

system.status confirms component discovery and tool counts. scene.inspect verifies an actual Blender connection, and the screenshot verifies that the intended scene is visible.

Capabilities

Find the exact operations at runtime instead of guessing parameters:

system.find_tools(query="keyframe")
system.find_tools(query="material")
system.describe_tool(name="object.inspect")

The full inventory contains all tool names, implementation choices, and input/output schemas. Availability of an operation does not imply that every parameter combination, extension, provider, or Blender version has been verified.

Example workflow

These are MCP calls to make through your client, rather than shell commands:

object.create_object(type="CUBE", name="Example", location=[0, 0, 1])
transform.set_location(object_name="Example", location=[1, 2, 3])
object.inspect(object_name="Example")
viewport.screenshot(max_size=800)
file.save_file(filepath="/ABSOLUTE/PATH/example.blend")

A direct API operation can use the Python tool:

code.execute(
  code="import bpy\nresult = {'objects': len(bpy.data.objects)}",
  implementation="reference"
)

Example requests for an assistant:

• “Create a simple studio scene with a cube, a floor, a camera, and area lighting.”

• “Inspect this mesh, find its modifiers, and show me a viewport screenshot.”

• “Add location keyframes and switch their interpolation to linear.”

• “Find a wood texture on Poly Haven and apply it to the selected object.”

For multi-step changes, inspect the current scene first, verify the result, and save explicitly.

Configuration

The package contains four capability components. They run as isolated workers and connect to bridges in the same Blender process.

All default bridge sockets bind to loopback. Choose another block of four ports when running multiple instances:

uv run blender-unified-configure --output local.json --port-base 19876

The default selection order is modeling, authenticated, reference, then assets. An operation with multiple implementations accepts an optional selector:

object.inspect(object_name="Example", implementation="authenticated")

To override the default for one operation, edit the generated configuration's routes object:

{
  "routes": {
    "object.inspect": "authenticated"
  }
}

This is a configuration fragment, not a replacement for the complete generated file. Keep its engines and priority settings. Invalid routes fail at startup.

Different implementations can have different parameter and return shapes. Use system.describe_tool to inspect the selected branch. Calls are serialized across components. The gateway does not retry mutations or automatically switch implementations after a failure; implementation-specific retry behavior may still apply. Inspect the scene after a timeout before repeating a mutation.

Blender executable for background tools

The background inspection and execution tools use BLENDER_PATH, falling back to blender on PATH. Set it in the MCP server's environment, for example in a client's env configuration:

{
  "env": {
    "BLENDER_PATH": "/Applications/Blender.app/Contents/MacOS/Blender"
  }
}

Selecting the host with --blender does not set this separate worker environment variable.

Updating an existing installation

Version 0.3 uses capability-based component identifiers. Regenerate configurations created before 0.3, reapply custom ports/environment settings/routes, and restart both host and endpoint. Update explicit implementation selectors to the identifiers in the table above. Catalog metadata uses implementation_routes and tool_name.

External services

The asset component exposes integration controls in Blender's sidebar. Some authenticated routes read BLENDERMCP_* credential variables from the Blender process. Configuration of one route does not automatically configure every alternative route. Check a provider's status tool before calling it, and inspect the tool description for its prerequisites.

No paid generation jobs were submitted during verification. A disabled integration or missing credential is not a successful end-to-end provider test.

Data, execution, and privacy

• Blender Python executes with the privileges of the Blender process. This package is not a sandbox.

• Security checks differ between components; authentication on one bridge does not protect the others.

• Telemetry collection defaults to disabled, with temporary Blender consent preferences off. The gateway adds no telemetry.

• Feedback persistence requires telemetry consent and is not verified with the default opt-out configuration.

• Runtime state and pairing tokens live under .runtime/ beside the configuration and are excluded from Git.

• Provider tools contact external services when called. Local modeling and bundled documentation searches do not require provider accounts.

• Generated settings, credentials, virtual environments, caches, and built distributions are excluded from the repository.

MCP behavior

Images and structured results are preserved. Viewport captures can return native MCP image blocks. The endpoint also exposes resources, templates, and prompts:

Tool-time elicitation and progress forwarding are supported. Sampling, resource subscriptions, and dynamic catalog-change notifications are not implemented. Restart after changing the catalog.

Testing and verification

The recorded live audit covers 270 implementation routes on Blender 5.2.2 LTS:

The three discovery tools also passed. Of the live passes, 86 include independent scene or output-file assertions; 157 verify valid responses. The 27 blocked routes comprise 25 credential/job-dependent provider operations, the 3D Print Toolbox operation, and feedback persistence. These counts are implementation routes, not distinct public tools.

The report records its test date and environment. It is evidence for those cases, not a guarantee for every operation mode or future provider API. Blender 5.2 annotation points do not support pressure; the stroke tool reports pressure_supported: false.

Python checks

uv run pytest -q
uv run ruff check src scripts tests
uv run blender-unified --config local.json --inventory

Tests cover real MCP subprocesses, schema preservation, routing, output formats, resource and prompt handling, pagination, elicitation, error detection, and serialized execution.

Live smoke test

uv run blender-unified-configure --output smoke-config.json --port-base 20876
uv run blender-unified-host --config smoke-config.json --smoke-report blender-smoke.json

This uses a disposable factory scene to exercise all four components, inspect and mutate an object, search documentation, capture a viewport image, read a resource and prompt, and clean up. The window closes automatically.

Full live audit

uv run blender-unified-configure --output audit-config.json --port-base 24876
BLENDER_PATH=/Applications/Blender.app/Contents/MacOS/Blender uv run blender-unified-host --config audit-config.json --audit-report tool-audit.json

Adjust the executable path for your installation. The audit resets its factory scene between cases, writes fixtures under .runtime/tool-audit, downloads public Poly Haven assets, and closes its window. It leaves provider jobs requiring credentials or payment unsubmitted.

For a targeted rerun, use a separate output file:

uv run blender-unified-host --config audit-config.json --audit-report targeted-audit.json --audit-filter add_geometry_node,list_keyframes

Direct Blender regression tests:

/path/to/blender --background --factory-startup --python-exit-code 1 --python tests/blender_regressions.py

Before publishing audit artifacts, remove local paths and other environment-specific information. The checked-in report has machine-specific paths redacted.

Troubleshooting

When reporting a bug, include the package and Blender versions, operating system, canonical tool name, selected implementation, minimal arguments, and relevant error text. Remove credentials and private scene data.

Repository layout

src/blender_unified/
  server.py, gateway.py, catalog.py   Public MCP endpoint and routing
  engine.py, config.py, settings.py  Component startup and configuration
  host.py, launch.py                Blender host lifecycle
  audit.py, audit_cases.py, smoke.py Live verification
  engines/                          Included capability implementations
    modeling/, assets/, authenticated/, reference/
  bridges/                          Blender-side implementations
  names.json                        Canonical tool-name mapping
  provenance.json                   Source and modification records
scripts/                            Maintenance and compatibility entry points
tests/                              Protocol and Blender regression tests
licenses/                           License texts and source records
inventory.json                      Complete tool schema snapshot
tool-audit.json                     Recorded per-route verification

Development

uv sync
uv run pytest -q
uv run ruff check src scripts tests
uv build

After changing tool definitions, regenerate name mappings with uv run python scripts/refresh_catalog.py, inspect the inventory, and run the affected live tests. Keep schemas and recorded inventory consistent. Do not count unavailable provider flows as passing tests.

License and notices

The package is distributed under AGPL-3.0-or-later. Incorporated code and documentation retain their applicable licenses and attribution in THIRD_PARTY.md, licenses/, and the provenance manifest. These records are retained independently of product branding. They do not represent separately installed runtime packages.