Blender MCP

A headless-first Model Context Protocol server for safe, deterministic Blender automation.

Status

This repository is under active development. The first milestone is deliberately small:

1. discover and verify Blender;
2. inspect a .blend scene through a versioned JSON contract;
3. render a preview still without mutating the source scene; and
4. expose those capabilities as typed MCP tools.

The project does not accept arbitrary Python or shell commands from MCP clients.

Design principles

• Headless Blender is the authoritative execution engine.
• MCP tools are thin wrappers around testable application services.
• Blender and the MCP server run in separate Python environments.
• Every Blender request uses a versioned, allowlisted JSON envelope.
• Files are restricted to one configured project root.
• Source scenes are not overwritten by inspection or preview operations.
• Failures return stable codes and request IDs.

Development target

• macOS Apple Silicon
• Blender 5.2 LTS
• Python 3.12
• MCP Python SDK 2.x

Additional platforms and an interactive Blender add-on are intentionally deferred until the headless path is reliable.

Repository layout

src/blender_mcp/    MCP server and application core
blender_adapter/    bundled scripts executed by Blender
schemas/            versioned JSON contracts
fixtures/           reproducible Blender fixtures
tests/              unit, security, integration, and end-to-end tests
docs/               contracts and architecture notes

Setup

cd /Users/akki/Desktop/github/blender-mcp
uv sync --python 3.12 --extra dev

Choose a project root containing the .blend files and preview outputs that the server is allowed to access:

export BLENDER_MCP_PROJECT_ROOT=/absolute/path/to/blender-project
export BLENDER_MCP_BLENDER_EXECUTABLE=/Applications/Blender.app/Contents/MacOS/Blender
uv run blender-mcp

The project root is a security boundary. MCP paths must be relative to it; absolute paths, traversal, symlink escapes, and unexpected file extensions are rejected.

Codex configuration

[mcp_servers.blender]
command = "/opt/homebrew/bin/uv"
args = [
  "run",
  "--project",
  "/Users/akki/Desktop/github/blender-mcp",
  "blender-mcp",
]
cwd = "/Users/akki/Desktop/github/blender-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 300
default_tools_approval_mode = "writes"
required = false

[mcp_servers.blender.env]
BLENDER_MCP_PROJECT_ROOT = "/absolute/path/to/blender-project"
BLENDER_MCP_BLENDER_EXECUTABLE = "/Applications/Blender.app/Contents/MacOS/Blender"

Restart Codex after changing MCP configuration.

M0 tools

• get_blender_status
• inspect_scene
• render_preview

The server deliberately has no arbitrary Python, shell, add-on installation, URL download, or external-asset tool.

Verification

Run tests that do not require Blender:

uv run pytest tests/unit tests/security tests/contract -q

Run the real Blender integration suite:

uv run pytest tests/integration/test_blender_adapter.py -q

On the reference macOS machine, Blender 5.2 can crash during native startup when launched inside the Codex application sandbox. The identical test passes when run through an approved unsandboxed Blender process or directly from Terminal. The launcher classifies an early segmentation fault as BLENDER_CRASHED; it is not reported as an adapter validation failure.

See the frozen M0 contract for the exact boundaries, schemas, errors, and deferred capabilities.