Blender MCP

Connect your chosen Mosael agent to local Blender, then exchange models and camera shots from the 3D Scenes → Blender menu. This plugin uses the community MCP for Blender server (published as mcp-for-blender; called blender-mcp before 2.0), pinned to 2.0.3. It does not require Astra or a separate modeling-model API key.

Installation#

1. Install and open Blender. The version actually verified for this release is Blender 5.2.0 LTS; with other versions, try a small scene first. Blender and the Mosael desktop backend must be on the same computer.

2. Install uv and make sure the Mosael backend can find uvx. Install the add-on that matches this version:

   sh

   uv run plugins/examples/blender/install-extension.py

   It is installed as an Extension (the new system in Blender 4.2+). Upstream only ships a legacy single-file add-on, and in Blender 5.x Preferences → Add-ons lists only Extensions by default — running upstream's install-addon directly leaves you with "the file is clearly there, but the UI can't find it". The script regenerates the extension from the upstream copy, so after an upgrade just run it again; it also removes any legacy copy of the same version, because two copies side by side fight over the same port 9876.

   By default it installs into every Blender 4.2 or newer; --blender 5.2 installs into just one, and --list shows where it would install first. Only run uvx --python 3.14 mcp-for-blender==2.0.3 install-addon if you still need the legacy system (Blender older than 4.2).

   Once installed, search for MCP in Blender's Preferences → Add-ons and tick MCP for Blender. This is a community add-on, not an official Blender add-on.

3. Copy this directory into plugins/blender/ under the Mosael data directory, then click Scan plugins on the Plugins page. The default data directory is ~/.mosael; custom deployments use MOSAEL_DATA_DIR. Once a release bundle includes dev.mosael.blender.zip, you can also install it from the plugin market.

4. Create a Blender MCP connection, keep the local host address and the default port 9876 (if you change it, it must match the Blender panel), grant the permissions the manifest lists, and enable it. The plugin turns off upstream telemetry by default.

5. Open a 3D scene and click Blender → Check in the toolbar. Development mode (pnpm dev) already sets MOSAEL_LOCAL_DESKTOP=1 by default — the dev backend is on the same machine as your files anyway; to simulate a team server, use MOSAEL_LOCAL_DESKTOP=0 pnpm dev. Do not turn this switch on for a remote deployment to get around the local-only restriction: the exchange writes a .blend to the local disk and hands it to Blender on the same machine, and a backend on a server cannot reach your computer.

The first launch downloads the pinned Python / MCP packages, which can take a while. The add-on runs inside Blender's graphical interface; --background cannot replace the interactive connection.

Usage#

• Get from Blender (3D scene list page): takes the scene currently open in Blender as a new Mosael scene, with no need to have sent anything first — this is the way in when you already have a Blender project. Only geometry comes back: a Mosael shot needs to know "where it is looking", and that distance is carried only by cameras that were sent from Mosael; an arbitrary Blender camera cannot provide it, so cameras are not brought back (you get an explicit notice if there are any) and shots are redesigned on the Mosael side.
• Send current scene: waits for saving to finish, then sends the currently visible models, materials/lights and all shots to a separate Mosael · scene name Blender Scene without clearing other Scenes. The selected shot becomes Blender's active camera. The GLB is generated by the backend from the saved version (no longer exported and uploaded by the browser), so agents can send too — see blender_send_scene. Imported GLB models are each imported as files and placed at their positions in the scene.
• Edit models, modifiers, materials or cameras in Blender. You can also have a Mosael agent (the modeling assistant or a chat, using the model you choose) model directly in Blender; see the next section.
• Receive Blender changes: reads the Scene of the matching transfer record and updates the current scene. Models are imported as one combined GLB; cameras come back as editable shot keyframes. It is an ordinary change to the current scene — ⌘Z undoes it, and the version from before receiving stays in the version history.
• Save as new scene: use this when the original scene must not change by a single byte; the received result goes into a separate new scene (previously this was the only way to receive). Then use Open received scene to check the models and shots, and carry on with the existing shot preview, first/last frame and reference video generation flow.
• .blend: downloads the most recently received project; if nothing has been received yet, downloads the project from when it was sent. The file contains that Scene and its dependencies, not unrelated Scenes. Newly added linked resources such as external textures should be packed or saved alongside in Blender yourself.

Transfer records are stored in the local data directory, so you can still receive after refreshing the app. After Blender restarts, reopen the matching .blend or send the scene again. Receiving locates the Scene by its mosael_transfer_id property, so renaming it does not matter; if that property or the Scene is deleted, send again.

Letting the agent model in Blender#

When a connection is available, the agent has five built-in Blender tools, which act on the scene you currently have open in Blender:

• blender_inspect: lists objects, types, hierarchy, transforms, dimensions, modifiers and materials. Read-only.
• blender_look: frames the scene automatically and renders a few images (overview / front / side / back / top / scene camera) as visual input for the model. solid uses Workbench and takes about a second; rendered uses EEVEE to show real materials. Render settings are changed temporarily and restored afterwards. Read-only.
• blender_execute: runs bpy modeling code written by the model — bmesh, modifiers, curves, geometry nodes and materials are all available. It goes through an approval card: Blender's Python is not a sandbox. An undo step is pushed before running, so you can ⌘Z in Blender; if the code raises, the traceback goes back to the model, which fixes it and retries. The auto-approve rules have a separate Modeling in Blender entry, and allowing it does not also allow Running code on this computer.
• blender_send_scene: sends the Mosael scene (blockout geometry, groups, materials, all shots) into Blender — the same path as Send current scene in the UI.
• blender_import_to_scene: adds the whole Blender scene, or objects picked by name (including their children), to the Mosael scene as one model object.

The modeling loop is "run a small step → take a look → correct". Whether the model itself can see images decides whether the second step works; a model without image input does not receive the screenshots and gets a one-line explanation instead.

The plugin's own execute_blender_code is the raw entry point with no approval. Since 0.2.0 it is marked internal in the manifest: only the fixed scripts of the 3D scene exchange use it, it does not appear in the tool checklist on the plugin page, and neither agents nor workflows can call it — otherwise it would be a back door around the approval card. Updating to 0.2.0 requires copying the plugin directory again or updating from the plugin market.

The rest of upstream's tools are declared by their consequences: read-only ones (Inspect Blender scene / Inspect Blender object, Capture Blender viewport, describe_node_type and bpy_api_lookup for looking up how to write things, each integration's get_*_status) are called by the agent directly; ones that change the scene, download assets, export files or call Hyper3D / Hunyuan3D generation show an approval card before the agent calls them.

Current scope#

• Sending bakes camera motion and vertical FOV at 30 fps. Receiving samples at most 100 frames per shot duration; long shots show a review notice.
• Perspective shots without roll are supported; orthographic/tilted shots keep the version from when they were sent, with an explicit notice. Receiving keeps the source shot's name, duration and aspect ratio; newly created Blender cameras do not automatically become Mosael shots.
• What is received is a geometry snapshot of the first frame, with modifiers applied where possible. Complex node materials, object animation, world lighting and Area lights cannot be fully restored through GLB; the complete editing information stays in the .blend. The environment background/ambient light is taken from the sent snapshot.
• Scene files are at most 512 MB, and receiving uses Mosael's model complexity limits (5000 nodes / 2000 meshes) and external resource checks. If you actually hit them, try compression first: Mosael can decode Draco, KTX2 (Basis) and meshopt; failing that, hide objects you don't need, reduce textures to 2K, or split the scene into several parts and transfer them separately.
• This stage has no automatic per-object merging, continuous two-way sync or Cycles background render queue.

Python inside Blender has the Blender process's file permissions and is not a sandbox. Only enable connections you trust. The sync buttons in the UI and the agent's inspect, screenshot and export actions all use fixed scripts, pass parameters as data, and go through user, workspace and plugin authorization checks; only blender_execute runs code written by the model, and it must go through the approval card or an auto-approve rule you have explicitly set.

Timeline in Mosael 1.2.0#

Cameras and ordinary objects are both edited in the timeline at the bottom; select an object, move the playhead, adjust the pose, then press I to insert a keyframe. A shot picks its camera position through camera_id, and camera keyframes are stored on that object's track.

At the send boundary, the camera track is converted into the per-shot frame sequence Blender uses; an empty track is sent as a fixed camera position, and FOV/target values left blank use the camera position's own values. Before the first keyframe the first frame is held, with no extrapolation. When coming back, the linear sampling rhythm is kept, and cameras use the returned world coordinates, no longer referencing the original group that has been replaced by the combined model.

Generating a reference image can include a separately rendered neutral gray model; model and reference frame exports exclude the editing camera helpers inside nested groups. Ordinary object animation in Mosael still does not round-trip as native Blender animation tracks; keep the .blend project for complex animation.