Skip to main content
Glama

blender_run

Destructive

Execute custom bpy Python scripts in headless Blender to handle procedural geometry, custom cleanup, baking, or batch edits, returning structured JSON results to the caller.

Instructions

POWER TOOL: run an arbitrary bpy (Python) script in headless Blender on this machine. The script gets helper globals from the Tufan preamble: ARGS (parsed k=v argv), IN/OUT (from inputFile/outputFile), emit(dict) → returns structured JSON to the caller, plus load_input()/import_any()/export_any()/mesh_objs()/tri_count()/inspect_report()/apply_all_modifiers()/select_only(). End with emit({...}) to return data. Python exceptions come back as clean tracebacks. Use blender_process for the common canned operations; this is for everything else (procedural geometry, custom cleanup, baking, batch edits). Executes native code locally — hidden in read-only mode. Needs Blender installed (auto-detected or TUFAN_BLENDER_PATH).

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": {
      "script": "<script>"
    },
    "name": "blender_run"
  }
}

Input Schema

NameRequiredDescriptionDefault
scriptYesThe bpy Python script body to execute
inputFileNoLocal 3D file surfaced to the script as IN (use load_input())
outputFileNoPath surfaced to the script as OUT
factoryStartupNoRun with --factory-startup (default true; set false to load user add-ons/extensions)
timeoutSecondsNoMax seconds for the Blender run (default 180, max 600)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare destructive=true and readOnly=false, and the description adds substantial context beyond them: it executes native code locally, requires Blender installed or TUFAN_BLENDER_PATH, is hidden in read-only mode, and returns Python exceptions as clean tracebacks. The preamble contract (ARGS, IN/OUT, emit, helper functions) is behavioral detail an agent cannot get from annotations or schema.

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?

It is a dense paragraph, but front-loaded with the verb and the core purpose, with the sibling alternative and preamble details following. The long parenthetical list of helper functions is informative rather than padding, though it slightly crowds the prose.

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?

For a high-complexity arbitrary-code-execution tool with no output schema, the description covers the return mechanism (emit → structured JSON), error behavior (clean tracebacks), environment prerequisites, and the execution context. Nothing essential to calling it correctly is missing.

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 the baseline is 3, but the description meaningfully annotates parameter behavior beyond the terse schema: inputFile becomes IN via load_input(), outputFile becomes OUT, and ARGS is a parsed k=v argv. factoryStartup and timeoutSeconds are left to the schema, which is acceptable.

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?

States a specific verb and resource ("run an arbitrary bpy (Python) script in headless Blender") and immediately distinguishes itself from the sibling canned-operation tool blender_process. An agent can tell exactly what this does and how it differs from the adjacent tool without reading 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?

Explicitly routes the agent: use blender_process for common canned operations, this tool "is for everything else (procedural geometry, custom cleanup, baking, batch edits)." It also states the constraint that it is hidden in read-only mode, which is a genuine when-not-to-use signal.

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