Tether
Lets an agent drive Blender in headless or windowed mode: execute Python in a persistent namespace, query detailed scene reports (geometry, materials, modifiers, topology, animation), render multi-angle and multi-shading previews, and verify or fix its own work.
Provides optional GTA V / FiveM checks through the Sollumz add-on, allowing the agent to validate exports and related scene data for FiveM workflows.
Enables searching for and importing Sketchfab 3D models into Blender through asset search and import tools, with license filtering (CC0 by default), secure downloads, caching, and rollback on import failure.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Tether open blender and model a low-poly coffee mug, then render it from four angles"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.

What it does
Starts its own Blender.
openlaunches 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,numpyand friends are already there. Stalebpyreferences are dropped when a file loads or undo runs, instead of crashing Blender.Lets the agent verify its work.
scenereturns a text report (sizes, ground contact, topology, weights, modifiers, animation range...).viewrenders 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_searchandasset_importwork 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.selectraise with the reason where raw Blender calls silently do nothing (a locked object, a hidden collection, an export that saysFINISHEDand 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-tetherRegister it with your MCP client. For Claude Code:
claude mcp add tether -- python -m tether.mcp_serverAny 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 |
| Lists running apps (selector, mode, version, busy or idle) and what can be opened. Call it first. |
| Starts Blender and waits for its agent. |
| Closes a background agent. |
| Runs Python (or a script file with |
| Searches the running Blender's own API ( |
| Read-only scene report. Fields: location, size, ground, rotation, scale, parent, children, hidden, details, materials, modifiers, animation, topology, weights, gta, settings. |
| One PNG of the scene: |
| Searches models, PBR textures and HDRIs. |
| 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 ( |
| Starts a text-to-3D or image-to-3D job at Rodin or Hunyuan. Without |
| 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. Useblend=andclean=onrunto open a file or return to the factory scene.Windowed Blender:
open app=blenderstarts Blender with your own settings and the agent attached. To attach to a Blender you started yourself, linkblender_addon/tether_blenderinto Blender'sscripts/addonsfolder 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.pyembeds the agent in a Python program andtether/agent/example_node.jsdoes the same in about 70 lines of Node. The protocol is described at the top oftether/agent/__init__.py.
Configuration
Variable | Meaning |
| Full path of the Blender executable. |
| Comma-separated add-ons the headless daemon enables, for example |
| Extra folders (separated by |
| State folder. Default |
| Turns off the call log. It stores counts and timings only, never code or output. |
| Keys for the two providers that need them. They can also be put in |
| Keys for generative 3D (Hyper3D Rodin; Tencent Cloud for Hunyuan3D). Also readable from |
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 | 0.59 to 0.83 s |
One | 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) |
| 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
scenereport and multi-angleviewlet 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.0Rodin (
rodin): text or up to 5 pictures,tierdefaultGen-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,pbrandface_countoptional. 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 focusThe 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
Popenand 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, thenopen).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 toolsapi_searchARead-only
Searches the app's API from the running version; use it before writing code. Blender: bpy.ops and bpy.types, open add-ons included. An exact name ('bpy.ops.mesh.primitive_cube_add') dumps the parameters and enum values.
Inputs: app (required), query (required). Returns: result
asset_importADestructive
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.
asset_searchARead-only
Searches ready-made 3D assets on the internet: models, PBR textures, HDRIs. source: all (default, in parallel), polyhaven (all CC0, no key), ambientcg (textures/hdris, CC0), sketchfab (models; a token is needed to download), polypizza (low-poly models; an API key). The query is English ('couch' also finds sofa). kind: model, texture, hdri. license: CC0 only by default; 'cc0,by' also brings CC-BY (attribution required). category: a text filter. polyhaven only: attrs={'weather': 'clear'} (hdri), min_size_m (the real size of a texture; 2+ for floors and walls). max_faces: polygon cap (polyhaven, sketchfab). animated: sketchfab, polypizza. previews=N (at most 6): small images of the first N results as one numbered image. Line: source id | kind | name | category | faces | size (m) | highest resolution | license | author. Pass the id to asset_import.
Inputs: kind, attrs, limit, query, +7 more.
closeADestructive
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.
runADestructive
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
sceneARead-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
statusARead-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.
viewARead-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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
Generate 3D models, worlds, PBR materials, and coordinated asset packs from AI agents.
Blender and GLB/FBX/USD/STL rendered on cloud GPUs for AI agents: product shots, turntables, MP4
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI agents to drive a live Blender session for modeling, shading, lighting, rendering, and scene manipulation, returning rendered images for visual feedback.4122MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to inspect and modify live Blender scenes, manage objects and materials, render images, retrieve PolyHaven assets, and send prompts to configurable local or OpenAI-compatible LLM backends.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to control a live Blender session, inspect and modify scenes, manage PolyHaven assets, render images, and route prompts through configurable local or OpenAI-compatible LLM backends.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to control a live Blender session, manage scenes, objects, materials, and renders, download PolyHaven assets, and switch between multiple LLM backends at runtime.-