Skip to main content
Glama
mohakmalviya

blender-compact-mcp

by mohakmalviya
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Frugal Blender MCP

Let your AI agent build Blender scenes. All of Blender, four tools, 338 tokens.

Checks PyPI Blender 4.2+ MCP MIT

Quick start · How it saves tokens · Benchmark · Safety · Example

Five execute calls (109 operations) written by Claude, rendered with Cycles in Blender 5.1. Replay the exact calls: they run in under a second.

Why it matters

Every MCP client sends each server's tool definitions to the model on every request, before you type anything. Most Blender servers expose 26 to 31 tools and spend thousands of tokens that way. That's context your agent can't use for your scene, your code or its own reasoning.

Frugal Blender MCP exposes four tools, discover, execute, inspect and capture, and still reaches the whole Blender API.

Related MCP server: Blender MCP Server

Quick start

You need Blender 4.2+ and uv.

1. Install the Blender add-on

uvx frugal-blender-mcp install-addon

In Blender, open Edit → Preferences → Add-ons and enable Frugal Blender MCP. Then press N in the 3D Viewport, open the Frugal MCP tab and click Start bridge.

2. Connect your agent

claude mcp add blender -- uvx frugal-blender-mcp
codex mcp add blender -- uvx frugal-blender-mcp
{
  "mcpServers": {
    "blender": { "command": "uvx", "args": ["frugal-blender-mcp"] }
  }
}

If a desktop app can't find uvx, use its absolute path (which uvx or where uvx).

3. Ask for something

Build a small lighthouse island at golden hour: a red-and-white tower, a keeper's house, a few pines, rocks and a sailboat. Batch your edits, then capture a preview.

How four tools reach all of Blender

Most servers ship one tool per action, and every definition rides along with every request. This server keeps the menu short and hands the details over only when the agent asks for them:

sequenceDiagram
    autonumber
    participant A as AI agent
    participant M as Frugal Blender MCP
    participant B as Blender
    Note over A,M: Each request carries only 4 tool definitions, 338 tokens
    A->>M: discover()
    M-->>A: 16 operation summaries, 189 tokens, once
    A->>M: discover("array")
    M-->>A: argument contract for one operation
    A->>M: execute(43 steps)
    M->>B: validated batch, run on Blender's main thread
    M-->>A: ok, completed 43, 28 tokens
    A->>M: capture()
    M-->>A: preview image at the scene's aspect ratio

Technique

What it does

Effect

Lazy schemas

Operation arguments live behind discover. The agent fetches each one once, only if it uses it.

Fixed cost stays at 338 tokens. Even fetching every schema totals 1,256.

Batching

One execute carries up to 100 operations. array makes up to 200 copies in one step, keyframes sets up to 1,000 keys.

The lighthouse took 5 calls, not 109.

Compact results

execute returns counts and errors, never the scene echoed back.

109 operations returned 202 tokens in total.

Look, don't dump

capture returns an image. inspect is paged and filtered by name.

The agent checks its work without reading huge scene dumps.

Lean definitions

Generated schema titles, null unions and docstring whitespace are stripped before tools are listed.

Definitions shrank from 406 to 289 tokens. A test fails if they grow past 300.

One escape hatch

python runs any bpy code through the same execute call, so it needs no extra tool.

Geometry Nodes, rigging, simulation and import/export at zero fixed cost.

The five calls behind the animation above, and what each one added:

Benchmark

Server

Tools

Fixed context per request

Frugal Blender MCP

4

338 tokens

Blender Lab official

26

4,722 tokens (14.0x)

ahujasid mcp-for-blender

31

7,464 tokens (22.1x)

Tool definitions plus server instructions from each server's real initialize and tools/list responses, tokenized with tiktoken o200k_base. Method, raw data, discovery costs and caveats.

What the agent can do

Need

Operations

🧱

Build

primitive, array, transform, material, assign_material, light, camera, delete

🎨

Refine

modifier (any Blender modifier), properties (any RNA property on objects, data, scene or render), rna (look up property names and enums)

🎬

Animate

keyframes, frame

📸

Output

capture (preview back to the agent; EEVEE, or Cycles on request), render (stills or animations), save (a .blend copy)

🐍

Anything else

python: the full bpy API. Off by default.

Safety

Blender stays in control. You choose permissions in the add-on panel when you start the bridge, and the agent can't change them.

  • Write and render are on by default. Delete, save and python are off.

  • Python is unrestricted local code execution. Turn it on only for agents you trust.

  • The bridge listens on loopback only and needs a fresh random token each time you start it.

  • Deletes need confirm: true. Saves and renders never overwrite existing files.

  • Interactive sessions get an undo checkpoint before every batch.

  • No telemetry.

Details: SECURITY.md.

How it compares

Choose by what you need, not just context size:

  • Blender Lab's official server also searches Blender's manual and API docs, which helps agents write correct bpy.

  • ahujasid's server bundles asset providers (Poly Haven, Sketchfab, Hyper3D and others).

  • This server keeps the fixed context small, batches edits, gates risky actions behind permissions, and still reaches the whole API through python when you allow it.

More

uvx --from frugal-blender-mcp frugal-blender discover
uvx --from frugal-blender-mcp frugal-blender inspect
uvx --from frugal-blender-mcp frugal-blender execute --params '{"steps":[{"op":"primitive","kind":"cube","name":"Demo"}]}'
uvx --from frugal-blender-mcp frugal-blender capture --params '{"filename":"preview.png","size":768}'

PowerShell can pipe a file instead of quoting JSON: Get-Content -Raw examples/lighthouse/01-sky-and-sea.json | uvx --from frugal-blender-mcp frugal-blender execute --params -

Captures, renders and saves go to the bridge's exports/ folder, and the CLI prints the filename.

Each running bridge writes a connection descriptor. If more than one exists, set BLENDER_COMPACT_CONNECTION to the one you want:

  • Windows: %LOCALAPPDATA%/blender-compact-mcp/connection-<pid>.json

  • Linux/macOS: ${XDG_STATE_HOME:-~/.local/state}/blender-compact-mcp/connection-<pid>.json

Ambiguous discovery fails rather than picking a scene at random. Opening a different file stops the bridge. After a crash, delete only the stale descriptor.

  • Add-on: download frugal-blender-mcp-addon-<version>.zip from Releases and use Install from Disk in Blender's add-on preferences, or run uvx frugal-blender-mcp install-addon --zip addon.zip.

  • Server from source: clone the repository, run uv sync --frozen, and point your client at uv run --directory /absolute/path/to/frugal-blender-mcp frugal-blender-mcp.

Configs that use the old blender-astra-mcp or blender-compact-mcp commands keep working.

AI client -- MCP stdio --> Python bridge -- authenticated loopback JSON --> Blender add-on
CLI ----------------------------^                                         bpy.app.timers

Blender's timer accepts bounded socket input and runs operations on Blender's main thread. No background thread touches Blender data. discover returns readable argument contracts, and the add-on validates every batch again before running it. A batch that fails partway reports which step failed and what already ran. See design.

uv sync --frozen
uv run ruff check --config pyproject.toml .
uv run ruff format --check --config pyproject.toml .
uv run pytest -q

Tests that need Blender skip unless BLENDER_EXE points at a Blender executable. Set BLENDER_TEST_UI=1 to also test interactive timers and undo. They launch separate factory-startup Blender processes and never touch your scenes or preferences. Results: validation.

scripts/demo_host.py runs a headless bridge on an empty scene for replaying examples/. scripts/bench_tool_context.py and scripts/context_chart.py reproduce the benchmark and chart.

If this saves your agent some tokens, a ⭐ helps other people find it.

MIT licensed. Independent project, not affiliated with the Blender Foundation or any model provider.

Available Tools

4 tools
captureA

PNG preview, longest edge 64..1024, scene aspect ratio: camera render or viewport (interactive only). Renders with EEVEE (fast); pass engine="CYCLES" for ray-traced quality.

ParametersJSON Schema
NameRequiredDescriptionDefault
sizeNo
viewNocamera
engineNo

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations, the description carries the full burden and does disclose meaningful traits: clamped output size (longest edge 64..1024), aspect-ratio source, and that viewport capture is interactive-only. It does not state whether the call is read-only/non-destructive, whether it blocks during a Cycles render, or whether a file is written versus data returned.

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?

Two dense sentences with the deliverable front-loaded and no filler. The middle clause ("scene aspect ratio: camera render or viewport (interactive only)") is slightly telegraphic and takes a second read, which keeps it off a 5.

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

Completeness3/5

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

For a 3-param tool with no annotations and no output schema, the description adequately covers output format and all three parameters. Gaps remain around preconditions (interactive session, existing scene/render context) and response shape, which the missing output schema leaves undocumented.

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 0%, so the description has to compensate and largely does: it explains the size clamp (longest edge 64..1024), the two view behaviors (camera render vs viewport, interactive only), and the engine default/alternative. It still omits the literal enum values and units, leaving minor guesswork.

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

Purpose4/5

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

Leads with the concrete deliverable ("PNG preview") and adds the render-pipeline details that make the intent unambiguous — an agent knows this produces a snapshot image rather than inspecting or executing code. It never names the sibling tools, but inspect/discover/execute are generic enough that the resource (a rendered preview) still separates it.

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

Usage Guidelines3/5

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

Gives parameter-level tradeoff guidance (EEVEE is the fast default, pass engine="CYCLES" for ray-traced quality), which implies when to reach for the heavier path. It says nothing about when to choose capture over the sibling tools or what state must exist before calling it.

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

discoverB

List operation summaries, or fetch one operation's arguments.

ParametersJSON Schema
NameRequiredDescriptionDefault
operationNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries the full disclosure burden. It usefully reveals the mode-switching behavior (listing vs single fetch based on the parameter), but never states that this is a read-only/no-side-effect operation, nor does it mention auth requirements or whether the listing is paginated or bounded.

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

Conciseness5/5

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

A single sentence, front-loaded with the primary list behavior and then the fetch variant. No filler or redundancy; every clause carries information.

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

Completeness2/5

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

An output schema exists so return values need not be explained, but with no annotations, zero parameter documentation, and undefined terminology ('operations') plus an ambiguous sibling set, the description is too thin for an agent to confidently choose this over 'inspect' or to know how to call it.

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

Parameters3/5

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

Schema coverage is 0% and the single 'operation' parameter is undocumented in the schema, so the description must compensate. It does explain that supplying 'operation' fetches that operation's arguments, but it does not say what form the identifier takes (name, path, ID) or where to obtain it, leaving real ambiguity.

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

Purpose4/5

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

The description names two concrete behaviors with specific verbs and resources: listing operation summaries and fetching one operation's arguments. It is clear what the tool does at a high level, but it never defines what an 'operation' is (an API route? a command?) and does nothing to distinguish itself from the sibling 'inspect', which sounds adjacent.

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

Usage Guidelines3/5

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

The dual-mode wording implies usage: call with no argument to list, call with 'operation' to fetch details. However, it gives no explicit when-to-use guidance relative to siblings 'inspect', 'execute', or 'capture', and no prerequisites or exclusions. Usage is inferred rather than stated.

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

executeB

Execute up to 100 {'op': name, ...arguments} steps. Returns counts/errors, not full scene data. dry_run checks syntax/permissions only. Runtime failures are partial, not transactional.

ParametersJSON Schema
NameRequiredDescriptionDefault
stepsYes
dry_runNo
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses the return shape ('counts/errors, not full scene data'), that dry_run is non-mutating ('syntax/permissions only'), and that runtime failures are 'partial, not transactional'. This is strong negative-consequence disclosure; only auth/permission requirements are left unstated.

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

Conciseness5/5

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

Four tight sentences, each carrying distinct information, with the batching limit and return semantics front-loaded. No filler.

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

Completeness4/5

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

For a batch/partial-failure mutation tool with an output schema, the description covers batching limits, return scope, dry-run behavior, and non-transactional failure. The unmentioned timeout param is the only notable omission.

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

Parameters3/5

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

Schema coverage is 0%, so the description must compensate. It meaningfully explains two of three params: steps as up to 100 op objects and dry_run as syntax/permission-only validation. The timeout parameter is never mentioned, leaving a real gap.

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

Purpose3/5

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

States a specific verb (Execute) and the resource shape ('{'op': name, ...arguments} steps'), and implies the domain via 'not full scene data'. However, it never says what an 'op' is or what system it operates on, and gives no differentiation from siblings inspect/discover/capture.

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

Usage Guidelines2/5

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

No guidance on when to use execute versus the sibling tools (inspect, discover, capture), and no prerequisites or exclusions stated. The dry_run note implies a validation use case but does not frame it as a when-to-use recommendation.

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

inspectB

Read a bounded scene summary; pass names for detailed object properties.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
namesNo
offsetNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full behavioral burden. 'Read' implies non-mutation, but it says nothing about permissions, error behavior, cost, or what 'bounded' actually constrains.

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

Conciseness5/5

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

A single tight sentence, front-loaded with the primary action, with the secondary mode in the following clause. No filler.

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

Completeness2/5

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

An output schema exists, so return values need no explanation, but with zero annotation coverage and three fully undocumented parameters the description is too thin for correct invocation — pagination, bounding, and failure modes are all missing.

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

Parameters2/5

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

Schema coverage is 0%, so the description must compensate. It explains only 'names' (detailed object properties); 'limit' and 'offset' are never addressed beyond the vague word 'bounded', leaving pagination semantics undocumented.

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

Purpose4/5

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

States a specific verb (read) and resource (bounded scene summary), plus a second mode via names. It reasonably separates itself from discover/execute/capture as the read/inspect tool, though 'scene summary' is domain jargon left undefined.

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

Usage Guidelines3/5

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

Implies two modes — default bounded summary vs. detailed properties when names are passed — but gives no guidance on when to prefer this over siblings like discover, and no exclusions or prerequisites.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.2.1
    • Changedcapture4 fields changed
      • addedInput schema / properties / engine
        Added value: +{
+  "type": "string"
+}
      • removedInput schema / properties / size / title
        Removed value: -"Size"
      • removedInput schema / properties / view / title
        Removed value: -"View"
      • removedInput schema / title
        Removed value: -"captureArguments"
    • Changeddiscover5 fields changed
      • removedInput schema / properties / operation / anyOf
        Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
      • removedInput schema / properties / operation / default
        Removed value: -null
      • removedInput schema / properties / operation / title
        Removed value: -"Operation"
      • addedInput schema / properties / operation / type
        Added value: +"string"
      • removedInput schema / title
        Removed value: -"discoverArguments"
    • Changedexecute5 fields changed
      • removedInput schema / properties / dry_run / title
        Removed value: -"Dry Run"
      • removedInput schema / properties / steps / items / additionalProperties
        Removed value: -true
      • removedInput schema / properties / steps / title
        Removed value: -"Steps"
      • removedInput schema / properties / timeout / title
        Removed value: -"Timeout"
      • removedInput schema / title
        Removed value: -"executeArguments"
    • Changedinspect8 fields changed
      • removedInput schema / properties / limit / title
        Removed value: -"Limit"
      • removedInput schema / properties / names / anyOf
        Removed value: -[
-  {
-    "items": {
-      "type": "string"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]
      • removedInput schema / properties / names / default
        Removed value: -null
      • addedInput schema / properties / names / items
        Added value: +{
+  "type": "string"
+}
      • removedInput schema / properties / names / title
        Removed value: -"Names"
      • addedInput schema / properties / names / type
        Added value: +"array"
      • removedInput schema / properties / offset / title
        Removed value: -"Offset"
      • removedInput schema / title
        Removed value: -"inspectArguments"
  2. 4 tool updatesv0.2.0
    • First observedcapture
    • First observeddiscover
    • First observedexecute
    • First observedinspect
Deploy Server
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

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct purpose: inspect reads Blender scene state, discover exposes the operation schema, execute mutates the scene via operations, and capture renders a preview. The read-side tools (inspect vs discover) are clearly separated as scene data versus API schema, so misselection is unlikely.

Naming Consistency5/5

All four tools use a consistent single-verb, lowercase snake_case convention (inspect, discover, execute, capture). There is no mixing of styles or noun/verb patterns, making the naming predictable.

Tool Count5/5

Four tools is well-scoped for a deliberately compact server, using a discover/execute dispatcher to cover many Blender operations without bloating the tool list. Every tool earns its place: read, schema, mutate, render.

Completeness4/5

The surface covers the core loop of discovering operations, executing them, inspecting results, and capturing previews, but lacks explicit save/export operations and relies on non-transactional partial execution. Capture is also limited to PNG stills rather than broader render outputs, though these are minor gaps workable via execute.

Maintenance

ActivityMaintained
ResponsivenessSlow

Resources

Related MCP Connectors

Related MCP Servers

  • bMCP

    niewinny
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI to control Blender 3D through the Model Context Protocol, allowing Python execution, scene state queries, and automation of 3D workflows.
    5
    GPL 3.0

  • Blender-Mind-MCP

    xiaohai-uid
    A
    license
    A
    quality
    C
    maintenance
    Enables AI-driven 3D modeling in Blender by providing tools to create primitives, apply modifiers and materials, set up lighting and cameras, capture viewport snapshots, export assets, inspect scenes, and execute Python commands via natural language.
    10
    MIT

  • Blender Universal & Token

    domainjon
    F
    license
    A
    quality
    C
    maintenance
    Enables AI agents to inspect and drive Blender scenes directly, either through a live editor bridge on port 8190 or automatically via headless background CLI when Blender is closed. Provides token-efficient tools for scene outlining, object creation and modification, modifiers, materials, rendering, asset export, and arbitrary bpy script execution.
    11
    -