Blender MCP
Provides headless Blender automation for inspecting .blend scenes and rendering preview stills without modifying source scenes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Blender MCP inspect the scene in scene.blend"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
discover and verify Blender;
inspect a
.blendscene through a versioned JSON contract;render a preview still without mutating the source scene; and
expose those capabilities as typed MCP tools.
The project does not accept arbitrary Python or shell commands from MCP clients.
Related MCP server: Maya MCP
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 notesSetup
cd /Users/akki/Desktop/github/blender-mcp
uv sync --python 3.12 --extra devChoose 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-mcpThe 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_statusinspect_scenerender_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 -qRun the real Blender integration suite:
uv run pytest tests/integration/test_blender_adapter.py -qOn 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.
Available Tools
3 toolsget_blender_statusARead-onlyIdempotent
Check whether the configured Blender and bundled adapter are available.
Inputs: no named parameters. Returns: object
inspect_sceneARead-onlyIdempotent
Inspect a project-relative .blend file without modifying it.
Inputs: scene_path (required). Returns: object
render_previewB
Render a PNG preview to a project-relative output path.
Inputs: scene_path (required), output_path (required), max_width, max_height, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: checking environment status, inspecting a blend file, and rendering a preview. No two tools overlap in function.
All tool names follow a consistent verb_noun pattern (get_blender_status, inspect_scene, render_preview), making the intended action obvious.
Three tools is at the low end of the typical well-scoped range, but each serves a distinct function without redundancy. The count feels minimal rather than excessive.
The server lacks any tools for creating, editing, or saving Blender scenes, which are common operations for a Blender integration. The existing tools only cover a narrow inspect-and-render workflow, leaving significant gaps for general-purpose use.
Maintenance
Related MCP Connectors
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Ovanek MCP: Model Context Protocol server for Ovanek platform tools; writes are dry-run by default.
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that allows management and execution of Blender Python scripts, enabling users to create, edit and run scripts in a headless Blender environment through natural language interfaces.11-
- AlicenseBqualityCmaintenanceA local Model Context Protocol server for controlling Autodesk Maya, providing typed tools for scene, modeling, animation, and more without Maya imports in the server process.71312 PyPI36MIT
- AlicenseCqualityDmaintenanceMCP server that enables AI to control Blender 3D, providing 175 typed tools for objects, materials, animation, compositing, and more via the Model Context Protocol.1003MIT
- AlicenseCqualityBmaintenanceEnables secure, local automation of Blender through typed MCP tools for scene, modeling, material, animation, rendering, and file workflows via an authenticated loopback bridge.173MIT