Skip to main content
Glama

blender-tether

Let an AI agent drive Blender, headless or live, and check its own work.

Tether is an MCP server plus a small agent that runs inside Blender. The agent runs Python in Blender, reads a text report of the scene, looks at the result from several angles in one image, and fixes what it finds. When no Blender is running it starts its own headless one, so there is no window to click and no add-on to install for the common case. It can also attach to a Blender window you opened.

demo

What it does

  • Starts its own Blender. open launches a headless daemon (factory scene, no user add-ons) in about 2 seconds and closes it after 30 idle minutes or when the agent session ends.

  • Runs Python with a persistent namespace. Define a function once and call it by name. bpy, bmesh, mathutils, numpy and friends are already there. Stale bpy references are dropped when a file loads or undo runs, instead of crashing Blender.

  • Lets the agent verify its work. scene returns a text report (sizes, ground contact, topology, weights, modifiers, animation range...). view renders the scene offscreen, in the background too, as one PNG with several angles, shading modes (solid, wireframe, xray, texture, material) or an animation strip.

  • Finds and imports assets. asset_search and asset_import work with Poly Haven, ambientCG, Sketchfab and Poly Pizza. CC0 only by default. Downloads are HTTPS-only, from allow-listed hosts, capped in size, hash-checked and cached.

  • Generates 3D models from a prompt or pictures with Hyper3D Rodin or Tencent Hunyuan3D, with your own API keys. Nothing is sent, and no credits are spent, until the agent passes accept_cost=True.

  • Fails loudly. Helpers such as tether.select raise with the reason where raw Blender calls silently do nothing (a locked object, a hidden collection, an export that says FINISHED and writes no file).

  • Optional GTA V / FiveM checks through the Sollumz add-on (see below).

Related MCP server: Blender Open MCP

Install

Requirements: Python 3.10+, Blender, and the mcp and Pillow packages. Developed and tested on Windows 11 with Blender 5.2.4 LTS and Python 3.13. macOS and Linux are untested. Tether runs on the MCP Python SDK 1.x (1.28 and later) and on 2.x with the same code: tether/mcp_server.py imports MCPServer (2.x) or FastMCP (1.x), whichever is installed. The install allows mcp>=1.28,<3; the full test suite passes with 1.30.0 and 2.3.0.

pip install git+https://github.com/B7Kompirine/blender-tether

Register it with your MCP client. For Claude Code:

claude mcp add tether -- python -m tether.mcp_server

Any client that reads a JSON config:

{
  "mcpServers": {
    "tether": {
      "command": "python",
      "args": ["-m", "tether.mcp_server"],
      "env": { "TETHER_BLENDER": "C:\\Program Files\\Blender Foundation\\Blender 5.2\\blender.exe" }
    }
  }
}

TETHER_BLENDER is optional: Tether looks on PATH and in the usual install folders first. From a source checkout you can also point the client at python tether/mcp_server.py.

Tools

Tool

What it does

status

Lists running apps (selector, mode, version, busy or idle) and what can be opened. Call it first.

open

Starts Blender and waits for its agent. background=true is the headless daemon, otherwise a window with your settings.

close

Closes a background agent.

run

Runs Python (or a script file with args, cwd, env, blend, clean, grep). Returns output, the value of the last expression and a line-numbered trace on errors.

api_search

Searches the running Blender's own API (bpy.ops, bpy.types, add-ons included). An exact name dumps its parameters.

scene

Read-only scene report. Fields: location, size, ground, rotation, scale, parent, children, hidden, details, materials, modifiers, animation, topology, weights, gta, settings.

view

One PNG of the scene: angles, shading, target, distance, frames, look, image.

asset_search

Searches models, PBR textures and HDRIs.

asset_import

Downloads an asset and brings it into Blender with a target size, a license note and rollback on failure. Also imports a finished generated model (source rodin or hunyuan, id = the job).

generate_start

Starts a text-to-3D or image-to-3D job at Rodin or Hunyuan. Without accept_cost=True it only shows what it would send and what it costs.

generate_status

Polls a job once and, when it is done, downloads the model.

A typical loop for an agent: status → open → api_search → run → scene + view → fix → scene + view.

Modes

  • Headless daemon: open app=blender background=true. Starts clean (--factory-startup), so a user add-on cannot interfere. Use blend= and clean= on run to open a file or return to the factory scene.

  • Windowed Blender: open app=blender starts Blender with your own settings and the agent attached. To attach to a Blender you started yourself, link blender_addon/tether_blender into Blender's scripts/addons folder and enable Tether in Preferences.

  • Other apps: the wire protocol is JSON lines over loopback TCP and does not depend on Python. tether/agent/example_app.py embeds the agent in a Python program and tether/agent/example_node.js does the same in about 70 lines of Node. The protocol is described at the top of tether/agent/__init__.py.

Configuration

Variable

Meaning

TETHER_BLENDER

Full path of the Blender executable.

TETHER_ADDONS

Comma-separated add-ons the headless daemon enables, for example Sollumz. Default: none.

TETHER_SCRIPT_DIRS

Extra folders (separated by ; on Windows, : elsewhere) in which a relative file of run is looked up, after cwd.

TETHER_HOME

State folder. Default ~/.tether.

TETHER_STATS=0

Turns off the call log. It stores counts and timings only, never code or output.

SKETCHFAB_TOKEN, POLYPIZZA_KEY

Keys for the two providers that need them. They can also be put in ~/.tether/assets.json as sketchfab_token and polypizza_key. Never paste a key into a chat.

RODIN_API_KEY, TENCENT_SECRET_ID, TENCENT_SECRET_KEY

Keys for generative 3D (Hyper3D Rodin; Tencent Cloud for Hunyuan3D). Also readable from ~/.tether/assets.json as rodin_key, tencent_secret_id, tencent_secret_key.

Measured numbers

python tools/benchmark.py drives the MCP server the way an agent does and writes real tool output and timings. Medians of three runs on one machine (Ryzen 7 9800X3D, RTX 5070, Windows 11, Blender 5.2.4 LTS) varied like this:

Range of medians

Cold blender -b --factory-startup with an empty script

0.59 to 0.83 s

One run round trip to the running daemon

22 to 30 ms

4-angle 1024 px image from the daemon, warm

76 to 95 ms

Daemon start, once per session

2 to 3 s

These are tool-side times. Inside an agent every call also pays the agent runtime's own overhead, which in my sessions was tens to hundreds of milliseconds, so the saving shows up in jobs that would otherwise start Blender, not in a single call. The runs differ from each other by more than the noise inside one run, so treat single numbers with care.

Compared with blender-mcp

blender-mcp (the "MCP for Blender" add-on, version 1.8 here) is the established tool for the same job. python tools/compare.py drives both through the same MCP stdio harness with the same code. Three runs on the machine above (after the speed fixes), the range of per-run medians, both tools attached to a windowed Blender unless stated:

Tether

blender-mcp

Needs a Blender window

No: headless daemon, ready in 2.5 to 2.8 s. A window is optional (4.2 to 4.9 s)

Yes: a Blender with the add-on running (3.7 to 4.1 s)

print(1 + 1) round trip

12 to 23 ms

54 ms

Scene read (text report / JSON)

21 to 28 ms

53 to 54 ms

Build a 40-object scene with one call

74 to 306 ms

74 to 141 ms

Viewport image, 1024 px

66 to 83 ms

86 to 123 ms

Several angles in one image, headless

80 to 90 ms

not available

Error answer

one line plus a line-numbered trace

JSON wrapped in a "communication error" message

Poly Haven, Sketchfab, Poly Pizza

yes, CC0 by default (also ambientCG)

yes

Generative 3D (Hyper3D, Hunyuan3D)

yes, with your own keys (not yet run against the live services, see below)

yes

Sollumz / GTA V export checks

yes

no

What this does and does not show:

  • Per call, Tether is faster on code and scene reads in a windowed Blender: the other add-on hands commands to Blender's main thread on a 50 ms timer, which sets a floor of about 50 ms per call. Viewport images are about the same (Tether slightly ahead in these runs). Building the scene is a tie within the noise.

  • The larger difference is structural. Tether can start and use its own headless Blender, and its scene report and multi-angle view let an agent check its own work. blender-mcp has a much larger user base, which Tether does not.

  • The two tools return different content (a text report is not a JSON dump, a window screenshot is not a four-angle image), so read the times together with what comes back.

  • Asset downloads are network bound: about 2.5 s for Tether and 2.1 s for blender-mcp for the same Poly Haven texture, one run each. The blender-mcp asset search failed on this machine with an argument mismatch between the server and the installed add-on, so it is not in the table.

  • One machine, one Blender version, a game running in the background, so absolute numbers will differ on yours. Tether's headless print(1 + 1) varied from 5 to 31 ms between runs.

Security

Tether listens on 127.0.0.1 only, on a port the OS chooses. Each agent has a random token that is stored in ~/.tether/apps/<app>-<pid>.json. Anyone who can read that file can run code in that Blender, exactly as the user who started it can, so treat it like any local code execution. The client verifies a registry entry against the process id and creation time before connecting, and removes stale ones. Asset downloads accept HTTPS from allow-listed hosts only, including after redirects, and are capped in size and time.

Generative 3D

generate_start provider=rodin prompt="a wooden barrel"           -> NOT SENT, shows the cost
generate_start provider=rodin prompt="a wooden barrel" accept_cost=true  -> job rodin-<id>
generate_status job=rodin-<id>                                    -> waiting / running / done (downloads the glb)
asset_import app=blender source=rodin id=rodin-<id> target_size=1.0
  • Rodin (rodin): text or up to 5 pictures, tier default Gen-2.5-Low (the higher tiers need a full API plan). About 0.5 credits per job.

  • Hunyuan3D Pro (hunyuan): a prompt or one picture, pbr and face_count optional. 20 credits per job plus extras (about 2 to 2.4 CNY), a free package of 100 credits can be claimed once in the Tencent console.

  • The result is a glb, downloaded once into ~/.tether/assets/generated/<job>. The license is the provider's terms, not CC0. Result files come from whichever public HTTPS host the provider's API names, so redirects, private addresses and size are checked.

  • Jobs live in ~/.tether/jobs, so a job can be polled from a later session. Hunyuan's result links are valid for 24 hours.

  • Hunyuan Rapid, multi-view input and the other Tencent 3D actions are not supported.

GTA V / FiveM (optional)

If you work with GTA V assets through the Sollumz add-on, set TETHER_ADDONS=Sollumz. The headless daemon then enables it, scene fields=["gta"] flags the usual export problems (missing UVMap 0 or Color 1, empty sz_lods, unapplied transforms, .001 suffixes, missing textures) and tether.export_sollumz(folder, [names]) runs a Sollumz export that checks the files it wrote. None of this is active unless you ask for it.

Tests

python tests/run_tests.py                     # engine, client, scripts, asset sources against a fake server (no Blender, no network)
python tests/run_tests.py --mcp               # plus the MCP server through a stdio client
python tests/run_tests.py --mcp --blender     # plus a real headless Blender (412 checks with Sollumz installed, about two minutes)
python tests/run_tests.py --blender --gui     # also a windowed Blender: a window opens and takes focus

The Blender groups analyse image pixels, so they need numpy: pip install ".[test]" from a checkout. The Sollumz checks run only when that add-on is available. The MCP groups use whichever SDK is installed: add "mcp<2" or "mcp>=2" to that command to pick the major.

Limits

  • Developed on Windows. The process launch uses WMI to start Blender outside a packaged app's file virtualization and with the console hidden. The non-Windows launch path is a plain detached Popen and has not been run.

  • Tested with Blender 5.2.4 LTS only.

  • A script that registers add-ons, classes or handlers needs a fresh process (close, then open).

  • While you are inside a modal operator in a windowed Blender, jobs wait until it ends.

  • Generative 3D has been tested against a fake server that follows the providers' documented request and response shapes, and the Hunyuan request signature matches the official Tencent SDK byte for byte. It has not been run against the live Rodin or Hunyuan services yet: expect to fix small things on the first real job.

License

MIT, see LICENSE. Blender is a registered trademark of the Blender Foundation. Tether is an independent project and is not affiliated with or endorsed by the Blender Foundation.

Available Tools

11 tools
asset_importA
Destructive

Downloads a found asset and brings it into Blender (the download happens on this computer, from allow-listed hosts, with a size cap, into a cache; it is not downloaded twice). model: arrives under a root empty; target_size = the largest dimension in metres (chair 1.0, car 4.5, cup 0.12; sketchfab/polypizza arrive at an arbitrary scale, always give it); snap_to_ground puts the centre of the base at location ([x, y, z], default 0,0,0). texture: a Principled material named 'source_id' (kept even if it is outside the scene); apply_to=['Object'] replaces those meshes' material (warns if there are no UVs). hdri: assigned as a new world (the old one is kept). resolution: 1k (default), 2k, 4k, 8k; format: model gltf/fbx, texture jpg/png, hdri hdr/exr. accept_license: take a non-CC0 asset knowingly. Returns: bounding box, tris, materials, file, license; look at it with view afterwards. The root gets the properties asset_source/asset_license/asset_attribution. A generated model: source='rodin' or 'hunyuan', id = the job from generate_start (it must be done: see generate_status); target_size is advisable.

Inputs: id (required), app (required), source (required), kind, +7 more.

closeA
Destructive

Closes only a background agent. The user closes a windowed Blender; close a window you opened with open only by calling bpy.ops.wm.quit_blender() through run (the connection drops, which is not counted as an error).

Inputs: app (required). Returns: result

generate_startA

Starts generating a 3D model from text or pictures at a paid provider: rodin (Hyper3D Rodin; RODIN_API_KEY) or hunyuan (Tencent Hunyuan3D Pro; TENCENT_SECRET_ID and TENCENT_SECRET_KEY). Each job spends the provider's credits, so without accept_cost=True NOTHING is sent: the answer shows the job and its cost; ask the user before passing accept_cost=True. prompt (English or Chinese) or images (local .jpg/.png/.webp paths; rodin up to 5, hunyuan 1, and hunyuan takes a prompt or an image, not both). rodin: tier (default Gen-2.5-Low; Gen-2.5-Medium/High need a full API plan). hunyuan: pbr (PBR materials, +credits), face_count (3000 to 1500000, +credits). It takes minutes: poll generate_status, then asset_import(source=provider, id=job). Models are generated in the provider's cloud; the license is the provider's terms.

Inputs: provider (required), pbr, tier, images, +3 more.

generate_statusA

Asks the provider once how a generate_start job is doing: waiting, running, done or failed. When it is done the model is downloaded (once, into the cache); then bring it into Blender with asset_import(source='rodin' or 'hunyuan', id=job, target_size=metres). Poll no more often than every 10 seconds.

Inputs: job (required).

openA

Starts the app outside the caller's container and waits for its agent. Returns: selector, pid, mode, version, startup_s (seconds). Blender: background=True is a headless daemon: the factory scene (cube, camera, light), no user settings and no add-ons unless addons=['Name', ...] (add-on module names) or the TETHER_ADDONS environment variable are given; it closes after 30 minutes idle or when this session ends. background=False is windowed: it starts with the user's settings and the splash window shows. file = a .blend to load at startup; clean = start without user settings.

Inputs: app (required), file, clean, addons, +1 more.

runA
Destructive

Runs code in the app's own language (Blender: Python; bpy, bmesh, mathutils ready). The namespace persists (reset=True clears it, fresh=True makes this call a one-off). Value: the last expression or result; print output and a line-numbered error trace come back too. Script (instead of 'blender -b --python x.py -- a b'): file = path (relative: looked up in cwd first, then in the server's working directory; the answer says which one ran), args = what follows '--', cwd, env = environment variables; it runs in a fresh namespace and cwd/env/sys.path are restored afterwards. Background Blender: blend = open that .blend first, clean = go back to the factory scene first (both refused in a windowed Blender). grep = regex: only the matching lines of the output are kept; if the output is cut the full text is written to a file and its path is given. timeout = seconds (code 60, script 300): when it expires the call returns but the job continues (status says 'busy'); its result is not returned.

Inputs: app (required), cwd, env, args, +8 more. Returns: result

sceneA
Read-only

Scene report (read-only): the header has object/type counts, active, selected, mode; then fields per object (default: top-level objects, location+size+children+hidden). fields: location, size (world box including children), ground (ok/floating/below), rotation, scale, parent, children, hidden, details (faces/tris/verts, bones, light), materials, modifiers, animation; topology (quads/tris/ngons, boundary and non-manifold edges, loose vertices, poles); weights (vertices a deform bone does not move, bones without a vertex group); gta (Sollumz: UVMap 0, Color 1, sz_lods, shader, missing textures, unapplied transforms, .001 suffix); settings (file, engine, frames, resolution, camera, HDRI, units). Groups: placement, contents, health, all. root='Name': that object's hierarchy; query='text': the objects with it in their name; limit at most 200 lines.

Inputs: app (required), root, limit, query, +1 more. Returns: result

statusA
Read-only

Running apps: selector ('name#pid'), mode, version, busy or not, whether a modal operator is running, capabilities. Call this first.

Inputs: no named parameters.

viewA
Read-only

One PNG of the scene + a caption line (which tile is which angle). width: pixels of the long side (of the whole image when combined). mode: viewport (windowed Blender: the user's view without the UI; background: the camera or an automatic frame), camera (at the render aspect), angles (frames the target from several directions; the background default), frames (an animation strip). shading: solid, texture, material, rendered (EEVEE), wireframe (edges over the surface), xray (transparent, bones visible). target: objects to frame, with their children (default everything visible; a big object such as a floor enlarges the frame). angles: at most 6 of front, back, left, right, top, bottom, iso or an [x, y, z] direction (default front, right, top, iso). distance: metres from the target to the eye. frames: frame numbers or frame_count (2-12, default 6); look: camera, an angle name or [x, y, z]; frames steps through the frames and returns to the old frame at the end. image: instead of the scene, 'Render Result', an open image name or a file path. area (windowed): 'window' = the whole window, 'NODE_EDITOR'/'OUTLINER'... = a screenshot of that area (the splash window may cover it); it cannot be combined with the other options. Temporary settings are restored.

Inputs: app (required), area, look, mode, +8 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: open/close manage the session, run executes code, api_search looks up API, scene/view inspect, and asset_search/asset_import form a clean search-then-import pair. The only mild friction is the generic name 'status' (running apps) sitting beside 'generate_status' (generation job) and 'scene'/'view', which all report some kind of state; descriptions resolve it but the bare names could cause a first-glance misselection.

    Naming Consistency3/5

    All names are lowercase snake_case, which is good, but they mix at least three conventions: verb_noun (asset_search, asset_import, generate_start, generate_status, api_search), bare verbs (open, close, run), and bare nouns (status, scene, view). The generate_* and asset_* prefixes give helpful grouping, but the overall set is not a single predictable pattern.

    Tool Count5/5

    Eleven tools is well within the sweet spot for a rich Blender control server. Each tool occupies a distinct role (lifecycle, code execution, inspection, asset acquisition, AI generation) and none feels redundant or bolted on.

    Completeness4/5

    The surface covers session lifecycle (open/close/status), code execution and API discovery (run/api_search), visual and textual inspection (view/scene), asset search/import, and paid model generation with polling — a coherent end-to-end workflow. Minor gaps are that saving/exporting, undo, and closing a windowed Blender are not exposed as first-class tools (the latter is explicitly punted to run), though run provides a universal escape hatch.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers