Blender-MCP

What it is · Why not the alternative · Tools · Quick start · Config · Docker · Architecture

Production-grade Blender automation over the Model Context Protocol. Pydantic-validated • Zero telemetry • Async-native • Pytest-covered • Plugin-extensible

Sibling project in the MCP-HUB collection.

🎯 What this is

blender-mcp connects Blender 3D to any MCP-compatible AI assistant (Claude Desktop, Claude Code, Cursor, Continue, Cline, …). After a one-time setup, you tell the assistant what you want, and it drives Blender for you — creating objects, applying materials, lighting the scene, framing cameras, rendering. The assistant takes the wheel; you watch it work.

flowchart LR
    U["🧑 You<br/><i>natural language</i>"]:::user
    AI["🤖 AI Client<br/>Claude · Cursor · Cline"]:::ai
    B["🌉 Bridge Server<br/><i>this package</i>"]:::bridge
    BL["🟠 Blender Addon<br/><i>main-thread exec</i>"]:::blender

    U -->|prompt| AI
    AI <-->|"MCP · stdio / http / sse"| B
    B <-->|"TCP JSON · 127.0.0.1:9876"| BL
    BL -.->|screenshot · render · scene data| B
    B -.->|tool result| AI
    AI -.->|answer| U

    classDef user fill:#2d3436,stroke:#636e72,color:#fff
    classDef ai fill:#0984e3,stroke:#74b9ff,color:#fff
    classDef bridge fill:#6c5ce7,stroke:#a29bfe,color:#fff
    classDef blender fill:#EA7600,stroke:#F5792A,color:#fff

Two halves:

• Bridge server (this Python package, run via uv) — speaks MCP to the AI client.

• Blender addon (blender_addon/blender_mcp.py) — runs inside Blender, executes commands on the main thread.

Related MCP server: BlenderMCP

⚔️ Why use this instead of ahujasid/blender-mcp?

The blender-mcp project pioneered the space. We respect that. We're built for a different audience: studios, technical artists, and pipeline engineers who need verifiable, auditable, production-grade tooling.

If telemetry, validation, tests, audit-ability, or air-gapped deployment matter to you, this is the one to use.

🧰 Tools (v0.4.1)

15 core tools, all Pydantic-validated with full MCP annotations, plus opt-in plugin packs.

🔌 Plugins — opt-in, separately installable

Each plugin is a pip package that registers additional tools via the entry-point system. Install only what you need. All require zero pre-configured secrets at server startup — keys are checked at call time, so the server always boots cleanly.

pip install blender-mcp-polyhaven

pip install blender-mcp-hyper3d
export HYPER3D_API_KEY="your-key"  # https://hyper3d.ai

pip install blender-mcp-sketchfab
export SKETCHFAB_API_KEY="your-token"  # https://sketchfab.com/settings#password

🚀 Quick start

Prerequisites

• Blender 3.0+ (3.6, 4.0, 4.2 LTS all tested)

• Python 3.10+

• uv package manager

  # Windows
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  # macOS / Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh

0 · Clone

git clone https://github.com/Aayushdubey101/Blender-MCP.git
cd Blender-MCP

1 · Install dependencies

From the repo root:

uv sync

2 · Install the Blender addon

1. Open Blender → Edit → Preferences → Add-ons → Install…

2. Pick blender_addon/blender_mcp.py

3. Tick the checkbox next to "Development: Blender MCP"

4. In the 3D viewport press N → MCP tab → ▶ Start MCP Bridge

You should see in Blender's system console:

[MCP Bridge] Listening on 127.0.0.1:9876

3 · Smoke-test the server

uv run blender-mcp

It will block on stdin — that's correct (MCP stdio transport). Press Ctrl-C. A clean run with no errors means you're good.

For a full interactive test, use the official inspector:

npx @modelcontextprotocol/inspector uv run blender-mcp

4 · Wire it into your AI client

A ready-to-copy template is at .mcp.json.example. Copy it, rename to .mcp.json (gitignored), and replace the path.

Replace <path-to-Blender-MCP> with the absolute path to this repo (e.g. C:\Projects\Blender-MCP on Windows, /home/you/Blender-MCP on Linux/macOS).

%APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-Blender-MCP>",
        "run",
        "blender-mcp"
      ]
    }
  }
}

claude mcp add blender -- uv --directory <path-to-Blender-MCP> run blender-mcp

Or add manually to ~/.claude/settings.json:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["--directory", "<path-to-Blender-MCP>", "run", "blender-mcp"]
    }
  }
}

.cursor/mcp.json (or the equivalent config file for your client):

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["--directory", "<path-to-Blender-MCP>", "run", "blender-mcp"]
    }
  }
}

Same shape everywhere — command: uv, args: [--directory <path>, run, blender-mcp]. See your client's MCP docs for the exact config file.

5 · Drive Blender with natural language

With Blender open, addon enabled, Start MCP Bridge running, and your AI client restarted — just ask. The assistant picks the right tools, validates inputs, and executes. You sit back.

You: Build a still-life scene. Put a glossy red sphere on a matte grey plane,
     light it with a warm key light from the right and a cool rim from behind,
     frame a 50mm camera looking down at 30°, then render at 720p with EEVEE.

...and here is the exact tool flow the assistant drives:

sequenceDiagram
    autonumber
    actor You
    participant AI as 🤖 AI Client
    participant Bridge as 🌉 Bridge
    participant Blender as 🟠 Blender

    You->>AI: "Glossy red sphere on grey plane, warm key + cool rim, 50mm cam, 720p"
    AI->>Bridge: blender_ping
    Bridge->>Blender: ping
    Blender-->>Bridge: pong · v4.2 · protocol 1.0
    loop build the scene
        AI->>Bridge: create_primitive · set_material · add_light · set_camera
        Bridge->>Blender: execute on main thread
        Blender-->>Bridge: status success
    end
    AI->>Bridge: blender_render_image (EEVEE, 720p)
    Bridge->>Blender: render frame
    Blender-->>Bridge: PNG preview + metadata
    Bridge-->>AI: inline image
    AI-->>You: "Done — here's your render ✨"

⚙️ Configuration

Every option is an environment variable. None are required; all have sensible defaults. Copy .env.example to .env to customize.

Read-only mode (safe demos)

BLENDER_MCP_READ_ONLY=true uv run blender-mcp

blender_create_primitive, blender_render_image, blender_execute_python, etc. all return a structured "read-only mode" error. Inspection tools still work.

JSON logging (log infra)

BLENDER_MCP_LOG_FORMAT=json uv run blender-mcp

Each line is a single JSON object — ship straight to Loki / Datadog / CloudWatch.

🐳 Docker

For headless / render-farm setups. The container talks to a Blender instance running on the host:

docker compose up --build

The Blender addon must be running on the host (host.docker.internal:9876 inside the container). On Linux the compose file already maps host.docker.internal to host-gateway.

📂 Project layout

Blender-MCP/
├── src/blender_mcp/
│   ├── server.py              # MCP entry point; transport (stdio / http / sse)
│   ├── client.py              # Async TCP client, per-call + persistent modes
│   ├── schemas.py             # Pydantic v2 input models
│   ├── utils.py               # format_error / format_success / read-only guard
│   ├── plugins/               # Plugin loader + BlenderMCPPlugin Protocol
│   ├── _log_formatter.py      # JSON log formatter
│   └── tools/
│       ├── scene.py           # inspection + file-management tools
│       ├── objects.py         # destructive object/material/light/camera tools
│       ├── render.py          # blender_render_image
│       └── code.py            # blender_execute_python (escape hatch)
├── blender_addon/
│   └── blender_mcp.py  # Install this in Blender
├── plugins/
│   ├── polyhaven/             # pip install blender-mcp-polyhaven
│   ├── hyper3d/               # pip install blender-mcp-hyper3d
│   └── sketchfab/             # pip install blender-mcp-sketchfab
├── tests/                     # core test suite
├── docs/
│   └── ARCHITECTURE.md        # Process model, threading, response shape, extensibility
├── examples/
│   └── direct_client_test.py  # Drive the bridge without an MCP client
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml             # uv / build configuration
├── .env.example
├── CHANGELOG.md
├── LICENSE
└── README.md

For deeper internals see docs/ARCHITECTURE.md.

🧪 Development

uv sync --extra dev          # install dev deps
uv run pytest                # core tests, ~2s
uv run pytest --cov=src      # with coverage
uv run ruff check src/       # lint
uv run ruff format src/      # format
uv run mypy src/             # type-check

# Run plugin tests
uv run pytest plugins/polyhaven/tests/    # 23 tests
uv run pytest plugins/hyper3d/tests/      # 44 tests
uv run pytest plugins/sketchfab/tests/    # 33 tests

CI runs the same matrix on every push (Python 3.10 / 3.11 / 3.12).

🗺️ Roadmap

• v0.3.0 ✅ — Plugin architecture, PolyHaven + Hyper3D + Sketchfab plugins, persistent connection, HTTP transport.

• v0.4.x ✅ — SHA256 asset cache, headless --background Blender control, file management tools.

• v1.0.0 — Final polish, full comparison table green on every row.

🔧 Troubleshooting

Open Blender, Preferences → Add-ons, enable Blender MCP, then in the 3D viewport's N-panel → MCP tab → click ▶ Start MCP Bridge.

Change the port in the addon N-panel and set BLENDER_MCP_PORT to match.

Verify the absolute path in claude_desktop_config.json, then fully quit and relaunch Claude Desktop (Cmd-Q / right-click tray icon → Quit).

Pass timeout_seconds=600 (or higher) on the blender_render_image call for heavy Cycles renders. Default is 300s.

Re-install blender_addon/blender_mcp.py in Blender — your addon and server are out of sync.

⭐ Star history

📜 License

MIT — see LICENSE.