Skip to main content
Glama
deenesjakoruzh
parkspark

blender-control-mcp

by parkspark
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

blender-control-mcp

blender-control-mcp 是一个独立的 STDIO MCP 服务器，用于在本地 Windows 的 background 模式下安全地控制 Blender。它不包含 LLM、自然语言解析或任意 Python/Shell 执行功能。只能使用服务器公开的 7 个结构化工具，并且主机和 Blender 内部都会分别验证输入。

环境要求

  • Windows

  • Python 3.12 或更高版本

  • 推荐使用 Blender 5.2 LTS

  • 默认 Blender 路径：C:\Users\park\Applications\blender-5.2.0-windows-x64\blender.exe

Related MCP server: blend-ai

安装

在项目根目录下使用 PowerShell 运行。

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

如果 Blender 位于其他位置，请设置环境变量。

$env:BLENDER_EXECUTABLE = "D:\Apps\Blender\blender.exe"

可选环境变量：

  • BLENDER_EXECUTABLE：blender.exe 的路径

  • BLENDER_TIMEOUT_SECONDS：单个操作的超时时间，1~3600 秒，默认 180 秒

  • BLENDER_CONTROL_WORKDIR：只读检查操作的日志/计划存储根目录。默认值为 %TEMP%\blender-control-mcp

服务器运行

.\.venv\Scripts\blender-control-mcp.exe

或者可以按以下方式运行。

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

由于是 STDIO 服务器，正常运行时不会向 stdout 输出交互式提示或常规日志。MCP 客户端会启动该进程并通过 JSON-RPC 进行通信。

连接 Codex

Codex 支持本地 STDIO MCP 服务器，可以在用户的 ~/.codex/config.toml 或受信任项目的 .codex/config.toml 中进行配置。以下路径是使用此仓库默认位置的示例。

[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"

配置完成后，重启 Codex，并通过 /mcp 或 codex mcp list 检查连接状态。在 UI 中，也可以选择 Settings → MCP servers → Add server → STDIO 并输入相同的 command/args。最新配置项请参考 OpenAI 的 Codex MCP 文档。

通过 CLI 添加的示例如下。

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

连接其他 MCP 客户端

这是 STDIO 服务器设置格式为 JSON 的客户端的一般示例。实际配置文件位置和键名请查阅客户端文档。

{
  "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"
      }
    }
  }
}

工具

所有路径输入均为字符串。输入资源仅允许 .glb、.blend、.fbx 格式。target 必须是 all 或包含大小写在内的完全匹配名称。如果找不到或存在歧义，服务器不会随意选择，而是返回 target_not_found/ambiguous_target 错误及候选列表。

scene.inspect

输入：

{"input_path":"C:\\assets\\chair.glb"}

data.objects 中返回名称、类型、材质槽位、网格顶点/多边形数量、dimensions、location 和 Modifier 列表。

{
  "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_path":"C:\\assets\\chair.blend"}

返回示例：

{
  "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 是 01 范围的 RGB 或 RGBA，roughness、metallic、alpha 也均为 01。至少需要一个更改值。

{
  "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
}

目标为精确的材质名称，或仅有一个材质的对象名称。会同时生成修改后的 GLB、BLEND、FBX。如果一个对象有多个材质，则返回材质候选列表并要求明确选择。

asset.transform

每个向量由 3 个数字组成。scale 每个轴为 0.001~1000，且至少需要一个更改值。

{
  "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]
}

会同时生成修改后的 GLB、BLEND、FBX。

asset.add_modifier

Bevel 输入示例：

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "modifier_type":"bevel",
  "width":0.03,
  "segments":3
}

Decimate 输入示例：

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "modifier_type":"decimate",
  "ratio":0.5
}

Bevel 仅允许 width > 01000、segments 116（默认 0.1/3）。Decimate 仅允许 ratio 0.01~1（默认 0.5）。拒绝其他 Modifier 或混合参数。会同时生成修改后的三种格式。

asset.set_smooth_shading

{
  "input_path":"C:\\assets\\chair.fbx",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair"
}

为目标网格多边形设置平滑着色，并同时生成修改后的 GLB、BLEND、FBX。

asset.export

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\exports",
  "formats":["glb","blend","fbx"]
}

formats 必须是 glb、blend、fbx 中不重复的一个或多个，并且只生成请求的格式。

通用响应与产物

所有调用都会返回结构化响应。修改/导出工具会在 <output_directory>/<operation_id>/ 下生成产物，只读工具会在临时工作根目录下留下日志。

{
  "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": []
}

即使失败，也会尽可能保留 operation.json 和 blender.log，并按以下方式返回错误代码和候选列表。

{
  "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"]
  }]
}

测试

完整测试：

.\.venv\Scripts\python.exe -m pytest -q

在没有 Blender 的环境中，只有一个实际的 Blender 集成测试会自动跳过，单元测试仍会通过。

# 빠른 단위 테스트만
.\.venv\Scripts\python.exe -m pytest -m "not integration" -q

# 실제 Blender 통합 테스트만
.\.venv\Scripts\python.exe -m pytest -m integration -q

集成测试会先创建一个小型 GLB，然后在实际 Blender 中验证场景检查、材质颜色/粗糙度/透明度修改、scale 修改、Bevel 添加以及 GLB/BLEND/FBX 生成。

安全设计

  • 没有接受任意 Blender Python、Python 字符串、自然语言计划或 Shell 命令的工具。

  • 桥接器是固定的 blender_mcp_bridge.py 一个文件，并通过 allow-list 重新验证 JSON operation type/字段/值。

  • 桥接器中不包含 eval、exec、subprocess 或外部命令执行。

  • Blender 以 --background --factory-startup --disable-autoexec 方式运行。

  • 使用 subprocess.run(..., shell=False) 和参数数组，并应用超时。

  • 在启动 Blender 之前验证输入文件的存在性和扩展名。

  • 输出仅写入随机 operation ID 子文件夹，不会覆盖现有产物和原始文件。

  • 桥接器会再次确认计划、结果和产物都位于同一工作文件夹边界内。

MVP 限制

  • 不支持图像纹理像素修改、Texture Paint 和烘焙。

  • 如果 Base Color 插槽连接了纹理/节点，即使更改默认值，最终外观也可能不会改变。在这种情况下，会在 blender.log 中留下警告。

  • 材质修改仅支持具有 Principled BSDF 的材质。

  • Modifier 仅添加 Bevel 和 Decimate，不进行应用（apply）。导出格式的 exporter 如何处理评估后的结果，遵循 Blender 各格式的行为。

  • Blender 文件本身的损坏、Blender importer/exporter 错误以及格式之间的功能差异会通过结构化错误和日志报告，但不会自动修复。

  • 每次工具调用都会启动一个独立的 Blender 进程，因此对于大型资源，启动和转换成本较高。

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
A
license - permissive license
A
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

  • blend-ai

    HoldMyBeer-gg
    A
    license
    B
    quality
    B
    maintenance
    An MCP server that enables AI assistants to control Blender through 108 specialized tools for 3D modeling, animation, and rendering. It provides a secure, thread-safe interface to execute validated operations in Blender using natural language commands.
    100
    126
    AGPL 3.0

  • Blender MCP

    YellowFoxH4XOR
    F
    license
    A
    quality
    C
    maintenance
    A headless-first Model Context Protocol server for safe, deterministic Blender automation, exposing typed tools to inspect scenes and render previews without arbitrary command execution.
    3

  • blender-lab-mcp-client

    A-to-PC
    A
    license
    Not graded
    quality
    C
    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.
    MIT

View all related MCP servers

Related MCP Connectors

  • ChiR24-unreal_mcp

    Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…

  • MCP Fortress

    Security scanner for MCP servers. Detect vulnerabilities, prompt injection, and tool poisoning.

  • ChiR24-unreal_mcp_server

    A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/parkspark/blender-control-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server