Skip to main content
Glama

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.

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 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.

Available Tools

3 tools
get_blender_statusA
Read-onlyIdempotent

Check whether the configured Blender and bundled adapter are available.

Inputs: no named parameters. Returns: object

inspect_sceneA
Read-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

    A3.8/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: checking environment status, inspecting a blend file, and rendering a preview. No two tools overlap in function.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_blender_status, inspect_scene, render_preview), making the intended action obvious.

    Tool Count4/5

    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.

    Completeness2/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -
    • A
      license
      B
      quality
      C
      maintenance
      A 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.
      71
      312 PyPI
      36
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables secure, local automation of Blender through typed MCP tools for scene, modeling, material, animation, rendering, and file workflows via an authenticated loopback bridge.
      173
      MIT