Skip to main content
Glama
Blender-MCP

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.

Dimension

✅ blender-mcp (this)

ahujasid/blender-mcp

Telemetry

None. Zero phone-home.

Default-on Supabase telemetry

Input validation

Pydantic v2 with extra="forbid" everywhere

None — raw kwargs

Async runtime

Native asyncio, non-blocking

Synchronous socket.recv

Tests

207 passing, 90% coverage

None visible in repo

CI

GitHub Actions on Python 3.10 / 3.11 / 3.12

None

Architecture

Modular package, ~8 files

Monolithic 1186-line server.py

Tool annotations

All 4 MCP hints on every tool

Mostly omitted

Read-only mode

BLENDER_MCP_READ_ONLY=true

None

Structured logging

BLENDER_MCP_LOG_FORMAT=json

Plain strings

Protocol versioning

BRIDGE_PROTOCOL_VERSION="1.0" enforced

None

Docker

Dockerfile + docker-compose.yml

None

Hardcoded third-party keys

None — bring your own

RODIN_FREE_TRIAL_KEY baked into source

Asset integrations

Plugin packages (opt-in, separately versioned)

Baked into core

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.

Tool

Purpose

blender_ping

Confirm Blender + addon reachable, returns versions and protocol

blender_get_scene_info

Scene name, frame range, render engine, object count

blender_list_objects

List objects, optional filter by type (MESH, LIGHT, CAMERA, …)

blender_get_object_info

Full per-object detail (transform, dimensions, materials, mesh/light/camera specifics)

blender_get_viewport_screenshot

Inline PNG of the active viewport

Tool

Purpose

blender_create_primitive

Cube / sphere / cylinder / cone / plane / torus / monkey

blender_transform_object

Set location / rotation / scale (any subset)

blender_delete_object

Remove by name (idempotent)

blender_set_material

Principled BSDF: RGBA, metallic, roughness, optional emission

blender_add_light

POINT / SUN / SPOT / AREA with per-type parameters

blender_set_camera

Location, aim target, focal length, set-active

blender_render_image

Render a frame; returns metadata + inline PNG preview

blender_execute_python

Power-user escape hatch (bpy available, set result to return)

Tool

Purpose

blender_save_file

Save the current .blend (optional target path)

blender_open_file

Open a .blend from disk

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

Tool

Purpose

polyhaven_status

Check plugin status and cache directory

polyhaven_categories

List asset categories (hdris / textures / models)

polyhaven_search

Search PolyHaven's library

polyhaven_download

Download an asset to local cache

polyhaven_apply_texture

Download + apply texture to an object in Blender

pip install blender-mcp-polyhaven

Tool

Purpose

hyper3d_status

Check plugin status and API key configuration

hyper3d_generate_text

Text → 3D model via Rodin API

hyper3d_generate_image

Image → 3D model (URL or local file)

hyper3d_poll

Poll generation status with exponential backoff

hyper3d_import

Poll + download + import GLTF/FBX/OBJ/STL into Blender

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

Tool

Purpose

sketchfab_status

Check plugin status and API key configuration

sketchfab_search

Search Sketchfab's 3D model library by keyword

sketchfab_preview

Get full metadata for a model by UID

sketchfab_download

Download GLTF + import into Blender

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.

Variable

Default

Purpose

BLENDER_MCP_HOST

127.0.0.1

Where the Blender addon is listening

BLENDER_MCP_PORT

9876

Same — match the N-panel value

BLENDER_MCP_LOG_LEVEL

INFO

DEBUG / INFO / WARNING / ERROR

BLENDER_MCP_LOG_FORMAT

text

text for humans, json for log infra

BLENDER_MCP_READ_ONLY

false

true disables every destructive tool

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.

Available Tools

15 tools
blender_add_lightA

Add a light source to the scene.

Supports POINT (omnidirectional), SUN (directional), SPOT (cone), and AREA (panel) lights.

Args: params: AddLightInput with light_type, optional name, location, energy, color, and type-specific settings (spot_size, size, etc.).

Returns: JSON with the light object name and properties.

Example: blender_add_light(light_type="POINT", location=(0, 0, 4), energy=2000)

Inputs: params (required). Returns: result

blender_create_primitiveA

Create a primitive mesh (cube, sphere, cylinder, etc.) in the scene.

Args: params: CreatePrimitiveInput with primitive_type, optional name, location (x, y, z), and size.

Returns: JSON describing the newly created object.

Example: blender_create_primitive(primitive_type="cube", name="MyCube", location=(0,0,1))

Inputs: params (required). Returns: result

blender_delete_objectA
DestructiveIdempotent

Delete an object from the scene by name.

DESTRUCTIVE: permanently removes the object. Idempotent: deleting a missing object returns success with a note.

Args: params: DeleteObjectInput with the exact name of the object to delete.

Returns: JSON confirming the deletion.

Example: blender_delete_object(name="Cube")

Inputs: params (required). Returns: result

blender_execute_pythonA
Destructive

Execute arbitrary Python code inside Blender (escape hatch for advanced ops).

The code runs with bpy already imported. To return data, assign it to a variable named result. Use this only when no dedicated tool fits.

DESTRUCTIVE: arbitrary code can modify or delete anything in the scene.

Args: params: ExecutePythonInput with the code string to execute (max 20,000 chars).

Returns: JSON with the value of result (if set) or a success confirmation.

Example: code = "result = [obj.name for obj in bpy.data.objects if obj.type == 'MESH']"

Inputs: params (required). Returns: result

blender_get_object_infoA
Read-onlyIdempotent

Get detailed information about a specific object by name.

Returns transform, dimensions, material slots, and type-specific data (mesh stats for MESH, light settings for LIGHT, focal length for CAMERA).

Args: params: GetObjectInfoInput with the object name and response_format.

Returns: Markdown summary or JSON with full object properties.

Example: blender_get_object_info(name="Cube")

Inputs: params (required). Returns: result

blender_get_scene_infoA
Read-onlyIdempotent

Get an overview of the current Blender scene.

Returns scene name, frame range, render engine, and total object count.

Args: params: GetSceneInfoInput with response_format ('markdown' or 'json').

Returns: Markdown summary or JSON object describing the scene.

Example: blender_get_scene_info(response_format="json")

Inputs: params (required). Returns: result

blender_get_viewport_screenshotA
Read-onlyIdempotent

Capture a screenshot of the current Blender 3D viewport.

Renders using OpenGL and returns the image inline. Great for inspecting the current state of the scene visually.

Args: params: ViewportScreenshotInput with max_size (default 800px).

Returns: An inline PNG image of the viewport, or an error string if capture fails.

Example: blender_get_viewport_screenshot(max_size=1024)

Inputs: params (required).

blender_list_objectsA
Read-onlyIdempotent

List objects in the current Blender scene, optionally filtered by type.

Args: params: ListObjectsInput with optional object_type filter (e.g. 'MESH') and response_format.

Returns: Markdown table or JSON list of objects with name, type, and location.

Example: blender_list_objects(object_type="MESH", response_format="json")

Inputs: params (required). Returns: result

blender_open_fileA
Destructive

Open a .blend file in Blender, replacing the current scene.

WARNING: Unsaved changes to the current scene will be lost.

Args: params: OpenFileInput with filepath (absolute path to .blend file).

Returns: JSON confirming the file that was opened.

Example: blender_open_file(filepath="/home/user/projects/scene.blend")

Inputs: params (required). Returns: result

blender_pingA
Read-onlyIdempotent

Check whether Blender is running and the bridge addon is reachable.

Use this as the first step before any other tool to confirm the integration is live.

Returns: JSON with status and a message indicating reachability.

Example: blender_ping() → {"status": "success", "result": {"reachable": true}}

Inputs: no named parameters. Returns: result

blender_render_imageA

Render a frame using Blender's render engine and return the result inline.

Blocks until the render is complete. For fast previews use EEVEE; for photorealistic output use CYCLES (much slower — increase timeout_seconds).

Returns both a JSON metadata block and an inline image preview. If output_path is given the full-resolution render is also saved to disk.

Args: params: RenderImageInput with optional frame, output_path, engine override, Cycles sample override, preview size, and timeout.

Returns: List of [metadata JSON string, inline PNG preview Image].

Example: blender_render_image(engine="BLENDER_EEVEE", frame=1, max_preview_size=512) blender_render_image(engine="CYCLES", samples=64, timeout_seconds=600)

Inputs: params (required).

blender_save_fileA
Idempotent

Save the current Blender scene to a .blend file.

Args: params: SaveFileInput with optional filepath. Uses the currently open file path if omitted.

Returns: JSON with the path the file was saved to.

Example: blender_save_file(filepath="/tmp/my_scene.blend") blender_save_file() # saves to current file path

Inputs: params (required). Returns: result

blender_set_cameraA
Idempotent

Configure a camera's position, aim target, and focal length.

Uses the active scene camera if no name is given. Creates a new camera if the scene has none. Optionally points the camera at a 3D target point.

Args: params: SetCameraInput with optional name, location, target (point to aim at), lens (focal length in mm), and set_active flag.

Returns: JSON with the camera name, location, rotation, and lens.

Example: blender_set_camera(location=(5, -5, 3), target=(0, 0, 0), lens=50)

Inputs: params (required). Returns: result

blender_set_materialA
Idempotent

Apply a PBR material to an object using Principled BSDF.

Creates or updates a material with the given base color, metallic, roughness, and optional emission. Assigns it to the first material slot of the object.

Args: params: SetMaterialInput with object_name, color (RGBA), metallic, roughness, optional material_name, and optional emission.

Returns: JSON with the material name and applied properties.

Example: blender_set_material(object_name="Cube", color=(0.2, 0.4, 0.8, 1.0), metallic=0.9)

Inputs: params (required). Returns: result

blender_transform_objectA
Idempotent

Set location, rotation, and/or scale of an existing object.

Any field left as None is left unchanged. This is idempotent — calling with the same values is a no-op.

Args: params: TransformObjectInput with the target object name and any combination of location, rotation_euler, and scale.

Returns: JSON with the updated transform values.

Example: blender_transform_object(name="Cube", location=(1,0,0), scale=(2,2,2))

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: scene overview, object listing, detailed object info, file operations, viewport capture, primitive creation, transformation, deletion, material application, light addition, camera setup, and rendering. The Python escape hatch is explicitly marked as a fallback, avoiding confusion.

    Naming Consistency5/5

    All tools follow a strict blender_verb_noun pattern (e.g., get_scene_info, create_primitive, set_material). This consistent convention makes the tool set predictable and easy to navigate.

    Tool Count5/5

    With 15 tools, the set is well-scoped for a Blender automation workflow. Each tool covers a necessary operation from scene inspection to rendering, and the count remains within the ideal 3-15 range without bloat.

    Completeness4/5

    The tool set covers the full CRUD lifecycle for objects, plus materials, lights, camera, and rendering. Advanced Blender features like modifiers, animation, and mesh editing are not directly exposed, but the blender_execute_python escape hatch covers these gaps, so agents won't hit dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Connects Blender to Claude AI through the Model Context Protocol, enabling AI-assisted 3D modeling, scene creation, and manipulation through natural language commands.
      17
      2
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Connects Blender to AI through the Model Context Protocol to enable prompt-assisted 3D modeling and scene manipulation. It supports object creation, material control, and arbitrary Python code execution directly within the Blender environment.
      22
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to control Blender 3D modeling and rendering through natural language commands via the Model Context Protocol.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Blender to AI assistants through the Model Context Protocol, enabling direct AI control of 3D modeling, scene creation, and manipulation via natural language.
      MIT