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:

Perception Layer (11 tools):

Declarative Write Layer (4 tools):

Imperative Write Layer (9 tools):

Fallback Layer (5 tools):

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)

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

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

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

</details>

Version Compatibility

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

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

中文

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

分层工具架构

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

感知层（11 个工具）：

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

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

后备层（5 个工具）：

注意: 所有工具使用 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）

快速开始

初次使用？ 请参阅 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

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

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

#### MCP 服务器

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

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

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

支持的 MCP 客户端

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

</details>

版本兼容性

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

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Star History

License

MIT License - see LICENSE for details.