Subhuti Blender MCP
Allows controlling a local Blender instance via natural language or code, including executing arbitrary Python/bpy code in Blender's main thread, checking connection status, summarizing scene objects, and querying object transforms, mesh statistics, and materials.
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., "@Subhuti Blender MCPWhat objects are in the Blender scene?"
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.
Subhuti Blender MCP
通过 MCP 协议用自然语言/代码控制本机 Blender 的桥梁项目。
架构
┌──────────────┐ stdio (JSON-RPC) ┌───────────────────┐ HTTP (127.0.0.1:9876) ┌──────────────────┐
│ MCP 客户端 │ ──────────────────▶ │ MCP Server │ ───────────────────────▶ │ Blender 插件 │
│ WorkBuddy / │ │ mcp_server/ │ │ blender_addon/ │
│ Claude 等 │ ◀────────────────── │ server.py │ ◀─────────────────────── │ subhuti_..._mcp.py│
└──────────────┘ └───────────────────┘ └──────────────────┘
工具调用 转发请求/结果 主线程执行 bpy 代码Blender 插件:启动一个本地 HTTP 服务,所有
bpy代码调度到 Blender 主线程执行(bpy 线程不安全的唯一解法)。GUI 模式用bpy.app.timers轮询,无头模式(-b)用脚本主循环。MCP Server:stdio 协议,把工具调用翻译成 HTTP 请求转发给 Blender。
客户端:任何 MCP 客户端(WorkBuddy、Claude Desktop、mcp inspector 等)。
Related MCP server: Blender MCP Server
目录结构(标准 src 布局)
subhuti-blender-mcp/
├── src/subhuti_blender_mcp/ # 主包(可安装、可导入)
│ ├── __main__.py # 入口:python -m subhuti_blender_mcp
│ ├── config.py # 配置模块(环境变量统一管理)
│ ├── core/ # 核心应用服务
│ │ └── mcp_server.py # MCP Server 定义 + 4 个工具
│ └── utils/ # 基础工具
│ └── http_client.py # 与 Blender 桥通信的 HTTP 封装
├── blender_addon/ # 部署物:Blender 插件(独立于 Python 包)
│ └── subhuti_blender_mcp.py
├── scripts/ # 辅助启动脚本
│ ├── start_blender_gui.py
│ └── start_blender_headless.py
├── tests/ # 测试
│ ├── test_client.py # stdio 端到端测试
│ └── debug_client.py # HTTP 模式调试客户端
├── pyproject.toml # 构建配置(src 布局)
├── requirements.txt
└── README.md分层职责:
core/ = 核心应用服务:MCP 协议、工具定义,只关心"提供什么能力"
utils/ = 基础工具:无业务语义的通用能力(HTTP 封装),可被任意模块复用
config.py = 配置集中管理,环境变量不散落在代码里
blender_addon/ 单独放是因为它是部署到 Blender 的产物(import bpy,依赖 Blender 内置 Python),不属于可安装的 Python 包
安装包(src 布局需要先安装才能 import):
.venv/bin/python -m pip install -e .快速开始
1. 安装为正式 Addon(推荐,Blender 启动即用)
# 复制插件到 Blender 用户级 addons 目录
mkdir -p "$HOME/Library/Application Support/Blender/4.3/scripts/addons"
cp blender_addon/subhuti_blender_mcp.py \
"$HOME/Library/Application Support/Blender/4.3/scripts/addons/"
# 启用并保存为用户偏好(只需一次,之后 Blender 启动自动加载)
/Applications/Blender.app/Contents/MacOS/Blender -b -y --python-expr "
import bpy, addon_utils
addon_utils.enable('subhuti_blender_mcp', default_set=True, persistent=True)
bpy.ops.wm.save_userpref()
"之后正常双击打开 Blender 即可,插件随启动自动加载,无需任何参数。 也可以在 Blender 偏好设置 → 插件 → 搜索 "Subhuti Blender MCP" 勾选启用。
1b. 打包分发(zip 一键安装)
make package # 生成 dist/subhuti_blender_mcp.zip安装 zip(两种方式任选):
GUI(最常用):Blender → 偏好设置 → 插件 → 右上角"安装(Install...)"→ 选择 zip → 勾选启用
命令行:
/Applications/Blender.app/Contents/MacOS/Blender -b -y --python-expr " import bpy, addon_utils bpy.ops.preferences.addon_install(filepath='dist/subhuti_blender_mcp.zip') addon_utils.enable('subhuti_blender_mcp', default_set=True, persistent=True) bpy.ops.wm.save_userpref() "
分发给别人:直接发 zip,对方 Install from Disk 即可。zip 已内置 MCP Server 源码(mcp_server/ 目录),插件加载时会自动 uv tool install 本地源码——装插件 = 桥 + 翻译官一次到位,不用手动装 MCP Server 侧。
修改插件源码后需重新
make package再安装;已装环境可直接重新拷贝blender_addon/subhuti_blender_mcp.py覆盖后重启 Blender。 修改 MCP Server 代码(src/)后:重新make package分发(zip 内的mcp_server/会更新),本机开发直接uv tool install .。
2. 连通性自检
curl --noproxy '*' http://127.0.0.1:9876/health
# {"status": "ok", "blender": "4.3.2", "background": false, ...}提示:如本机配置了 HTTP 代理,curl 请加
--noproxy '*',否则可能得到 502。
3. 端到端测试(MCP 协议全链路)
.venv/bin/python tests/test_client.py预期输出:4 个工具依次调用成功,包括在 Blender 里新建物体并保存文件。
无头模式(自动化/CI)
正式 Addon 的无头模式(-b)下进程会随启动退出,不适合自动化。
自动化请改用脚本方式(脚本内含主循环,进程常驻):
.venv/bin/python scripts/start_blender_headless.py /Users/hezenghui/Public/blender/cli_test.blendMakefile 管理(启动 / 关闭 / 状态 / 日志)
make run-logs # ★ 前台日志模式:启动 + 日志实时滚动,Ctrl+C 统一关闭(推荐日常)
make start # 后台启动 Blender(GUI) + MCP Server(HTTP),启动前自动清理残留实例
make start-headless # 同上,但 Blender 无头模式(自动化/CI)
make stop # 彻底关闭所有相关进程(SIGTERM + 兜底 SIGKILL)
make status # 查看各组件运行状态
make logs # 查看当前会话日志
make clean # stop + 删除日志/运行时文件自动清理:所有
start*/run-logs都会先执行stop,把其他位置启动的 Blender 桥和 MCP Server 实例关掉,避免端口冲突。日志模式:
run-logs前台运行,Blender 与 MCP Server 的输出实时滚动打印到终端,同时落盘logs/blender.log与logs/mcp.log(每次启动自动清空旧日志);make logs查看历史、make status看运行状态。指定文件:
make run-logs BLEND_FILE=/path/to/file.blend
开发调试(PyCharm 里断点调试 MCP)
MCP Server 支持两种传输模式,生产用 stdio,开发调试用 HTTP(PyCharm 直接 F5 运行 + 打断点):
# 终端 1:以 HTTP 模式启动 server(默认 127.0.0.1:8100/mcp)
BLENDER_MCP_TRANSPORT=http .venv/bin/python -m subhuti_blender_mcp
# 终端 2 / PyCharm 调试:触发调用(server 端断点会命中)
.venv/bin/python tests/debug_client.py在 PyCharm 里:
core/mcp_server.py中任意工具函数打断点 → F5 运行(配置环境变量BLENDER_MCP_TRANSPORT=http,入口选__main__.py)→ 运行tests/debug_client.py触发 → 断点命中、可单步。也可以用官方 Inspector 可视化调试:
npx @modelcontextprotocol/inspector后连接http://127.0.0.1:8100/mcp。调试建模代码:在 PyCharm 里把 bpy 代码片段作为字符串传给
blender_run_code,返回的 stdout 就是 Blender 里 print 的输出;建模逻辑写在tests/debug_client.py里可以全程打断点。
可用工具
工具 | 说明 |
| 检查与 Blender 的连接状态 |
| 在 Blender 主线程执行任意 Python 代码(可用 |
| 列出场景中所有对象(名称/类型/可见性) |
| 查询对象的位置、旋转、缩放、网格统计、材质 |
接入 MCP 客户端
WorkBuddy(本机)
第一步:把 MCP Server 装成全局命令(一次性)
# 安装全局命令 subhuti-blender-mcp(依赖自动装进独立环境,不污染项目 venv)
uv tool install .
# 把 ~/.local/bin 加入 PATH(或 uv tool update-shell),之后可直接使用该命令不装全局命令也可以:直接用项目 venv 方式(
command指到.venv/bin/python,args为["-m", "subhuti_blender_mcp"])。 改了 server 源码后重新执行uv tool install .即可更新全局命令。
第二步:编辑 ~/.workbuddy/mcp.json(如不存在则创建):
{
"mcpServers": {
"blender-mcp": {
"command": "/Users/hezenghui/.local/bin/subhuti-blender-mcp",
"args": [],
"env": {
"BLENDER_MCP_HOST": "127.0.0.1",
"BLENDER_MCP_PORT": "9876"
}
}
}
}然后在 WorkBuddy 的连接器管理页右上角"自定义连接器"里对该服务点击 信任 即可启用。
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json 中 mcpServers 增加同名配置。
环境变量
变量 | 默认值 | 说明 |
|
| 监听地址(不要改成非回环地址,存在安全风险) |
|
| 监听端口(Blender 侧与 MCP Server 侧需一致) |
|
| 插件自动安装 MCP Server 时的包来源(本地开发可设为项目目录) |
|
| 插件加载时是否自动安装缺失的 MCP Server( |
插件的环境自检与自动安装
插件加载(register)时自动执行一次环境自检:
检测 subhuti-blender-mcp 命令 → 已装:打印 "MCP Server 已就绪"
→ 未装 + 自动安装开启:后台 uv tool install(不阻塞 Blender)
→ 未装 + 未找到 uv:打印手动安装指引这样对方只需装好插件,MCP Server 环境会自动备好,不用手动装依赖。
发布到 PyPI 前,请把
SUBHUTI_MCP_PACKAGE指向你的包来源(本地项目目录或发布地址),避免从 PyPI 拉到同名第三方包。自动安装是后台线程执行,不阻塞 Blender 启动;失败仅打印警告,不影响插件本身。
安全说明
该桥允许执行任意 Python 代码,功能等价于在 Blender 里开 Python 控制台,仅供本机可信环境使用。
默认只监听
127.0.0.1,请勿暴露到公网。
常见问题
Q: MCP Server 报 Connection refused?
A: Blender 未启动或插件未加载成功,先确认 curl http://127.0.0.1:9876/health 能返回 JSON。
Q: 无头模式下 bpy.context.object 报错?
A: 无头模式没有 active object 概念,改用 bpy.context.view_layer.objects.active 或直接索引 bpy.data.objects。
Q: GUI 模式看不到视口刷新?
A: 确认是 GUI 模式启动(脚本在 -b 参数下运行就是无头模式),且 RPC 请求已正确返回。
Available Tools
4 toolsblender_object_infoA
查询指定对象的属性:位置、旋转、缩放、网格顶点/面数、材质。
| Name | Required | Description | Default |
|---|---|---|---|
| object_name | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It does communicate a read-only query intent through '查询', which is useful. However, it does not disclose behavior for missing objects, whether all listed attributes are always returned, or any execution constraints, leaving gaps beyond the basic read-only implication.
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, efficient sentence that front-loads the action and then lists the specific data points returned. There is no filler, repetition, or unnecessary detail.
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 one-parameter read-only tool with an output schema, the description covers the core return fields. However, it lacks guidance on when to use it versus blender_scene_summary, does not mention error behavior, and relies entirely on the output schema to communicate the result shape. This is adequate but has clear gaps.
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%, and the single parameter object_name has no schema-level explanation. The description adds minimal value by linking '指定对象' to the object_name parameter, but it does not explain naming conventions, how to reference nested objects, or what happens when the name is invalid. The parameter is self-explanatory enough to earn a baseline 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 ('查询' / query) and resource ('指定对象' / specified object), and enumerates the exact attributes returned: position, rotation, scale, mesh vertex/face count, and materials. This clearly distinguishes it from the sibling tools like blender_scene_summary or blender_run_code.
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 description gives no guidance on when to prefer this tool over its siblings, nor does it mention any exclusions or prerequisites. There is no reference to blender_scene_summary for scene-level queries or to blender_run_code for arbitrary operations, so the agent is left to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
blender_run_codeA
在 Blender 主线程执行一段 Python 代码(可直接使用 bpy、C、D),返回标准输出。
示例:创建立方体并移动 import bpy bpy.ops.mesh.primitive_cube_add(size=2, location=(1, 0, 0)) print('created:', bpy.context.object.name)
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It correctly notes main-thread execution and stdout return, but it does not mention that code can mutate scenes, that mutations persist, what happens on exceptions, or any Blender state prerequisites. For an arbitrary code execution tool, this is a significant transparency gap.
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 compact and front-loaded with the core behavior, followed directly by a useful, concrete example. Every sentence and code line earns its place; there is no filler.
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?
Although an output schema exists and the parameter surface is minimal, this is a high-complexity, potentially destructive tool with no annotations. The description omits side-effect warnings, error behavior, Blender startup/runtime requirements, and timeout or safety considerations. An agent could call it correctly for a trivial example, but not fully understand the consequences in real use.
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 coverage is 0%, so the description must explain the 'code' parameter. It does so beyond the schema by stating the code is Python, runs in the Blender main thread, can use bpy/C/D, and by providing a complete runnable example. It stops short of documenting error formats or execution limits, but the essential semantics are clear.
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 states a specific action: executing Python code in Blender's main thread, with access to bpy, C, and D, and returning standard output. This clearly distinguishes it from the sibling read-only tools like blender_status and blender_scene_summary, even without naming them.
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?
Usage is implied: use this tool when arbitrary Blender Python code must run, as shown by the cube-creation example. However, the description does not explicitly say when to prefer this over the sibling tools, nor does it warn against using it for simple queries that those tools may serve.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
blender_scene_summaryA
返回 Blender 当前场景的对象清单(名称 / 类型 / 可见性)。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavior burden. The verb '返回' (returns) strongly implies a read-only operation with no side effects, and the description provides no conflicting cues. Yet it does not explicitly state read-only behavior, error conditions, or performance implications, which prevents a higher score.
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 delivers the verb, resource, and result fields without any redundancy. Every piece of information is essential, and the parenthetical list provides precision without clutter.
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 zero-parameter read-only summary tool, the description covers the essential context: resource scope ('current scene') and the result fields. An output schema exists to further specify return values. Minor gaps include not stating whether empty scenes produce an empty list or whether ordering is guaranteed, but these are non-critical for typical use.
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 tool has zero parameters and an empty input schema, so there is no parameter ambiguity. The description adds value by clarifying the output content, which is especially useful given the baseline of 4 for parameterless tools.
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 operation (returns), the resource (object list of the current Blender scene), and the exact fields included (name/type/visibility). This distinguishes it from siblings like blender_object_info (single-object details) and blender_status (status overview), making the tool's purpose unambiguous.
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 description implies the tool is used when an agent needs an overview of objects in the current scene. However, it does not explicitly mention alternative tools or conditions for when not to use this tool, so guidance is only implicit rather than prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
blender_statusA
检查与 Blender 的连接状态,返回 Blender 版本等基本信息。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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 does reveal the read-only nature ('检查') and the returned data, but it does not state whether calling this can initiate a connection, what happens if Blender is unavailable, or explicitly guarantee no side effects, leaving a moderate transparency gap.
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 one sentence, front-loads the action ('检查连接状态'), and wastes no words. Every element—purpose, target, and output—is included without 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 zero-parameter status tool with an output schema present, the description is mostly complete: purpose and return content are stated, and return details can be inferred from the output schema. It only lacks an explicit mention of connection-failure behavior or placement as a prerequisite step.
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 tool has zero parameters and schema description coverage is 100%, so there are no parameter meanings the description must clarify. The baseline for 0-parameter tools is 4, and the description adds nothing misleading about 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 uses a specific verb-object pair ('检查与 Blender 的连接状态') and states a concrete output ('返回 Blender 版本等基本信息'). This clearly separates it from sibling tools like blender_run_code, blender_scene_summary, and blender_object_info, which all target different operations.
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 use case is clear from the description: call this when needing to verify Blender availability/connection and retrieve basic version info. It does not explicitly list exclusions or alternatives, but there are no plausible competing status tools among the siblings, so the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.2.0- First observed
blender_object_info - First observed
blender_run_code - First observed
blender_scene_summary - First observed
blender_status
TDQS
Scored across 4 tools
四个工具分别对应连接状态、代码执行、场景概览和对象属性查询,职责边界清晰,一个操作只对应一个工具,不会让 Agent 产生选择歧义。
所有工具均以 blender_ 前缀和 snake_case 命名,整体风格统一;但 blender_status、blender_scene_summary 是名词式,而 blender_run_code 是动词式,未完全遵循同一 verb_noun 模式,存在轻微不一致。
共 4 个工具,覆盖连接检查、执行、场景概览和对象详情,面向 Blender 交互的职责适中,每个工具都有独立且必要的用途。
blender_run_code 作为通用执行入口弥补了大量直接操作工具的缺失,配合场景清单和对象信息可完成核心查询与操作;但缺少渲染、文件保存等更专门的 Blender 工作流工具,存在可绕过的小缺口。
Maintenance
Related MCP Connectors
Cloud Blender for AI agents: scenes, assets, renders, MP4, STL, GLB — over hosted remote MCP.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Related MCP Servers
- AlicenseCqualityAmaintenanceEnables AI-powered control of Blender through natural language, allowing users to create, manipulate, and automate 3D scenes, objects, materials, animations, and more via Claude or other MCP clients.7144MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to control Blender via MCP tools for scene manipulation, material assignment, rendering, and Python script execution.131 PyPI26MIT
- AlicenseNot gradedqualityCmaintenanceEnables any MCP client to drive Blender 5.2 LTS through natural language, with tools for scene inspection, object creation and transformation, material and modifier handling, rendering, viewport capture, and guarded Python execution.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables any MCP client to control Blender 5.2 LTS via natural language, including scene creation, object manipulation, material assignment, rendering, and Python execution.1MIT