Skip to main content
Glama
Sign In

Blender Bridge

by com.blenderbridge
OverviewDiscussionsAdmin

Execute Blender Python

execute_blender_code
Destructive

Execute Blender Python code through Blender Bridge. operation_name is required and must be a short, concrete, user-facing history title in the user's language, never a generic Run/Execute label. Persistent save/render/export work must include the structured project and outputs fields; use prepared paths through bb_output_path(kind_or_id). If Bridge returns ProjectRequired, supply the requested destination or use its suggested workspace path when file organization was delegated; ask only for a missing user choice. get_llm_instruction / blender://instructions/llm provides protocol and helper details when needed. Connection failures return their resolution. Default response_mode 'compact' returns only logs, delta, scene_digest and a slim scene snapshot (when changed). Use 'full' only for deliberate protocol diagnostics, not ordinary save/render verification. Long operations automatically return a running request_id before common MCP-host call limits; poll get_blender_operation_status instead of repeating the command. Set include_screenshot=true when the command result and the current viewport screenshot must be delivered by the same request.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "code": "<code>",
      "operation_name": "<operation_name>"
    },
    "name": "execute_blender_code"
  }
}

Input Schema

NameRequiredDescriptionDefault
areaNoShort category identifying the part of the task for operation/history metadata.
codeYesPython to execute in the receiving Blender; it can change the scene, files and external state.
modeNoBridge execution mode, preview or final; preview does not make Python read-only.
outputsNoDeclared persistent output files with kind and optional id, filename and explicit overwrite authorization; use prepared paths through bb_output_path.
projectNoPersistent-output destination: optional name/path/workspace_root and required authorization describing the user's choice.
timeout_secNoBlender operation execution budget in seconds, distinct from the chat host's response timeout.
response_modeNominimal returns compact status; compact is for normal work; full is for deliberate protocol diagnostics.
operation_nameYesShort, concrete history title in the user's language describing the requested operation.
full_scene_stateNoRequest full scene-state capture in the Bridge response.
include_previewsNoInclude available preview artifacts in the Bridge result.
include_screenshotNoDeliver a current viewport screenshot with this command result when requested.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changed
    • addedInput schema / properties / area / description
      Added value: +"Short category identifying the part of the task for operation/history metadata."
    • addedInput schema / properties / code / description
      Added value: +"Python to execute in the receiving Blender; it can change the scene, files and external state."
    • addedInput schema / properties / full_scene_state / description
      Added value: +"Request full scene-state capture in the Bridge response."
    • addedInput schema / properties / include_previews / description
      Added value: +"Include available preview artifacts in the Bridge result."
    • addedInput schema / properties / include_screenshot / description
      Added value: +"Deliver a current viewport screenshot with this command result when requested."
    • addedInput schema / properties / mode / description
      Added value: +"Bridge execution mode, preview or final; preview does not make Python read-only."
    • addedInput schema / properties / operation_name / description
      Added value: +"Short, concrete history title in the user's language describing the requested operation."
    • addedInput schema / properties / outputs / description
      Added value: +"Declared persistent output files with kind and optional id, filename and explicit overwrite authorization; use prepared paths through bb_output_path."
    • addedInput schema / properties / project / description
      Added value: +"Persistent-output destination: optional name/path/workspace_root and required authorization describing the user's choice."
    • addedInput schema / properties / response_mode / description
      Added value: +"minimal returns compact status; compact is for normal work; full is for deliberate protocol diagnostics."
    • addedInput schema / properties / timeout_sec / description
      Added value: +"Blender operation execution budget in seconds, distinct from the chat host's response timeout."
  2. First observed

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive, openWorld and non-idempotent, so the description correctly reinforces that code can alter scene, files, and external state. It adds genuinely new behavioral facts beyond annotations: long ops return a running request_id before host timeouts, defaults return only logs/delta/scene_digest/slim snapshot, and connection failures surface their resolution. Slight ding because a few clauses (response_mode tradeoffs, screenshot flag) restate what the schema already documents.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action followed by protocol rules, and nearly every sentence carries an actionable constraint (paths, ProjectRequired recovery, polling, mode selection). It is dense and long, but the density is justified by the tool's generality; minor redundancy with schema-described fields keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by naming what the default compact response contains (logs, delta, scene_digest, slim scene snapshot) and how to get fuller diagnostics. Combined with the ProjectRequired and request_id handling, an agent has enough to call it and interpret the response correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema cannot: operation_name must be a concrete user-facing title in the user's language and never a generic Run/Execute label. It also clarifies when project/outputs are mandatory and the practical intent of response_mode='full', which is usage nuance not captured in the field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Execute Blender Python code through Blender Bridge'), which cleanly separates it from siblings like run_test_scene, save_blend_file, and export_model that do narrower, fixed operations. An agent can identify this as the general-purpose escape hatch without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes behavior in multiple situations: use prepared paths through bb_output_path, recover from ProjectRequired via the suggested workspace path, prefer 'full' only for protocol diagnostics not ordinary verification, and poll get_blender_operation_status rather than re-issuing the command. It names a specific alternative sibling and the exact condition selecting it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Blender Bridge toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources