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: blend-ai

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 to blender.exe

• BLENDER_TIMEOUT_SECONDS: timeout for one operation, 1~3600 seconds, default 180 seconds

• BLENDER_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.exe

Or you can run it as follows.

.\.venv\Scripts\python.exe -m blender_control_mcp.server

Since 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.server

Connecting 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 -q

In 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 -q

The 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.py that 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.