> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Blender Bridge

> blender-bridge — connect Profy to your local Blender over MCP: scene inspection, viewport screenshots, bpy scripting, GLB export

# Blender Bridge

Connect Profy to the Blender instance running on your own machine, so an expert can inspect the scene graph, execute Python (`bpy`), capture viewport screenshots to verify its own work, and export GLB.

This is orthogonal to Profy's cloud 3D capabilities. `profy-visualize` and `profy-game-studio` build **web-runnable** 3D with Three.js inside the sandbox. Blender Bridge operates on the actual `.blend` file sitting on your desktop.

<Warning>
  **Current implementation status (verified 2026-08-11)**: this plugin's `mcpServers` declaration (`uvx blender-mcp`) has **no consumer anywhere in the codebase**. The `PluginManifest.mcp_servers` field in agent-runtime is parsed but never read, and Core's MCP assembly path (`buildCommunityMcpToolsAndConfig`) only handles community plugin installations — it does not cover built-in manifests.

  In practice: ticking this plugin gives you its **skill and prompt layer** (the workflow discipline, safety rules, and export parameters below do take effect and shape model behaviour), but it does **not** give you callable Blender tools. Treat it as "a methodology for working with Blender" rather than "a remote control", until the wiring is completed.
</Warning>

## Declaration and activation

```json theme={null}
{
  "id": "blender-bridge",
  "name": "Blender Bridge",
  "version": "1.0.0",
  "mcpServers": [{ "name": "blender", "command": "uvx", "args": ["blender-mcp"] }],
  "activation": { "requires": { "desktop_connected": true }, "user_selectable": true }
}
```

Two independent gates must both pass before the manifest contributes anything:

| Gate                               | Condition                                                                                                              | If unmet                      |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `user_selectable: true`            | The plugin ID must appear in the set selected for this conversation                                                    | The whole manifest is skipped |
| `requires.desktop_connected: true` | Runtime `desktop_connected` is true, which is derived from the `PROFY_DESKTOP` environment variable equalling `"true"` | The whole manifest is skipped |

The evaluation order is: selectable gate first, then every entry in `requires` (booleans compared by truthiness, lists by membership, strings by equality), then legacy `conditions`. Any failure short-circuits.

The second gate means this plugin **exists only inside Profy Desktop**. A browser conversation in the cloud cannot select it and cannot activate it — the Blender you want to drive lives on your machine, and a cloud sandbox has no route to it.

## Prerequisites

| Requirement              | Notes                                                     |
| ------------------------ | --------------------------------------------------------- |
| Blender 4.x or newer     | Must be running; this is not passive file parsing         |
| BlenderMCP addon enabled | It is what exposes the MCP endpoint inside Blender        |
| Python `uv` installed    | `uvx` is used to launch `blender-mcp`                     |
| Profy Desktop            | Not available in the cloud, per the activation gate above |

`marketplace.installMode` is `ON_INSTALL`, meaning setup happens at install time rather than lazily on first call. `marketplace.availability` is `AVAILABLE` and the category is `creative-tools`.

## Workflow discipline (skill layer, active today)

The bundled `blender-workflow` skill defines the cadence the model follows. The core idea is **look after every step**:

```
1. Inspect the current scene → understand what already exists
2. Break the change into small steps
3. Execute one operation at a time
4. Screenshot the viewport after each change → verify visually
5. If wrong, undo and retry
6. When satisfied, save and optionally export
```

### Vision in the loop

The skill encodes one non-negotiable rule: **screenshot after every single modelling operation**, then ask whether the shape is right, the position is right, and the materials applied. Fix problems before moving on.

> Never assume an operation succeeded — always verify visually.

This discipline does not depend on the MCP wiring. It constrains how the model self-verifies in any 3D task, which is why the skill layer is worth having even while the tool layer is incomplete.

### Pre-flight checklist

1. Verify the MCP connection by calling any Blender tool, e.g. `get_scene_info`
2. Confirm the Blender version (4.x+) and the addon status
3. Identify the current scene state before making any changes

Step 3 exists because "create a cube" means something different in an empty scene versus a scene that already has forty objects and a specific naming convention.

## Capability inventory (available once MCP is wired)

| Category         | Contents                                                                        |
| ---------------- | ------------------------------------------------------------------------------- |
| Scene inspection | Object list, transforms, materials, lights                                      |
| Object creation  | Mesh primitives, curves, empties                                                |
| Modelling        | Modifiers: subdivision, boolean, array, mirror                                  |
| Materials        | PBR metalness–roughness workflow (base colour / metalness / roughness / normal) |
| Lighting         | HDRI environment, area / point / spot lights                                    |
| Scripting        | Execute arbitrary `bpy` Python                                                  |
| Export           | GLB / FBX / OBJ                                                                 |
| Asset libraries  | Poly Haven (HDRI, textures, models), Hyper3D Rodin                              |

## Web export parameters

Models destined for the web have specific parameters, not "just export it":

| Item         | Value                                  | Why                                                     |
| ------------ | -------------------------------------- | ------------------------------------------------------- |
| Format       | GLB (binary glTF)                      | Single file, natively supported by browsers             |
| Compression  | Draco enabled                          | Substantially reduces geometry size                     |
| Textures     | Embedded, max 2048×2048                | Beyond this, mobile pays more than it gains             |
| Transforms   | Apply before export                    | Otherwise downstream consumers receive wrong transforms |
| Verification | Open in a Three.js viewer after export | "Export succeeded" is not "loads correctly"             |

The full pipeline is: model in Blender → optimise (decimate, bake textures) → export GLB → load in Profy's `visualize` or `game-studio` → deploy via Sites.

## Safety rules

Four hard constraints from the skill that the model will honour:

* Never overwrite without asking — use "Save As" for new versions
* Never delete objects without confirmation
* Never modify files outside the project directory
* Always work on a copy, never the original

These are worth reading as a statement of intent. An agent with `bpy` execution has, in principle, arbitrary file access through Python; the skill narrows that voluntarily. It is discipline, not a sandbox — if you need a hard boundary, keep the original file outside the project directory entirely.

## Boundaries and failure modes

* **No Desktop, no plugin.** It does not appear in the plugin panel in cloud conversations. That is the activation gate working, not a bug.
* **Blender not running means pre-flight fails.** The skill requires an initial scene-inspection call to confirm connectivity. On failure the model should stop and report, not carry on pretending to model.
* **The MCP declaration is currently unwired** (see the warning at the top), so "the model says it should screenshot but has no screenshot tool" is expected behaviour right now, not the model being lazy.
* **Polygon budget is on you.** Web export has no automatic decimation fallback. An over-budget model still exports fine; it just loads badly.
* **`uvx` downloads on first use.** If your machine has no network route to PyPI, launching the server will fail regardless of Blender's state.

### Troubleshooting

| Symptom                                                   | Cause                                                                    | Fix                                                        |
| --------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------- |
| Blender Bridge missing from the plugin panel              | Not in Desktop, or Desktop not connected                                 | Open Profy Desktop and confirm the connection status       |
| Selected, but the model says it has no Blender tools      | `mcpServers` is unwired (see top of page)                                | Expected today; the skill layer still applies              |
| `uvx` not found                                           | Python `uv` is not installed                                             | Install `uv`, then confirm `uvx blender-mcp` runs manually |
| Exported GLB is empty in Three.js                         | Transforms not applied before export, or nothing was selected            | Walk the export parameter table item by item               |
| Viewport screenshot looks correct but the export does not | Modifiers not applied, or the export selection differs from the viewport | Apply modifiers, then re-export with an explicit selection |

## Verify your setup

1. Open a new conversation in Profy Desktop. Blender Bridge should appear in the plugin panel — **if it does not, Desktop is not connected** and nothing further will work.
2. Tick it and ask "what objects are in the current Blender scene?". If you get methodology advice instead of actual scene data, you have hit the unwired state described at the top of this page.
3. Ask it to outline the steps for "export the selected object as a web-ready GLB". A correct answer mentions Draco, the 2048 texture ceiling, and applying transforms — which confirms the skill layer really did load.

## Related

<CardGroup cols={2}>
  <Card title="3D and visualization" href="/en/documentation/plugins/3d-development">
    Cloud-side visualize / game-studio / AI 3D generation
  </Card>

  <Card title="Godot Bridge" href="/en/documentation/plugins/godot-bridge">
    Sibling bridge: game engine plus deterministic playtesting
  </Card>
</CardGroup>

<Note>
  Verified 2026-08-11. Sources: `services/agent-runtime/src/plugins/builtin/blender-bridge/plugin.json`, `skills/blender-workflow/SKILL.md`, `prompts/BLENDER.md`, `services/agent-runtime/src/plugins/registry.py` (`_check_activation`), `services/agent-runtime/src/plugins/utils/types.py`.
</Note>