ageless-blender-mcp

Blender MCP

English | 中文

---

English

MCP server integration for AI-assisted Blender automation.

Layered Tool Architecture

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

Perception Layer (11 tools):

Declarative Write Layer (3 tools):

Imperative Write Layer (9 tools):

Fallback Layer (3 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.

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

Click to expand client list

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

Version Compatibility

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

---

中文

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

分层工具架构

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

感知层（11 个工具）：

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

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

后备层（3 个工具）：

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

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

快速开始

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

点击展开客户端列表

客户端	文档
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

版本兼容性

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

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Star History

License

MIT License - see LICENSE for details.