Skip to main content
Glama
Sign In
deenesjakoruzh
blender-mcp

blender-mcp

by josefgoeller-ship-it
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

# blender-mcp

An MCP server that builds Blender .blend files. It reaches Blender two ways:

  • Headless — every call starts a fresh blender --background process. Deterministic, always available, and the right choice for generating files.

  • Live — a small Blender addon opens a local port so the server can drive the Blender window you already have open, and you watch it happen.

Both routes run the same handler code, so a script behaves identically either way. A local web UI lets you upload reference images and run generation jobs with the same tools.

Requirements

Blender

4.2 or newer (developed against 5.1)

Python

3.12+ for the server (Blender brings its own)

uv

dependency and venv management

Related MCP server: blender-chatgpt-mcp

Setup

uv sync                                        # create .venv and install
cp .env.example .env                           # then set BLENDER_MCP_EXECUTABLE
uv run python scripts/build_addon.py --install # build + install the Blender addon

If you skip .env, the server searches your PATH and the standard Program Files/Blender Foundation/Blender <version> folders on every drive, preferring the newest version it finds.

Turning on the live bridge

The addon is installed but idle until you start it:

  1. Open Blender.

  2. Press N in the 3D viewport to show the sidebar.

  3. Open the MCP tab and click Start MCP Bridge.

Tick Start listening on launch in the addon preferences to skip this every time.

Connecting an MCP client

.cursor/mcp.json already registers the server for this project. To make it available everywhere, copy that block into ~/.cursor/mcp.json:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\Users\\josef\\Projects\\blender-mcp", "blender-mcp"]
    }
  }
}

Quality workflow

Generation quality comes from looking, not from a single script dump:

  1. list_references / view_reference — open guide images first

  2. create_blend from studio or product

  3. Build in small run_script steps; apply_material for metal/plastic/rubber/glass/wood

  4. preview_views — multi-angle EEVEE previews; compare to refs with view_image

  5. Fix, preview again

  6. Final render / render_and_view (CYCLES only for finals; EEVEE while iterating)

Local web UI

uv run blender-mcp-web
# open http://127.0.0.1:8765

Upload reference images, enter a prompt, and browse jobs under output/jobs/.

  • With BLENDER_MCP_LLM_API_KEY in .env — the site runs a bounded multimodal agent that calls the same Blender tools (OpenAI-compatible or Anthropic via BLENDER_MCP_LLM_PROVIDER).

  • Without a key — uploads and job pages still work; open the job in Cursor and ask the MCP agent to build from output/jobs/<id>/refs.

Tools

Tool

Purpose

blender_status

Install, output/refs dirs, templates, materials, live bridge

list_references / view_reference / add_reference

Guide image library under output/refs

create_blend

New file from a template + optional script

run_script

Arbitrary bpy Python

apply_material

Procedural presets: metal, plastic, rubber, glass, wood

inspect_blend

Scene graph / materials / cameras / lights

preview_views

Multi-angle EEVEE previews for critique

render / render_and_view

Still PNG; the latter returns the image to look at

view_image / view_preview

Load a PNG for vision

viewport_screenshot

Live viewport capture

list_outputs

Files under output/

open_in_live_session

Open a .blend in the live Blender window

Writing scripts

run_script and the script argument of create_blend execute in a namespace where bpy, mathutils, math, D (bpy.data) and C (bpy.context) are already bound. Send data back by assigning to result or calling emit(value).

Templates

Name

What you get

empty

Nothing at all

default

Blender's startup scene: cube, camera, light

studio

Grey floor, three-point area lighting, 50mm camera, 1920×1080

product

White seamless backdrop, soft lights, 85mm product framing

Layout

addon/blender_mcp_addon/   Blender extension + shared handlers (incl. preview_views)
src/blender_mcp/
  server.py                MCP tools
  refs.py                  reference image library
  materials.py             procedural material presets
  templates.py             starter scenes
  agent/                   bounded multimodal generation loop
  web/                     FastAPI UI (templates + static)
  headless.py / bridge.py  Blender process / live socket
scripts/                   build, install, verification
output/                    .blend files, renders, refs/, jobs/

Testing

uv run pytest -m "not blender"   # fast
uv run pytest                    # includes real Blender runs
uv run python scripts/check_server.py
uv run python scripts/verify_live_bridge.py

Notes and limits

  • run_script executes arbitrary Python inside Blender. Keep the bridge on loopback.

  • Long renders block the live UI until they finish.

  • viewport_screenshot is live-only.

  • Cycles uses CPU unless you enable a GPU device in Blender preferences.

  • The web agent needs a multimodal model that supports tool calls and images.

Licence

MIT

Available Tools

16 tools
add_referenceA

Copy an image file into the reference library under output/refs.

Args: source_path: Existing image on disk (absolute or under the output folder). name: Optional destination filename. group: Optional subfolder name for organising guides.

Inputs: source_path (required), name, group.

apply_materialA

Apply a procedural material preset (metal, plastic, rubber, glass, wood) to a mesh.

Args: object_name: Mesh object name in the scene. preset: One of the presets from blender_status.materials. color: Optional RGB or RGBA floats 0-1. blend_file: Open this file first (forces headless). save_as: Save after applying. target: "auto", "live" or "headless".

Inputs: preset (required), object_name (required), color, target, +2 more.

blender_statusC

Report the Blender install, output folder, live-bridge state, templates and materials.

Inputs: no named parameters.

create_blendA

Create a new .blend file from a starter template and save it.

Args: path: Destination, relative to the output folder unless absolute. A ".blend" suffix is added when missing. template: empty, default, studio, or product. script: Optional extra bpy code run after the template. compress: Write a compressed .blend.

Inputs: path (required), script, compress, template.

inspect_blendA

Describe a scene: objects, transforms, materials, cameras, lights and render settings.

Args: blend_file: Inspect this file. Leave empty to inspect the live session instead. include_objects: Include the per-object breakdown, not just the counts. target: Where to look when no file is given.

Inputs: target, blend_file, include_objects.

list_outputsC

List the files produced so far in the output folder.

Inputs: pattern.

list_referencesA

List reference guide images under output/refs (optionally one group folder).

Inputs: group.

open_in_live_sessionB

Load a .blend into the Blender window the user has open, so they can see it.

Inputs: blend_file (required).

preview_viewsB

Render multi-angle EEVEE previews (front, three_quarter, side, top) for critique.

Args: blend_file: .blend to open and preview. output_dir: Folder under output/ for the PNGs. width: Preview width. height: Preview height. samples: Low sample count for speed. engine: Prefer EEVEE. target: Usually headless.

Inputs: blend_file (required), width, engine, height, +3 more.

renderA

Render a still image and write it to disk. Prefer render_and_view so you see it.

Args: output: PNG destination, relative to the output folder unless absolute. blend_file: Render this file rather than the live session. Forces a headless run. engine: "EEVEE", "CYCLES" or "WORKBENCH". EEVEE for iteration; CYCLES for finals. samples: Sample count. Keep it low for previews. width: Output width in pixels. height: Output height in pixels. frame: Frame to render. Defaults to the scene's current frame. transparent: Render the world background as alpha. target: "auto", "live" or "headless".

Inputs: frame, width, engine, height, +5 more.

render_and_viewC

Render a still and return the image so you must look at it.

Args: output: PNG destination under the output folder. blend_file: Optional .blend to open first. engine: Prefer EEVEE while iterating. samples: Sample count. width: Width in pixels. height: Height in pixels. target: "auto", "live" or "headless".

Inputs: width, engine, height, output, +3 more.

run_scriptA

Run Python against Blender's bpy API.

bpy, mathutils, math, D and C are pre-bound. Assign to result or call emit(value) to send data back; print() output is captured too.

Args: code: The Python to execute. blend_file: Open this .blend first. Supplying it forces a headless run. save_as: Save the file here when the script finishes. target: "auto", "live" or "headless".

Inputs: code (required), target, save_as, blend_file.

view_imageC

Load a rendered image so it can actually be looked at.

Args: path: Image path, relative to the output folder unless absolute.

Inputs: path (required).

viewport_screenshotB

Capture the live Blender window's 3D viewport as it currently looks.

Requires the MCP Bridge addon to be running in an open Blender session.

Inputs: output.

view_previewB

Look at one preview PNG from preview_views or a render.

Args: path: Image path relative to output or absolute.

Inputs: path (required).

view_referenceB

Look at a reference/guide image so you can match it while modeling.

Args: path: Path relative to output/refs, or absolute.

Inputs: path (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool targets a distinct action: status, references (list/view/add), file creation, scripting, material application, scene inspection, rendering (with variants for preview and view), screenshot, output listing, and live session opening. Even similar tools like render and render_and_view are clearly differentiated by purpose and parameters.

    Naming Consistency5/5

    All tool names use snake_case with a verb_noun pattern (e.g., list_references, create_blend, apply_material). The naming is predictable and follows a consistent structure, making it easy for an agent to infer functionality from the name.

    Tool Count5/5

    With 16 tools, the set covers a broad range of Blender operations—file management, references, materials, rendering, scripting, and inspection—without being overwhelming. The count is well-scoped for its domain: enough to handle common tasks without unnecessary duplication.

    Completeness3/5

    The tool surface covers many essential tasks but lacks direct tools for object creation (e.g., adding primitives), transformation (move/rotate/scale), or animation. While run_script can fill these gaps via Python, the explicit tool set leaves notable gaps for a modeling server, forcing agents to fall back to scripting for basic operations.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Blender MCP

      ageless-h
      A
      license
      A
      quality
      D
      maintenance
      MCP server for AI-assisted Blender automation, providing layered tools for perception, declarative and imperative writing, and fallback operations.
      29
      85 PyPI
      6
      MIT

    • blender-chatgpt-mcp

      bakaroart
      A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants like Codex or ChatGPT to inspect and control a local Blender scene, including creating objects, editing materials, setting cameras and lights, rendering previews, and saving safe copies of .blend files.
      1
      MIT

    • Blender MCP Server

      sattua
      F
      license
      B
      quality
      D
      maintenance
      MCP server that controls Blender via HTTP bridge, enabling 3D modeling, animation, and export operations from Cursor agent.
      32
      1
      -

    • blender-lab-mcp-client

      A-to-PC
      A
      license
      A
      quality
      D
      maintenance
      MCP server for Blender that connects to the official Blender Lab add-on, exposing 27 tools for scene manipulation, object editing, materials, rendering, and Python execution through the add-on's actual wire protocol.
      27
      1
      MIT