Skip to main content
Glama
blender-lab-mcp-client

blender-lab-mcp-client

by A-to-PC

blender-lab-mcp-client

An MCP client that speaks the official Blender.org "Blender Lab" MCP add-on's actual wire protocol, exposing the same 27 tools as djeada/blender-mcp-server — but working against blender.org/lab/mcp-server instead of that project's own bundled add-on.

Why this exists

There are (at least) two unrelated "Blender + MCP" projects that happen to share a name, a default port, and a similar pitch:

  1. djeada/blender-mcp-server — ships a matched pair: its own Blender add-on and a Python MCP client, talking a newline-delimited {"id", "command", "params"} / {"success", "result"} protocol over localhost:9876.

  2. The official Blender Lab add-on (blender.org/lab/mcp-server, maintainer "Blender Authors") — a completely separate project. It also listens on localhost:9876, but only ships the add-on side. It speaks null-byte-delimited {"type": "execute", "code": ..., "strict_json": ...} requests and {"status": "ok"|"error", "result": ...} responses, has no built-in named-command dispatcher (it just executes raw Python against bpy), and closes its TCP connection after every single request.

If you install the official Blender Lab add-on but configure an MCP client pointed at djeada/blender-mcp-server (e.g. via uvx blender-mcp-server), every tool call fails with something like:

Extra data: line 1 column 51 (char 50)

or, on the next call:

Lost connection to Blender: Blender connection closed

That's not a flaky connection, a stale process, or a Blender bug — it's two unrelated protocols talking past each other. djeada's client sends a newline-terminated request the add-on never recognizes; the add-on times the client out, sends back a small null-byte-terminated error, and the client's readline() chokes on the stray null byte immediately after the JSON object.

This package re-implements each of the original 27 MCP tools by generating the equivalent bpy Python and sending it through the Blender Lab add-on's actual protocol, so the tool names, parameters, and behavior stay the same — only the wire format underneath changes.

Related MCP server: blender-mcp

Install

  1. Install the official Blender Lab MCP add-on in Blender (Edit → Preferences → Add-ons → search "MCP", or via the Extensions platform) and confirm it's listening on 127.0.0.1:9876 (Add-on preferences → Start Server).

  2. Install this package:

    git clone https://github.com/A-to-PC/blender-lab-mcp-client.git
    cd blender-lab-mcp-client
    pip install -e .
  3. Point your MCP client at it. For a mcp.json-style config:

    {
      "servers": {
        "Blender": {
          "type": "stdio",
          "command": "blender-lab-mcp-client"
        }
      }
    }

    Or run directly from source without installing, via uv:

    {
      "servers": {
        "Blender": {
          "type": "stdio",
          "command": "uv",
          "args": ["run", "--project", "/absolute/path/to/blender-lab-mcp-client", "blender-lab-mcp-client"]
        }
      }
    }

Tool reference

Same 27 tools as upstream — see djeada/blender-mcp-server's tool reference for the full table (scene inspection, object manipulation, materials, rendering/export, history, Python execution, async jobs). Names and parameters are unchanged; only the transport underneath is different.

Known limitations

  • blender_python_exec_async / blender_job_status / blender_job_cancel / blender_job_list (bridge transport only) are faked as synchronous. The add-on's real deferred-job mechanism requires the executed code itself to set a check_is_finished callable, which isn't practical to synthesize generically from arbitrary submitted code. Async calls against the live Blender session actually run synchronously and are immediately reported as "succeeded". For genuinely long-running work (physics bakes, heavy sims), use transport="headless" instead — that path runs a separate blender -b background process and is unaffected by this limitation.

  • One connection per request. The add-on closes its socket after every response, so this client can't reuse a persistent connection — each tool call opens a fresh TCP connection. This matches the add-on's actual design; it isn't a performance shortcut that could be "fixed" client-side.

  • Tested against Blender 5.2 LTS with the Blender Lab add-on. Object/material helper code uses standard bpy.ops.* calls and should work on any recent Blender version, but hasn't been verified across a version matrix.

Credit

Forked from djeada/blender-mcp-server (MIT licensed) by Adam Djellouli — the MCP tool surface (names, parameters, descriptions) and the headless.py background-execution transport are carried over unchanged. Only server.py's BlenderConnection and the command-to-bpy-code translation layer are new, to target the official Blender Lab add-on's protocol instead of upstream's own bundled add-on.

License

MIT — see LICENSE.

Available Tools

27 tools
blender_export_fbxB

Export the scene as FBX. Provide the output file path.

Inputs: filepath (required). Returns: result

blender_export_gltfB

Export the scene as glTF/GLB. Provide the output file path.

Inputs: filepath (required). Returns: result

blender_export_objB

Export the scene as OBJ. Provide the output file path.

Inputs: filepath (required). Returns: result

blender_history_redoA

Redo the last undone operation in Blender.

Inputs: no named parameters. Returns: result

blender_history_undoA

Undo the last operation in Blender.

Inputs: no named parameters. Returns: result

blender_job_cancelA

Cancel a running or queued async Blender job. The job's cancel_event is set; scripts that check it will stop gracefully.

Inputs: job_id (required). Returns: result

blender_job_listA

List known async Blender jobs with their IDs, statuses, and creation timestamps.

Inputs: no named parameters. Returns: result

blender_job_statusA

Get the status of an async Blender job. Returns job_id, status (queued/running/succeeded/failed/cancelled), timestamps, result, stdout, stderr, and error. Poll this after starting a job with blender_python_exec_async.

Inputs: job_id (required). Returns: result

blender_material_assignB

Assign an existing material to an object.

Inputs: object (required), material (required). Returns: result

blender_material_createA

Create a new material. Optionally set an initial base color as [r, g, b] with values 0-1.

Inputs: name, color. Returns: result

blender_material_listA

List all materials in the Blender file.

Inputs: no named parameters. Returns: result

blender_material_set_colorA

Set the base color of a material. Color is [r, g, b] with values 0-1.

Inputs: name (required), color (required). Returns: result

blender_material_set_textureC

Set an image texture as the base color of a material. Provide the file path to the image.

Inputs: name (required), filepath (required). Returns: result

blender_object_createC

Create a new mesh object in Blender. Supported types: cube, sphere, cylinder, plane, cone, torus.

Inputs: name, size, location, mesh_type. Returns: result

blender_object_deleteC

Delete an object from the Blender scene by name.

Inputs: name (required). Returns: result

blender_object_duplicateC

Duplicate an object in the Blender scene. Optionally provide a new name.

Inputs: name (required), new_name. Returns: result

blender_object_get_hierarchyA

Get the parent/child hierarchy of objects. If name is provided, returns the subtree for that object. Otherwise returns the full scene hierarchy.

Inputs: name. Returns: result

blender_object_get_transformA

Get the position, rotation, and scale of a Blender object by name.

Inputs: name (required). Returns: result

blender_object_rotateA

Set the rotation of an object. Provide rotation as [x, y, z] angles. By default angles are in degrees.

Inputs: name (required), rotation (required), degrees. Returns: result

blender_object_scaleB

Set the scale of an object. Provide scale as [x, y, z].

Inputs: name (required), scale (required). Returns: result

blender_object_translateA

Move an object. Provide either 'location' for absolute positioning or 'offset' for relative movement.

Inputs: name (required), offset, location. Returns: result

blender_python_execA

Execute a Python script in Blender's context synchronously. Provide either 'code' (inline Python string) or 'script_path' (path to a .py file), not both. The script has access to 'bpy', 'mathutils', and an 'args' dict with your supplied arguments. Set 'result' in the script to return a JSON-serializable value. Returns the result, captured stdout/stderr, and execution duration. Use transport='bridge' for the live Blender add-on session, or transport='headless' to run the script in a separate blender -b process. For long-running tasks like baking, use blender_python_exec_async.

Inputs: args, code, transport, blend_file, +3 more. Returns: result

blender_python_exec_asyncA

Start a long-running Python script in Blender asynchronously. Same parameters as blender_python_exec. Returns a job_id immediately. Use blender_job_status to poll for completion, and blender_job_cancel to abort. The script can check 'cancel_event.is_set()' to detect cancellation. Ideal for fluid baking, rigid body simulation, or heavy scene generation. Use transport='headless' to run the job in a separate background Blender process.

Inputs: args, code, transport, blend_file, +3 more. Returns: result

blender_render_animationA

Render an animation. Optionally set output path, frame range, and render engine. Use transport='bridge' for the live Blender add-on session, or transport='headless' with a blend_file to render in a separate background Blender process.

Inputs: engine, frame_end, transport, blend_file, +3 more. Returns: result

blender_render_stillA

Render the current scene as a still image. Optionally set output path, resolution, and render engine (BLENDER_EEVEE, CYCLES, etc.). Use transport='bridge' for the live Blender add-on session, or transport='headless' with blend_file='/path/to/file.blend' to render in a separate background Blender process.

Inputs: engine, transport, blend_file, output_path, +3 more. Returns: result

blender_scene_get_infoA

Get information about the current Blender scene including name, frame range, render engine, resolution, and object count.

Inputs: no named parameters. Returns: result

blender_scene_list_objectsA

List all objects in the current Blender scene. Optionally filter by type (MESH, CAMERA, LIGHT, EMPTY, CURVE, etc.).

Inputs: type. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 27 tools

    Disambiguation5/5

    Each tool maps to a distinct Blender domain (scene, object, material, render, export, history, python, jobs) with clear action verbs. Even closely related tools like render_still vs render_animation and python_exec vs async are clearly differentiated by purpose and parameters.

    Naming Consistency5/5

    All tools follow the exact pattern 'blender_<domain>_<action>' with snake_case throughout. Naming is perfectly consistent, making it easy to predict tool names and group functionality.

    Tool Count4/5

    With 27 tools, the count is slightly on the heavier side but justified given the breadth of Blender capabilities covered (scene, objects, materials, rendering, exports, Python execution, async jobs, undo/redo). No redundant tools; each serves a distinct need.

    Completeness4/5

    The surface covers core scene management, object transforms, material handling, rendering, exports, and Python integration, which are the primary workflows. Minor gaps exist (e.g., creation of lights/cameras only via generic mesh creation, no modifier support), but agents can route around these via blender_python_exec.

    Related MCP Connectors

    Related MCP Servers