blender-control-mcp
Provides tools for inspecting and modifying Blender scenes, materials, and assets, enabling operations such as applying materials, transforms, modifiers, and exporting to GLB, BLEND, and FBX formats.
Click on "Deploy 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-control-mcp Inspect the chair model at C:\assets\chair.glb"
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.
blender-control-mcp
blender-control-mcp is a standalone STDIO MCP server that safely controls Blender in background mode on local Windows. It does not include LLM, natural language interpretation, or arbitrary Python/shell execution. Only the 7 structured tools exposed by the server can be used, and inputs are validated both on the host and inside Blender.
Requirements
Windows
Python 3.12 or later
Blender 5.2 LTS recommended
Default Blender path:
C:\Users\park\Applications\blender-5.2.0-windows-x64\blender.exe
Related MCP server: blender-lab-mcp-client
Installation
Run in PowerShell from the project root.
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"If Blender is located elsewhere, set the environment variable.
$env:BLENDER_EXECUTABLE = "D:\Apps\Blender\blender.exe"Optional environment variables:
BLENDER_EXECUTABLE: path toblender.exeBLENDER_TIMEOUT_SECONDS: timeout for one operation, 1~3600 seconds, default 180 secondsBLENDER_CONTROL_WORKDIR: root for storing logs/plans of read-only inspection operations. Default is%TEMP%\blender-control-mcp
Running the server
.\.venv\Scripts\blender-control-mcp.exeOr you can run it as follows.
.\.venv\Scripts\python.exe -m blender_control_mcp.serverSince it is a STDIO server, it does not print an interactive prompt or normal logs to stdout during normal operation. The MCP client starts the process and exchanges JSON-RPC.
Connecting to Codex
Codex supports local STDIO MCP servers and can be configured in the user's ~/.codex/config.toml or in a trusted project's .codex/config.toml. The paths below are examples using the default location of this repository.
[mcp_servers.blender_control]
command = "C:/Users/park/Desktop/dev_tool/blender-control-mcp/.venv/Scripts/python.exe"
args = ["-m", "blender_control_mcp.server"]
cwd = "C:/Users/park/Desktop/dev_tool/blender-control-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 300
default_tools_approval_mode = "writes"
[mcp_servers.blender_control.env]
BLENDER_EXECUTABLE = "C:/Users/park/Applications/blender-5.2.0-windows-x64/blender.exe"
BLENDER_TIMEOUT_SECONDS = "180"After configuration, restart Codex and check the connection status with /mcp or codex mcp list. In the UI, you can also select Settings → MCP servers → Add server → STDIO and enter the same command/args. Refer to OpenAI's Codex MCP documentation for the latest configuration items.
An example of adding via CLI is as follows.
codex mcp add blender_control --env BLENDER_EXECUTABLE=C:\Users\park\Applications\blender-5.2.0-windows-x64\blender.exe -- C:\Users\park\Desktop\dev_tool\blender-control-mcp\.venv\Scripts\python.exe -m blender_control_mcp.serverConnecting to other MCP clients
A typical example for clients whose STDIO server configuration format is JSON. Check the client documentation for the actual configuration file location and key names.
{
"mcpServers": {
"blender-control": {
"command": "C:\\Users\\park\\Desktop\\dev_tool\\blender-control-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "blender_control_mcp.server"],
"env": {
"BLENDER_EXECUTABLE": "C:\\Users\\park\\Applications\\blender-5.2.0-windows-x64\\blender.exe"
}
}
}
}Tools
All path inputs are strings. Input assets only accept .glb, .blend, and .fbx. target must be all or a name that matches exactly, including case. If not found or ambiguous, the server does not make an arbitrary selection and instead returns a target_not_found/ambiguous_target error along with a list of candidates.
scene.inspect
Input:
{"input_path":"C:\\assets\\chair.glb"}data.objects returns name, type, material slots, mesh vertex/polygon counts, dimensions, location, and Modifier list.
{
"success": true,
"data": {
"object_count": 1,
"objects": [{
"name": "Chair",
"type": "MESH",
"material_slots": ["Wood"],
"vertex_count": 1200,
"polygon_count": 800,
"dimensions": [1.0, 1.1, 1.8],
"location": [0.0, 0.0, 0.0],
"modifiers": []
}]
}
}material.list
Input:
{"input_path":"C:\\assets\\chair.blend"}Example response:
{
"success": true,
"data": {
"material_count": 1,
"materials": [{
"name": "Wood",
"base_color": [0.4, 0.2, 0.1, 1.0],
"roughness": 0.55,
"metallic": 0.0,
"alpha": 1.0,
"base_color_texture_linked": true
}]
}
}asset.apply_material
base_color is an RGB or RGBA in the 01 range, and roughness, metallic, and alpha are also 01. At least one changed value is required.
{
"input_path":"C:\\assets\\chair.glb",
"output_directory":"C:\\assets\\outputs",
"target":"Wood",
"base_color":[0.1,0.3,0.8,0.75],
"roughness":0.25,
"alpha":0.75
}Target an exact material name or an object name that has only one material. Generates modified GLB, BLEND, and FBX files. If an object has multiple materials, material candidates are returned and an explicit selection is required.
asset.transform
Each vector is 3 numbers. scale is 0.001~1000 per axis, and at least one changed value is required.
{
"input_path":"C:\\assets\\chair.glb",
"output_directory":"C:\\assets\\outputs",
"target":"Chair",
"location":[0,0,1],
"rotation_degrees":[0,0,90],
"scale":[1.2,1.2,1.2]
}Generates modified GLB, BLEND, and FBX files.
asset.add_modifier
Bevel input example:
{
"input_path":"C:\\assets\\chair.blend",
"output_directory":"C:\\assets\\outputs",
"target":"Chair",
"modifier_type":"bevel",
"width":0.03,
"segments":3
}Decimate input example:
{
"input_path":"C:\\assets\\chair.blend",
"output_directory":"C:\\assets\\outputs",
"target":"Chair",
"modifier_type":"decimate",
"ratio":0.5
}Bevel only accepts width > 01000 and segments 116 (default 0.1/3). Decimate only accepts ratio 0.01~1 (default 0.5). Other Modifiers or mixed parameters are rejected. Generates all three modified formats.
asset.set_smooth_shading
{
"input_path":"C:\\assets\\chair.fbx",
"output_directory":"C:\\assets\\outputs",
"target":"Chair"
}Sets smooth shading on the target mesh polygons and generates modified GLB, BLEND, and FBX files.
asset.export
{
"input_path":"C:\\assets\\chair.blend",
"output_directory":"C:\\assets\\exports",
"formats":["glb","blend","fbx"]
}formats must contain one or more of glb, blend, fbx without duplicates, and only the requested formats are generated.
Common responses and artifacts
Every call returns a structured response. Modification/export tools create artifacts in <output_directory>/<operation_id>/, and read tools leave logs under the temporary work root.
{
"success": true,
"operation_id": "9bc12a7f57f24f8ba9d9af2f78de3041",
"operation": "asset.export",
"artifacts": [
"C:\\assets\\exports\\9bc12a7f57f24f8ba9d9af2f78de3041\\chair.glb"
],
"summary": "asset.export completed successfully",
"data": {"formats":["glb"],"artifact_count":1},
"operation_path": "...\\operation.json",
"log_path": "...\\blender.log",
"log_excerpt": "Blender 5.2.0 ...",
"command": ["...\\blender.exe","--background","..."],
"exit_code": 0,
"errors": []
}On failure, operation.json and blender.log are also written when possible, and an error code and candidates are returned as follows.
{
"success": false,
"summary": "object target 'Seat' was not found",
"artifacts": [],
"errors": [{
"code": "target_not_found",
"message": "object target 'Seat' was not found",
"candidates": ["Chair", "Table"]
}]
}Testing
Full test suite:
.\.venv\Scripts\python.exe -m pytest -qIn environments without Blender, only the actual Blender integration test is automatically skipped, and unit tests pass.
# 빠른 단위 테스트만
.\.venv\Scripts\python.exe -m pytest -m "not integration" -q
# 실제 Blender 통합 테스트만
.\.venv\Scripts\python.exe -m pytest -m integration -qThe integration test creates a small GLB and then verifies scene inspection, material color/roughness/transparency changes, scale changes, Bevel addition, and GLB/BLEND/FBX generation in actual Blender.
Security design
There are no tools that accept arbitrary Blender Python, Python strings, natural language plans, or shell commands.
The bridge is a single fixed
blender_mcp_bridge.pythat re-validates JSON operation type/fields/values against an allow-list.The bridge has no
eval,exec,subprocess, or external command execution.Blender runs with
--background --factory-startup --disable-autoexec.subprocess.run(..., shell=False)with an argument array is used, and a timeout is applied.Input files are validated for existence and extension before Blender runs.
Output is written only to a random operation ID subfolder and never overwrites existing artifacts or originals.
The bridge re-checks that the plan, results, and artifacts all stay within the same operation folder boundary.
MVP limitations
Image texture pixel editing, Texture Paint, and baking are not supported.
For materials where a texture/node is connected to the Base Color socket, changing the default value may not change the final appearance. In this case, a warning is written to
blender.log.Material changes only support materials with Principled BSDF.
Modifiers only add Bevel and Decimate and do not apply them. How each export format's exporter handles the evaluated result follows Blender's per-format behavior.
Corruption of the Blender file itself, Blender importer/exporter errors, and cross-format feature differences are reported as structured errors and logs but are not automatically recovered.
Each tool call starts a separate Blender process, so startup and conversion costs are high for large assets.
Available Tools
7 toolsasset.add_modifierA
Add only a Bevel or Decimate modifier to exact target mesh objects.
Bevel accepts width >0..1000 and segments 1..16 (defaults 0.1 and 3). Decimate accepts ratio 0.01..1 (default 0.5). Parameters for the other modifier are rejected. Creates new GLB, BLEND, and FBX files without changing the input.
Inputs: target (required), input_path (required), modifier_type (required), output_directory (required), +3 more. Returns: data, errors, command, success, +8 more
asset.apply_materialA
Change only allow-listed Principled BSDF values and create new GLB, BLEND, and FBX files.
target is 'all', an exact material name, or an exact object name with exactly one material. base_color accepts normalized RGB or RGBA. Scalar values are 0..1. The input is never overwritten; outputs and logs go into a unique job subfolder.
Inputs: target (required), input_path (required), output_directory (required), alpha, +3 more. Returns: data, errors, command, success, +8 more
asset.exportA
Export the complete asset to a non-empty unique list of GLB, BLEND, and/or FBX formats.
Outputs and logs are isolated in a new operation-ID subfolder. The input is never overwritten.
Inputs: formats (required), input_path (required), output_directory (required). Returns: data, errors, command, success, +8 more
asset.set_smooth_shadingA
Enable smooth shading on 'all' mesh objects or one exact mesh object.
Creates new GLB, BLEND, and FBX files in a unique job subfolder; never overwrites input.
Inputs: target (required), input_path (required), output_directory (required). Returns: data, errors, command, success, +8 more
asset.transformA
Set explicit location, Euler rotation in degrees, and/or scale on target objects.
Each supplied vector must have exactly three finite numbers. target is 'all' or an exact object name. Creates new GLB, BLEND, and FBX files without changing the input.
Inputs: target (required), input_path (required), output_directory (required), scale, +2 more. Returns: data, errors, command, success, +8 more
material.listBRead-onlyIdempotent
List materials and Principled BSDF Base Color, Roughness, Metallic, and Alpha values.
Also reports whether Base Color is node-linked, since a linked texture can visually override the socket's default value. The source file is never modified.
Inputs: input_path (required). Returns: data, errors, command, success, +8 more
scene.inspectARead-onlyIdempotent
Open one GLB, FBX, or BLEND asset in headless Blender and return its scene structure.
Returns object names/types, material slots, mesh vertex/polygon counts, dimensions, locations, and modifier names/types. The source file is never modified.
Inputs: input_path (required). Returns: data, errors, command, success, +8 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool addresses a distinct resource and action. Read-only tools (scene.inspect, material.list) are clearly separated from write operations (apply_material, transform, add_modifier, set_smooth_shading, export), and no two tools overlap in purpose. An agent could select the correct tool without ambiguity.
Tools follow a consistent <domain>.<action> pattern using dots (e.g., scene.inspect, asset.transform), but action verbs vary in style (e.g., 'apply_material' vs 'transform' vs 'export'). This is a minor inconsistency, but the pattern is predictable and readable.
With 7 tools, the server is well-scoped for asset inspection, material editing, transformations, modifiers, shading, and export. Each tool serves a clear purpose without redundancy or bloat, fitting comfortably in the ideal 3-15 range.
The surface covers common asset editing workflows (inspect, modify, export), but lacks removal operations such as deleting objects, removing modifiers, or changing material assignments. These gaps could cause dead ends in more complex pipelines, though core workflows are functional.
Maintenance
Related MCP Connectors
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
6 3D/CAD MCP tools: STL repair, OBJ/GLB/SVG conversion, slicing, G-code M600, SVG optimize.
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceWindows-optimized MCP server that enables control of Blender 4.0+ through 21+ tools for scene management, object manipulation, and asset downloads from PolyHaven, Sketchfab, Hyper3D, and Hunyuan3D.16MIT
- AlicenseAqualityDmaintenanceMCP server for Blender that connects to the official Blender Lab add-on, exposing 27 tools for scene manipulation, object editing, materials, rendering, and Python execution through the add-on's actual wire protocol.271MIT
- AlicenseCqualityBmaintenanceEnables secure, local automation of Blender through typed MCP tools for scene, modeling, material, animation, rendering, and file workflows via an authenticated loopback bridge.173MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible clients to control Blender for modeling, materials, animation, physics, rendering, scene inspection, documentation search, and asset/generation service integration. It exposes a stdio endpoint with many Blender operations for creating and editing 3D content.AGPL 3.0