Blender MCP

English | 中文

<!-- Badges -->

---

<a name="english"></a>

English

MCP server integration for AI-assisted Blender automation.

Layered Tool Architecture

Blender MCP uses a four-layer tool architecture with 29 specialized tools organized by intent:

Layer	Tool Count	Purpose
Perception	11 tools	Read Blender state deeply with controllable granularity
Declarative Write	4 tools	Node editor (6 contexts) + Animation + VSE Sequencer + Mesh editing
Imperative Write	9 tools	Object/Material/Modifier/UV/Constraint/Physics/Scene
Fallback	5 tools	execute_operator + execute_script + import_export + render + batch

Perception Layer (11 tools):

Tool	Description
blender_get_objects	List/scene objects with filters
blender_get_object_data	Deep object data (12 include options)
blender_get_node_tree	Read any node tree (6 contexts)
blender_get_animation_data	Keyframes/NLA/drivers/shape keys
blender_get_materials	Material asset list
blender_get_scene	Scene-level global info
blender_get_collections	Collection hierarchy tree
blender_get_armature_data	Armature/bone hierarchy/constraints/poses
blender_get_images	Texture/image asset list
blender_capture_viewport	Viewport screenshot
blender_get_selection	Current selection/mode/active object

Declarative Write Layer (4 tools):

Tool	Description
blender_edit_nodes	Edit any node tree (add/remove/connect/disconnect/set_value) ⭐ Core
blender_edit_animation	Edit animation (keyframe/NLA/driver/shape_key/frame_range)
blender_edit_sequencer	Edit VSE video sequence (strip/transition/effect)
blender_edit_mesh	Edit mesh data (vertices/edges/faces)

Imperative Write Layer (9 tools):

Tool	Description
blender_create_object	Create scene objects (MESH/LIGHT/CAMERA/CURVE/EMPTY/ARMATURE/TEXT)
blender_modify_object	Transform/parent/visibility/rename/delete
blender_manage_material	Material create/PBR edit/assign/duplicate/delete
blender_manage_modifier	Modifier add/configure/apply/delete/reorder
blender_manage_collection	Collection create/delete/object link/hierarchy/visibility
blender_manage_uv	UV unwrap/seam/pack/layer management
blender_manage_constraints	Object/bone constraint add/configure/delete
blender_manage_physics	Physics simulation add/configure/bake
blender_setup_scene	Render engine/world environment/timeline config

Fallback Layer (5 tools):

Tool	Description
blender_execute_operator	Execute any bpy.ops.* operator
blender_execute_script	Execute arbitrary Python code (⚠️ use with caution)
blender_import_export	Import/export asset files (FBX/OBJ/GLTF/USD/Alembic/STL/etc.)
blender_render_scene	Render scene to image/video
blender_batch_execute	Execute multiple tool calls in a single request (performance optimization)

Note: All tools use blender_ prefix to avoid conflicts in multi-server environments. Tool names follow MCP specification with underscores. Payload wrapper is removed - all parameters are exposed directly as top-level inputSchema properties.

Tool Naming: All tools use the blender_ prefix to avoid conflicts in multi-server environments.

Features

• Undo Support: All write operations push to Blender's undo stack — Ctrl+Z works correctly.
• Localized Blender Support: Works in any Blender language. Uses English display names like "Principled BSDF" and they resolve to localized names automatically.
• Error Reporting: Detailed error messages from the addon are surfaced in MCP tool responses.
• Progress Notifications: MCP progress notifications for long-running operations (render, import/export). Clients can include progressToken in _meta field to receive real-time progress updates.

Progress Notifications

Blender MCP supports MCP progress notifications for long-running operations. To receive progress updates:

// Client request with progressToken
{
  "method": "tools/call",
  "params": {
    "name": "blender_render_scene",
    "arguments": {"output_path": "/tmp/render.png"},
    "_meta": {"progressToken": "render-123"}
  }
}

// Server sends progress notifications
{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "render-123",
    "progress": 50,
    "total": 100,
    "message": "Rendering frame 50/100"
  }
}

Safety features:

• Rate limited to 100ms minimum interval between notifications
• Progress messages truncated to 1000 characters
• Maximum 100 concurrent progress tokens
• Thread-safe notification output

Known Limitations (Blender 5.1)

Limitation	Cause
VSE strip creation fails	Blender 5.1 timer context API restriction
Compositor node editing fails	Blender 5.1 timer context API restriction
Object pointer properties can't be set	MCP set_property limitation
Multi-material slot creation	MCP assign only replaces slot 0

Quick Start

New to Blender MCP? See the 5-Minute Quick Start Guide for step-by-step setup instructions.

// Create a cube
{
  "name": "MyCube",
  "object_type": "MESH",
  "primitive": "cube",
  "size": 2.0
}

// Move it
{
  "name": "MyCube",
  "location": [1, 2, 3]
}

// Add a subdivision modifier
{
  "action": "add",
  "object_name": "MyCube",
  "modifier_name": "Subdivision",
  "modifier_type": "SUBSURF",
  "settings": {"levels": 2}
}

// Read object data
{
  "name": "MyCube",
  "include": ["summary", "modifiers"]
}

// Capture viewport
{
  "shading": "SOLID",
  "format": "PNG"
}

Installation

Blender Addon

1. Copy or symlink src/blender_mcp_addon/ to your Blender addons folder:

   • Windows: %APPDATA%\Blender\<version>\scripts\addons\blender_mcp_addon
   • macOS: ~/Library/Application Support/Blender/<version>/scripts/addons/blender_mcp_addon
   • Linux: ~/.config/blender/<version>/scripts/addons/blender_mcp_addon

2. In Blender: Edit > Preferences > Add-ons > Search "Blender MCP" > Enable

3. Configure and click "Start Server"

MCP Server

# Recommended: one-line install & run
uvx ageless-blender-mcp

# Or install globally
pip install ageless-blender-mcp
blender-mcp

# Or from source
uv sync
python -m blender_mcp.mcp_protocol

Supported MCP Clients

<details> <summary>Click to expand client list</summary>

Client	Documentation
Amp	docs/clients/amp.md
Antigravity	docs/clients/antigravity.md
Claude Code	docs/clients/claude-code.md
Cline	docs/clients/cline.md
Codex	docs/clients/codex.md
Copilot CLI	docs/clients/copilot-cli.md
Copilot / VS Code	docs/clients/vs-code-copilot.md
Cursor	docs/clients/cursor.md
Factory CLI	docs/clients/factory-cli.md
Gemini CLI	docs/clients/gemini-cli.md
Gemini Code Assist	docs/clients/gemini-code-assist.md
JetBrains AI Assistant	docs/clients/jetbrains.md
Kiro	docs/clients/kiro.md
OpenCode	docs/clients/opencode.md
Qoder	docs/clients/qoder.md
Visual Studio	docs/clients/visual-studio.md
Warp	docs/clients/warp.md
Windsurf	docs/clients/windsurf.md

</details>

Version Compatibility

Blender Version	Status
4.2 LTS	✅ Supported
4.5 LTS	✅ Supported
5.0+	✅ Supported
5.1	✅ Supported (some API limitations, see above)
< 4.2	❌ Not Supported

See docs/versioning/support-matrix.md for details.

---

<a name="中文"></a>

中文

用于 AI 辅助 Blender 自动化的 MCP 服务器集成。

分层工具架构

Blender MCP 采用四层工具架构，29 个专用工具按意图组织：

层级	工具数量	用途
感知层	11 个工具	以可控粒度深度读取 Blender 状态
声明式写入层	4 个工具	节点编辑器（6种上下文）+ 动画 + VSE 序列编辑器 + 网格编辑
命令式写入层	9 个工具	对象/材质/修改器/UV/约束/物理/场景
后备层	5 个工具	execute_operator + execute_script + import_export + render + batch

感知层（11 个工具）：

工具	描述
blender_get_objects	列出/筛选场景对象
blender_get_object_data	单对象深度数据（12 种 include 选项）
blender_get_node_tree	读取任意节点树（6 种上下文）
blender_get_animation_data	关键帧/NLA/驱动器/形态键
blender_get_materials	材质资产列表
blender_get_scene	场景级全局信息
blender_get_collections	集合层级树
blender_get_armature_data	骨架/骨骼层级/约束/姿态
blender_get_images	纹理/图片资产列表
blender_capture_viewport	视口截图
blender_get_selection	当前选择/模式/活动对象

声明式写入层（4 个工具）：

工具	描述
blender_edit_nodes	编辑任意节点树（添加/移除/连接/断开/设置值）⭐ 核心
blender_edit_animation	编辑动画（关键帧/NLA/驱动器/形态键/帧范围）
blender_edit_sequencer	编辑 VSE 视频序列（片段/转场/特效）
blender_edit_mesh	编辑网格数据（顶点/边/面）

命令式写入层（9 个工具）：

工具	描述
blender_create_object	创建场景对象（MESH/LIGHT/CAMERA/CURVE/EMPTY/ARMATURE/TEXT）
blender_modify_object	变换/父子/可见性/重命名/删除
blender_manage_material	材质创建/PBR 编辑/赋予/复制/删除
blender_manage_modifier	修改器添加/配置/应用/删除/排序
blender_manage_collection	集合创建/删除/对象链接/层级/可见性
blender_manage_uv	UV 展开/缝合线/打包/图层管理
blender_manage_constraints	对象/骨骼约束添加/配置/删除
blender_manage_physics	物理模拟添加/配置/烘焙
blender_setup_scene	渲染引擎/世界环境/时间线配置

后备层（5 个工具）：

工具	描述
blender_execute_operator	执行任意 bpy.ops.* 操作符
blender_execute_script	执行任意 Python 代码（⚠️ 谨慎使用）
blender_import_export	导入/导出资产文件（FBX/OBJ/GLTF/USD/Alembic/STL 等）
blender_render_scene	渲染场景到图像/视频
blender_batch_execute	在单次请求中执行多个工具调用（性能优化）

注意: 所有工具使用 blender_ 前缀以避免多服务器环境下的命名冲突。工具名称符合 MCP 规范使用下划线。Payload 包装层已移除 - 所有参数直接暴露为顶层 inputSchema 属性。

工具命名: 所有工具使用 blender_ 前缀以避免多服务器环境下的命名冲突。

特性

• 撤销支持：所有写入操作自动推入 Blender 撤销栈 — Ctrl+Z 正确回退。
• 本地化支持：支持任何语言的 Blender。使用英文显示名如 "Principled BSDF" 会自动解析为本地化名称。
• 错误报告：插件详细错误信息在 MCP 工具响应中可见。
• 进度通知：支持长时间运行操作（渲染、导入导出）的 MCP 进度通知。客户端可在 _meta 字段中包含 progressToken 以接收实时进度更新。

进度通知

Blender MCP 支持长时间运行操作的 MCP 进度通知。接收进度更新：

// 客户端请求携带 progressToken
{
  "method": "tools/call",
  "params": {
    "name": "blender_render_scene",
    "arguments": {"output_path": "/tmp/render.png"},
    "_meta": {"progressToken": "render-123"}
  }
}

// 服务端发送进度通知
{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "render-123",
    "progress": 50,
    "total": 100,
    "message": "正在渲染第 50/100 帧"
  }
}

安全特性：

• 频率限制：通知间隔最小 100ms
• 进度消息截断至 1000 字符
• 最多 100 个并发进度 token
• 线程安全的通知输出

已知限制（Blender 5.1）

限制	原因
VSE 片段创建失败	Blender 5.1 定时器上下文 API 限制
合成器节点编辑失败	Blender 5.1 定时器上下文 API 限制
对象指针属性无法设置	MCP set_property 限制
多材质槽创建	MCP assign 仅替换槽 0

快速开始

初次使用？ 请参阅 5 分钟快速开始指南 获取详细安装步骤。

// 创建一个立方体
{
  "name": "MyCube",
  "object_type": "MESH",
  "primitive": "cube",
  "size": 2.0
}

// 移动它
{
  "name": "MyCube",
  "location": [1, 2, 3]
}

// 添加细分修改器
{
  "action": "add",
  "object_name": "MyCube",
  "modifier_name": "Subdivision",
  "modifier_type": "SUBSURF",
  "settings": {"levels": 2}
}

// 读取对象数据
{
  "name": "MyCube",
  "include": ["summary", "modifiers"]
}

// 捕获视口
{
  "shading": "SOLID",
  "format": "PNG"
}

安装

Blender 插件

1. 将 src/blender_mcp_addon/ 复制或符号链接到 Blender 插件目录：

   • Windows: %APPDATA%\Blender\<版本>\scripts\addons\blender_mcp_addon
   • macOS: ~/Library/Application Support/Blender/<版本>/scripts/addons/blender_mcp_addon
   • Linux: ~/.config/blender/<版本>/scripts/addons/blender_mcp_addon

2. 在 Blender 中：编辑 > 偏好设置 > 插件 > 搜索 "Blender MCP" > 启用

3. 配置后点击 "启动服务器"

MCP 服务器

# 推荐：一行命令安装并运行
uvx ageless-blender-mcp

# 或全局安装
pip install ageless-blender-mcp
blender-mcp

# 或从源码
uv sync
python -m blender_mcp.mcp_protocol

支持的 MCP 客户端

<details> <summary>点击展开客户端列表</summary>

客户端	文档
Amp	docs/clients/amp.md
Antigravity	docs/clients/antigravity.md
Claude Code	docs/clients/claude-code.md
Cline	docs/clients/cline.md
Codex	docs/clients/codex.md
Copilot CLI	docs/clients/copilot-cli.md
Copilot / VS Code	docs/clients/vs-code-copilot.md
Cursor	docs/clients/cursor.md
Factory CLI	docs/clients/factory-cli.md
Gemini CLI	docs/clients/gemini-cli.md
Gemini Code Assist	docs/clients/gemini-code-assist.md
JetBrains AI 助手	docs/clients/jetbrains.md
Kiro	docs/clients/kiro.md
OpenCode	docs/clients/opencode.md
Qoder	docs/clients/qoder.md
Visual Studio	docs/clients/visual-studio.md
Warp	docs/clients/warp.md
Windsurf	docs/clients/windsurf.md

</details>

版本兼容性

Blender 版本	状态
4.2 LTS	✅ 支持
4.5 LTS	✅ 支持
5.0+	✅ 支持
5.1	✅ 支持（部分 API 限制，见上方说明）
< 4.2	❌ 不支持

详见 docs/versioning/support-matrix.md。

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Star History

License

MIT License - see LICENSE for details.