Blender Agent Bridge

The local, safety-aware bridge between Blender and external AI agents.

Blender Agent Bridge is a Blender extension plus a localhost MCP server. It lets tools such as Codex, Claude Desktop, Claude Code, Cursor, and other MCP-capable clients inspect the open Blender scene, gather visual evidence, make reversible edits, and run Blender Python only when you explicitly enable session trust.

<p align="center"> <img src="docs/assets/egypt-dogfight-hero.jpg" alt="Two aircraft in a generated Blender dogfight scene with smoke and motion blur" /> </p> <p align="center"> <a href="addon/claude_blender/blender_manifest.toml"><img alt="Blender 4.2+" src="https://img.shields.io/badge/Blender-4.2%2B-F5792A"></a> <a href="https://github.com/CallMeJones/blender-agent-bridge/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/CallMeJones/blender-agent-bridge"></a> <a href="https://github.com/CallMeJones/blender-agent-bridge/actions/workflows/mcp-smoke.yml"><img alt="Build, smoke, release" src="https://github.com/CallMeJones/blender-agent-bridge/actions/workflows/mcp-smoke.yml/badge.svg"></a> <img alt="MCP bridge" src="https://img.shields.io/badge/MCP-localhost%20bridge-3B82F6"> <img alt="LLM host" src="https://img.shields.io/badge/LLM%20provider-external-10B981"> <a href="LICENSE"><img alt="License GPL-3.0-or-later" src="https://img.shields.io/badge/License-GPL--3.0--or--later-111827"></a> </p> <p align="center"> <a href="https://polyhaven.com/"><img alt="Poly Haven assets" src="https://img.shields.io/badge/Assets-Poly%20Haven-2E7D32"></a> <a href="https://sketchfab.com/"><img alt="Sketchfab assets" src="https://img.shields.io/badge/Assets-Sketchfab-1CAAD9"></a> <a href="https://platform.tripo3d.ai/"><img alt="Tripo3D generation" src="https://img.shields.io/badge/Image--to--3D-Tripo-2563EB"></a> <a href="https://www.meshy.ai/"><img alt="Meshy generation" src="https://img.shields.io/badge/Image--to--3D-Meshy-7C3AED"></a> <a href="https://github.com/VAST-AI-Research/TripoSR"><img alt="Local TripoSR generation" src="https://img.shields.io/badge/Local%20Image--to--3D-TripoSR-374151"></a> </p>

What You Get

• Scene-aware agent workflows without putting a chat app or model-provider key inside Blender.
• Read-only inspection of objects, materials, animation, rigs, cameras, nodes, render settings, and .blend health.
• Viewport, playblast, inspection-render, thumbnail, and render-job evidence that agents can review before changing the scene.
• Reversible helper edits with visible Commit and Revert controls in Blender.
• Optional session-trusted Python for broad authored work when you deliberately enable Trust Agent Scripts.
• Optional Poly Haven, Sketchfab, Tripo, Meshy, local TripoSR, and self-hosted studio workflows with provider-specific consent and provenance.

Quick Start

1. Install the Blender extension

Install Blender 4.2.0 or newer. The release workflow continuously checks Blender 4.2 LTS, 4.5 LTS, and 5.1; newer versions are allowed through capability checks instead of an artificial maximum-version gate.

Recommended install:

1. In Blender, open Edit > Preferences > Get Extensions.

2. Enable online access if Blender asks.

3. Press Repositories.

4. Press +, choose Add Remote Repository, and name it Blender Agent Bridge.

5. Paste this repository URL:

   https://callmejones.github.io/blender-agent-bridge/index.json
   

6. Close the repository popover, open the extension settings menu, and choose Refresh Remote.

7. Search for Blender Agent Bridge.

8. Press Install, then confirm the extension is enabled.

9. In the 3D View, press N and open the Agent Bridge tab.

10. Press Start. The panel should report that the bridge is on.

Manual fallback:

1. Open the latest GitHub release.
2. Under Assets, download claude_blender-<version>.zip.
3. Do not download GitHub's generated Source code ZIP; it is not an installable Blender extension.
4. In Blender, open Edit > Preferences > Get Extensions.
5. Open the extension menu, choose Install from Disk, and select the downloaded ZIP.
6. Enable Blender Agent Bridge, open the Agent Bridge sidebar tab, and press Start.

The extension ZIP already includes the MCP server. The recommended bundled mode does not require pip, uv, or uvx. For checksums, command-line installation, update behavior, and troubleshooting, see Install From GitHub.

2. Connect an MCP client

After pressing Start, press Copy MCP Config in Blender. That copies the complete mcpServers.blender entry with the correct local Python path, bridge URL, session token, version metadata, and tool-registry digest.

Keep every generated command, args, and env value together. The copied config is the source of truth for Codex, Cursor, Claude Code, and manual Claude Desktop setup.

| Client | Setup | | --- | --- | | Claude Desktop | Recommended: open the blender-agent-bridge-<version>.mcpb asset from the matching GitHub release and enter the bridge URL/token shown in Blender. Manual fallback: merge the complete copied mcpServers object into Claude Desktop's config, then fully restart Claude Desktop. | | Claude Code | Take only the object inside mcpServers.blender, then run claude mcp add-json --scope user blender '<server-object-json>'. Run claude mcp list, restart Claude Code, and use /mcp to confirm it connected. | | Codex app, CLI, or IDE extension | Do not install the MCPB. Open Settings > MCP servers > Add server, choose local STDIO, and copy the generated command, every args item, and every env value. Alternatively, convert the same entry to [mcp_servers.blender] in ~/.codex/config.toml. Save it, select Restart, then use /mcp or codex mcp list. | | Cursor | Do not install the MCPB. Merge the complete generated JSON into ~/.cursor/mcp.json for all projects or .cursor/mcp.json for one project. Preserve other servers, refresh Cursor's MCP servers or restart Cursor, then check Settings > MCP. |

The MCPB is only the Claude Desktop connector format. Install and start the Blender extension separately for every client.

The generated config includes a localhost bridge token. Keep it in local configuration, never paste it into issues or public chat, and press Copy MCP Config again after changing the extension or bridge settings. Keep only one blender entry in each client, and connect only one active MCP server to a Blender bridge at a time.

Client-specific walkthroughs are available for Claude, Codex, Cursor, VS Code/Cline/Roo, ChatGPT, Gemini CLI, OpenCode, and Ollama hosts.

3. Test the connection

Keep Blender open with the bridge running, refresh or restart the MCP client, then ask:

Check Blender bridge status, find and invoke the scene-object inspection tool, and make no changes.

The default MCP tool list contains exactly blender_bridge_status, blender_tool_catalog, search_blender_tools, get_blender_tool_schema, and invoke_blender_tool. Helpers such as list_scene_objects are intentionally found through search, inspected through schema lookup, and called through the gateway.

Then try a reversible edit:

Move the selected cube up 1 Blender unit and make it red. Leave the change as a preview.

Helper preview edits stay pending in Blender until you use Commit, Revert, or Blender undo. Generated Python is refused while Trust Agent Scripts is off. With trust on, generated scripts run immediately with Blender Run Script-equivalent permissions and normal Blender undo/checkpoint behavior.

For deterministic diagnostics, use blender-bridge doctor when that command is available in your MCP runtime. It verifies the executable, optional client config, bridge socket, add-on/runtime compatibility, five-tool manifest, schema lookup, and a real read-only gateway invocation. See Connection Diagnostics.

Try These Prompts

With an object selected:

Move the selected cube up 1 Blender unit and make it red.

Make the selected cube bounce twice over 72 frames, getting smaller each bounce. Check it against the brief and leave it as a preview.

Capture close-up inspection renders of the selected vehicle underside, review them against the brief, and suggest repair operations.

Search Poly Haven for a sunset HDRI, cache it as an external asset job, poll until it is ready, then queue the import into the world as a preview.

Check which image-to-3D providers are ready and explain their cost, privacy, and quality tradeoffs. Do not start a job.

Generate a 3D model from these confirmed reference-image paths. If more than one provider is available, ask me which provider to use before starting anything.

Render a playblast as a background job, poll it, assemble the MP4, and validate the output.

Safety Model

Connected agents do not get blanket access by default. Blender stays the execution layer; the external client stays the model, conversation, planning, and account layer.

| Path | What happens | | --- | --- | | Local bridge | Off by default and bound to 127.0.0.1. Optional bearer authentication is available; without it, any local client that can reach the bridge may call its tools. | | Preview edits | Show Commit and Revert controls in Blender and retain normal Blender undo support. | | Project tools | Restrict generic file access to the current saved project directory. Save, open, and new-project operations require explicit confirmed paths. | | Generated Python | Refused while trust is off. With trust on, it has Blender Run Script permissions, including filesystem, network, subprocess, project-file, persistent-cache, and full Blender API access. | | Script trust | Runtime-only and visibly revocable. It clears on Revoke, timed expiry, add-on reload, or Blender exit. | | Credentials | Provider keys are redacted from responses. Optional persistence uses the operating system credential facility where available, with a clearly reported user-only file fallback; keys are never written to Blender preferences, .blend files, manifests, or audit logs. |

See SECURITY.md, PRIVACY.md, and Safety Model for the detailed model.

Optional Providers

Every provider is optional. Turning off Allow Third-Party Uploads disables hosted generation without disabling scene inspection, preview edits, trusted scripts, project tools, rendering, Poly Haven, local TripoSR, or a configured self-hosted studio endpoint.

| Provider | Use it for | Setup | | --- | --- | --- | | Poly Haven | CC0 HDRIs, PBR textures, and models. | No key required. | | Sketchfab | Public model search and authenticated glTF downloads with attribution and license provenance. | Search needs no key; downloads need a Sketchfab API token. | | Tripo | Hosted single-image and calibrated multi-view image-to-3D jobs. | API key plus Allow Third-Party Uploads. Hosted jobs require explicit spend approval in Blender. | | Meshy | Hosted single-image and multi-image generation with Meshy 7, Meshy T2 Smart Topology, remeshing, textures, and thumbnails. | API key plus Allow Third-Party Uploads. Hosted jobs require explicit spend approval in Blender. | | TripoSR | Local single-image blockouts without vendor upl