Skip to main content
Glama
blender-control-mcp

blender-control-mcp

by parkspark

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

Available Tools

7 tools
asset.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.listB
Read-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.inspectA
Read-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

    A3.9/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      27
      1
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables secure, local automation of Blender through typed MCP tools for scene, modeling, material, animation, rendering, and file workflows via an authenticated loopback bridge.
      173
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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