Provides tools to control Blender for creating and editing scenes, performing batched operations (e.g., primitives, arrays, materials), rendering, and capturing images.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@blender-compact-mcp discover primitive, array, material, and assign_material ops"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Four tools for Blender: inspect, discover, execute, capture. Batch related edits, fetch operation arguments only when needed, and return bounded summaries.
Version 0.2 adds existing-scene editing and an unrestricted Python operation for the full Blender API, while keeping four MCP tools and on-demand operation discovery.
Existing object transforms and material editing, primitives, linked arrays, cameras and lights.
Batched modifiers, RNA properties, keyframes, frame evaluation and RNA discovery.
Full Python access for Geometry Nodes, rigging, simulations, import/export and other bpy workflows.
Discover python, then execute {"op":"python","code":"..."}. Assign result for a bounded JSON
response; bpy, params and output_dir are available in the script.
Camera or interactive viewport previews; render uses current scene resolution and supports animation.
Independent write/render/delete/save toggles and an additional Python toggle, fixed at bridge start. Python is unrestricted local code execution and can bypass all the narrower toggles. It defaults off.
Interactive undo checkpoints and explicit partial batch errors. Long operations block Blender; the MCP execute timeout is configurable and does not cancel work.
The new capabilities are not fully validated. External asset-provider integrations are not bundled. The historical benchmark below measures batching only; no cross-product token comparison is available yet.
Related MCP server: bMCP
Requirements: Blender, Python 3.11+ and uv.
Download compact_blender-0.2.0.zip from this repository's Releases.
In Blender, open Edit → Preferences → Add-ons → Install from Disk, choose the ZIP and enable Compact Blender MCP.
In the 3D Viewport sidebar (N), open Compact MCP. Review permissions and click Start bridge.
Write and render default on; delete, save and Python default off. Enable Python for full API access. Stop/restart to change permissions.
Clone this repository and run uv sync --frozen inside it.
Add the MCP command below to your client. Use an absolute path to your checkout:
{
"mcpServers": {
"blender-compact": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/blender-compact-mcp", "blender-compact-mcp"]
}
}
}If uv is not on the GUI application's PATH, set command to its absolute executable path.
Use the client's own MCP configuration format; the block above illustrates a common JSON form.
No token needs to be pasted into model context. The bridge reads the local descriptor.
For multiple Blender instances, set BLENDER_COMPACT_CONNECTION to the intended descriptor:
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 an arbitrary scene. After a crash, remove only the
stale instance's descriptor. Normal shutdown removes it; opening a different file stops the server.
First ask the agent to discover primitive, array, material, and assign_material, then:
Create a teal cube named Demo at [0,0,1], then make 49 linked copies along X. Inspect the first and last object only. Do not render until I ask.
Or use the CLI:
uv run blender-compact discover
uv run blender-compact inspect
uv run blender-compact execute --params '{"steps":[{"op":"primitive","kind":"cube","name":"Demo","location":[0,0,1]},{"op":"array","name":"Demo","count":49,"offset":[2.5,0,0],"prefix":"Copy"}]}'For PowerShell, avoid nested JSON quoting by piping a file:
Get-Content -Raw examples/scene.json | uv run blender-compact execute --params -That example creates 50 cubes, a floor, camera and lights in one batch. Names must be unique; it intentionally refuses to overwrite existing objects. Run it in a fresh scene.
uv run blender-compact capture --params '{"filename":"preview.png","size":768}'The CLI returns an output filename; MCP returns an image. Exports go under the local state
directory's exports/ folder. A repeated filename is refused. Capture does not include other apps
or take a desktop screenshot. Save exports a copy, never overwrites a file, and requires save permission.
In a real Blender test, the same 50 transforms produced identical final object properties:
Protocol payload | 50 individual calls | One batch |
Argument tokens | 1,149 | 1,002 |
Result tokens | 800 | 16 |
Total | 1,949 | 1,018 |
47.77% fewer payload tokens, using cl100k_base. Results are measured from actual requests and
responses, not guessed from characters. This isolates batching using our own bridge in both cases.
It excludes model reasoning, conversation history, caching, tool-call envelopes, images, setup and
discovery. It is not a benchmark against another product and not a claim of 47.77% lower total bills.
The agent's quality, task and client-side tool loading still matter. See validation.
AI client -- MCP stdio --> Python SDK bridge -- authenticated loopback JSON --> Blender add-on
CLI ----------------------------------------------^ bpy.app.timersBlender's timer accepts bounded socket input and executes operations on its main thread. No Python
background thread accesses Blender data. The optional Python operation has full local process privileges. discover returns
human-readable argument contracts; operations are validated again by the add-on before execution.
See design and security.
uv sync --frozen
uv run ruff check --config pyproject.toml .
uv run ruff format --check --config pyproject.toml .
uv run pytest -q
uv run python scripts/package_addon.py
uv buildWithout BLENDER_EXE, real Blender tests explicitly skip. Enable them on Windows:
$env:BLENDER_EXE = 'D:/blender/blender.exe' # use your installed path
$env:BLENDER_TEST_UI = '1' # also check actual UI timer execution and Undo
uv run pytest -qThe tests launch separate factory-startup processes. They never connect to an already-open user
scene or save user preferences. Outputs and logs go to ignored artifacts/. The UI helper is hidden
on Windows and exits automatically. Linux UI tests require a display; background tests do not.
The package ZIP contains only the add-on's Python sources. The wheel contains the MCP bridge/CLI; installing the wheel alone does not install the Blender add-on.
MIT licensed. Independent software, not affiliated with Blender or any model provider.
PNG preview (64..1024): camera render or viewport (requires interactive 3D View).
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| view | No | camera |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden. It discloses the output format (PNG), size range, and the prerequisite of an interactive 3D View. It does not mention potential side effects, failure conditions, or whether it is read-only, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the output type and size range, followed by the mode and prerequisite. It contains no wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional parameters and no output schema, the description adequately covers the output (PNG), size range, and the critical prerequisite. It does not explain error handling or what happens if the view is not interactive, but that is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only defaults with 0% coverage, so the description must compensate. It does so by explaining the size range (64..1024) and clarifying that 'view' refers to camera render or viewport, directly enriching both parameters beyond their bare schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool captures a PNG preview at sizes 64..1024, either from a camera or viewport, and requires an interactive 3D View. This is a specific verb-resource-output combination that clearly distinguishes it from siblings like inspect or execute.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly communicates a key usage requirement (interactive 3D View) and specifies the two output modes (camera or viewport). However, it does not explicitly contrast with sibling tools or state when not to use it, though the distinct purpose makes the context evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List operation summaries, or fetch one operation's arguments.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the two modes (list summaries vs. fetch arguments) and implies a read-only nature, but it does not mention any edge cases, error behavior, or whether the operation parameter accepts identifiers, names, or other forms. This is moderate transparency but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the main action ('List operation summaries') before introducing the alternative. It avoids redundancy and unnecessary details, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and an output schema provided (not shown here). The description explains the two invocation patterns but does not detail the return format or clarify how to specify an operation (e.g., by ID or name). While the output schema may cover return structure, the ambiguity around the parameter and lack of sibling differentiation make it incomplete for an agent to reliably choose and use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the parameter's meaning. It does convey that the 'operation' parameter selects which operation to fetch arguments for, and that omitting it yields a list of summaries. However, it doesn't specify the format or allowed values of the parameter (e.g., integer ID, string name), so the agent must infer this from context or trial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's dual behavior: listing operation summaries or fetching one operation's arguments. It uses specific verbs ('List' and 'fetch') and specifies the resource ('operation summaries', 'operation's arguments'), which distinguishes it from the sibling tools (inspect, capture, execute). However, it doesn't explicitly contrast itself with these siblings, so it's a step below fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the alternatives (inspect, capture, execute). The description only states what it does, not the conditions under which an agent should select it. No exclusions or alternative suggestions are provided, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| steps | Yes | ||
| dry_run | No | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the 100-step ceiling, the non-transactional partial-failure behavior, and the fact that dry_run only checks syntax/permissions. This is strong behavior context, though it does not address auth or side-effect details of individual operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the core purpose and step format. Every sentence adds essential information: scope, return type, dry_run behavior, and failure semantics. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter batch tool with an output schema, the definition covers the main contract: step shape, limit, dry_run, and partial failures. Missing timeout semantics and explicit sibling routing are the only material omissions, so it falls just short of fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does explain the steps object format and dry_run's effect, but it leaves timeout undocumented beyond its name/default. That is a notable gap for a tool with only three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Execute up to 100 ... steps') and gives the step shape as {'op': name, ...arguments}. It also distinguishes its return style from inspect/capture-style tools by saying it returns 'counts/errors, not full scene data', though it never names the sibling tools explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The dry_run note gives clear guidance for validating a batch before running it, and the partial-failure warning implies the tool should not be used where atomicity is required. However, there is no explicit when-to-use/when-not-to-use comparison with the sibling tools inspect, discover, or capture.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a bounded scene summary; pass names for detailed object properties.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| names | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Read' implies a non-mutating operation, and 'bounded' hints at pagination/limit behavior, which is transparent. However, it does not disclose details about what a scene summary includes, how names behave when null, or any edge cases. The transparency is reasonable but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with a subject-verb-object followed by a cond intuitive complement. It wastes no words, front-loading the core behavior ('Read a bounded scene summary') before explaining the secondary option (detailed properties via names).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Though the description is short, the tool has zero required params, an output schema present, and no nested objects. It explains the primary call (bounded scene summary) and the optional enhancement (names). Given the schema already details return shape, the description covers the agent's immediate needs, though 'scene summary' itself remains fuzzy without more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does add meaning: 'bounded' points to limit/offset, and 'pass names for detailed object properties' directly explains the names parameter. Yet it leaves limit and offset to inference, so the compensation is only partial, deserving a mid-range score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and explicit resource ('bounded scene summary'), and it explains the behavior of passing names to retrieve detailed object properties. It is clear about the operation's nature, though it does not name any sibling tool to distinguish itself from discover/capture/execute.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus its siblings (discover, capture, execute). There are no conditions, exclusions, or alternatives mentioned, leaving the agent to guess when this read operation is appropriate over the other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0capturediscoverexecuteinspectScored across 4 tools
Each tool targets a clear, distinct concern: inspect reads scene state, discover exposes operation metadata, capture produces visual output, and execute runs operations. There is no meaningful overlap that would cause an agent to select the wrong tool.
All four tool names are single imperative verbs (inspect, discover, capture, execute), following a consistent and predictable style. The naming makes the toolset easy to scan and matches the compact design.
Four tools is well-scoped for a compact Blender MCP server: read, discover, execute, and visualize are all core capabilities with no filler. The count fits comfortably in the ideal 3-15 range.
The toolset forms a complete workflow for controlling Blender: discover what operations exist, execute them, inspect the resulting scene, and capture a preview. Any remaining limitations are documented runtime behavior rather than missing lifecycle coverage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Cloud Blender for AI agents: scenes, assets, renders, MP4, STL, GLB — over hosted remote MCP.
Discover, inspect and run 63,000+ agent tools from one balance. Pay per call, no subscriptions.
Discover, preview, estimate, run, and retrieve reusable AI workflows.
Build and run visual creative-production workflows from your AI agent.
