Control Blender with AI through the Model Context Protocol
Quick Start • Architecture • API Reference • Contributing • Discussions • 中文
--- > [!IMPORTANT] > **This project is not affiliated with any other Blender MCP project.** > It is an independent, original codebase — not a fork of, and sharing no code > with, anything else. In particular it is unrelated to > [`ahujasid/mcp-for-blender`](https://github.com/ahujasid/mcp-for-blender) > (formerly published on PyPI as `blender-mcp`). The `blender-mcp` package on > PyPI belongs to *that* project: installing it does **not** install this > software. Install this project by cloning this repository — see > [Quick Start](#quick-start). > **Provenance:** The overall shape — an MCP server talking to a Blender addon > over a local socket — is the standard approach for this category of tool and > is shared by other Blender MCP projects, so the architectures look similar. > This repository is **not a fork**, and the implementation here is independent. ## Overview **Blender MCP AI** is an open-source [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI assistants control [Blender](https://www.blender.org/) through natural language. It works with any MCP-compatible client — **Cursor**, **Windsurf**, **Claude Desktop**, and more. The project consists of two components: - **MCP Server** (`src/blender_mcp/`) — a FastMCP server exposing Blender operations as MCP tools - **Blender Addon** (`addon/blender_mcp_addon/`) — a Blender plugin that receives commands over TCP and executes them via Blender's Python API ``` AI Client (Cursor / Windsurf / Claude Desktop) ↓ MCP protocol (stdio or HTTP) Blender MCP Server (Python, FastMCP) ↓ TCP JSON messages (localhost:9876) Blender Addon (runs inside Blender) ↓ Blender Python API (bpy) Blender ``` ## Gallery > Generated entirely through natural-language AI commands via Blender MCP AI — no manual Blender interaction.  *A character built end-to-end by the agent — body template, hair, clothing and accessory — then lit and rendered at 1920×1080 through the MCP tools. It is a deliberately simple primitive-based blockout: the point is the round trip, not the polish.* The point of this project isn't the polish of any single render — it's the **agent ↔ Blender pipeline**: 380 tools, dynamic skill loading to keep the model's context lean, and viewport/render snapshots that let the model review its own work and iterate. ## Key Features - **380 MCP tools** across 56 modules — modeling, materials, animation, rendering, rigging, and more - **Smart skill loading** — default `skill` profile starts with 38 tools; 12 skill groups activate on demand to keep AI context lean - **6 profiles** — from `minimal` (35 tools) to `full` (377 tools) - **Visual feedback** — `blender_snapshot_viewport` and `blender_snapshot_render_preview` for multimodal AI review loops - **Checkpoint system** — named save/restore points before risky operations - **Style system** — 8 rendering style presets from Pixel Art to AAA - **67 procedural materials** — metals, woods, stones, fabrics, nature, skin, effects, toon - **Quality audit** — topology, UV, and performance validation - **Blender 4.x / 5.x** compatible - **Multi-IDE support** — Cursor, Windsurf, Claude Desktop, and any MCP client ## Quick Start ### Prerequisites - **Python 3.10+** - **Blender 4.0+** - **[uv](https://docs.astral.sh/uv/)** - An MCP-compatible client ### Install & Run > There is no PyPI release yet. Install from source — `pip install blender-mcp` > would install an unrelated third-party package (see the notice at the top). ```bash git clone https://github.com/harveyxiacn/blender-mcp-ai.git cd blender-mcp-ai uv sync # Build the Blender addon python build_addon.py # Start the MCP server uv run blender-mcp-ai ``` ### Set Up Blender 1. Open Blender → `Edit` → `Preferences` → `Add-ons` → `Install...` 2. Select `dist/blender_mcp_addon.zip` 3. Enable **Blender MCP** 4. Open the **MCP** panel in the 3D View sidebar ### Configure Your IDE Add to your MCP client config: ```json { "mcpServers": { "blender": { "command": "uv", "args": ["run", "--directory", "/path/to/blender-mcp-ai", "blender-mcp-ai"] } } } ``` ## Try It — a guided tour Want to see what this does before reading anything else? With Blender open and the addon enabled, build a demo scene and inspect it layer by layer: ```bash uv run python scripts/demo_tour.py --clean ``` It drives the MCP socket 46 times and groups the result into one collection per layer, so you can hide everything except the thing you want to look at: | Collection | What it demonstrates | How to look at it | |---|---|---| | `L1_场景基础` | Object creation and transforms | Outliner → select `L1_Cube` → press **N** | | `L2_建模` | Bevel / Subdivision / Boolean modifiers | Properties → **wrench** tab, toggle each modifier | | `L3_材质` | Metal vs plastic, Principled BSDF values | Press **Z** → *Material Preview* | | `L4_灯光相机` | Three-point lighting and a camera | Press **Z** → *Rendered*; select a light to read its power | | `L5_UV` | Smart UV project | Open a **UV Editor**, `Tab` into edit mode, press `A` | | `L6_动画` | Keyframed bounce + spin | Timeline → press **Space** | | `L7_角色骨骼` | Generated character plus an armature | Hide other layers, then *Pose Mode* on `L7_Rig` | | `L8_物理` | Cloth and rigid-body simulation | Play the timeline | **Full step-by-step walkthrough: [docs/en/TOUR.md](docs/en/TOUR.md)** (中文：[docs/zh/TOUR.md](docs/zh/TOUR.md)) If every layer reports `OK`, your install works end to end. To check the renderer and exporters too, select `L4_Cam` and press **F12**, or run `blender_export_fbx` on any object. Running it twice? Pass `--clean` (as above) so the previous run's objects do not collide with the new names. ## Tool Profiles | Profile | Tools | Use Case | |---------|-------|----------| | `minimal` | 35 | Core scene/object/utility/export only | | `skill` | 38 | **Default** — core + on-demand skill loading | | `focused` | 124 | Curated workflow set | | `standard` | 186 | Broader daily-use coverage | | `extended` | 215 | Adds physics & batch operations | | `full` | 377 | Everything | ## Skill System With the default `skill` profile, only core tools load at startup. AI activates additional groups on demand: ``` blender_list_skills → see all 12 available skill groups blender_activate_skill → load a group's tools dynamically blender_deactivate_skill → unload to free AI context ``` Skills include: `modeling`, `materials`, `style`, `character`, `animation`, `scene_setup`, `automation`, `physics`, `batch_assets`, `advanced_3d`, `sport_character`, `training`. ## Documentation All documentation is available in **English** and **中文 (Chinese)**. | Document | English | 中文 | |----------|---------|------| | Quick Start | [QUICKSTART](docs/en/QUICKSTART.md) | [快速开始](docs/zh/QUICKSTART.md) | | Guided Tour | [TOUR](docs/en/TOUR.md) | [分层演示教程](docs/zh/TOUR.md) | | Installation | [INSTALLATION](docs/en/INSTALLATION.md) | [安装指南](docs/zh/INSTALLATION.md) | | Architecture | [ARCHITECTURE](docs/en/ARCHITECTURE.md) | [架构设计](docs/zh/ARCHITECTURE.md) | | API Reference | [API_REFERENCE](docs/en/API_REFERENCE.md) | [API 参考](docs/zh/API_REFERENCE.md) | | Skill System | [MCP_SKILL_SYSTEM_GUIDE](docs/en/MCP_SKILL_SYSTEM_GUIDE.md) | [Skill 系统指南](docs/zh/MCP_SKILL_SYSTEM_GUIDE.md) | | Tutorials | [TUTORIALS](docs/en/TUTORIALS.md) | [教程](docs/zh/TUTORIALS.md) | | Contributing | [CONTRIBUTING](docs/en/CONTRIBUTING.md) | [贡献指南](docs/zh/CONTRIBUTING.md) | | Changelog | [CHANGELOG](docs/en/CHANGELOG.md) | [更新日志](docs/zh/CHANGELOG.md) | | Roadmap | [ROADMAP](docs/en/ROADMAP.md) | [路线图](docs/zh/ROADMAP.md) | | Security | [SECURITY](SECURITY.md) | [安全策略](docs/zh/SECURITY.md) | | Code of Conduct | [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) | [行为准则](docs/zh/CODE_OF_CONDUCT.md) | ## Community - **[GitHub Discussions](https://github.com/harveyxiacn/blender-mcp-ai/discussions)** — questions, ideas, long-form discussion - **[Issues](https://github.com/harveyxiacn/blender-mcp-ai/issues)** — bug reports and feature requests - **[Contributing Guide](docs/en/CONTRIBUTING.md)** — how to add tools, fix bugs, improve docs ## Contributing We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for guidelines. 1. Fork the repo & create a feature branch 2. Install dev dependencies: `uv sync --all-extras` 3. Make changes and add tests 4. Run checks: `pytest && ruff check src/ && black --check src/` 5. Submit a pull request ## Security For security concerns, please see [SECURITY.md](SECURITY.md). Do **not** open a public issue for security vulnerabilities. ## Known Caveats - If `.venv` breaks after copying the repo to another machine, delete `.venv` and re-run `uv sync` ## License [MIT](LICENSE) — Copyright (c) 2026 Harvey Xia --- ## 中文 > [!IMPORTANT] > **本项目与其他任何同名 Blender MCP 项目均无关联。** > 这是一套独立、原创的代码库，不是任何项目的 fork，也不共用任何代码。特别地，本项目与 > [`ahujasid/mcp-for-blender`](https://github.com/ahujasid/mcp-for-blender)（其旧版在 PyPI 上 > 叫 `blender-mcp`）毫无关系。PyPI 上的 `blender-mcp` 属于**那个**项目，安装它**不会**安装本软件。 > 安装本项目请克隆本仓库，见[快速开始](#快速开始)。 > **来源说明：** 「MCP 服务器 + Blender 插件、走本地 socket」这个整体形态是本类工具的通用做法， > 其他 Blender MCP 项目也采用类似结构，因此架构层面看起来会相似。本仓库**不是 fork**， > 实现为独立完成。 ### 概述 **Blender MCP AI** 是一个开源的 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，让 AI 助手可以通过自然语言控制 [Blender](https://www.blender.org/)。支持 **Cursor**、**Windsurf**、**Claude Desktop** 等任意 MCP 兼容客户端。 ### 展示 > 以下渲染完全通过自然语言 AI 命令生成，无需手动操作 Blender。  *一个由智能体端到端生成的角色 —— 体型模板、头发、服装、配饰全部由 MCP 工具创建，再经打光与 1920×1080 渲染。它是刻意简化的图元搭建，重点在完整回路，而非精细度。* 本项目的价值不在单张渲染的精细度，而在 **agent ↔ Blender 管线**：380 个工具、动态技能加载以精简上下文、以及让模型自审自迭代的视口/渲染截图。 ### 核心特性 - **380 个 MCP 工具**，覆盖建模、材质、动画、渲染等全流程 - **智能工具加载** — 默认 `skill` 配置仅加载 38 个工具，12 个技能组按需激活 - **6 种配置方案** — 从 `minimal`（35 个工具）到 `full`（377 个工具） - **视觉反馈** — 视口截图 + 渲染预览，支持多模态 AI 审查循环 - **检查点系统** — 高风险操作前的命名存档/还原点 - **风格系统** — 8 种渲染风格预设（像素风到 3A 级） - **67 种程序化材质** — 金属、木材、石材、布料、自然、皮肤、特效、卡通 - **质量审计** — 拓扑、UV、性能验证 - **兼容 Blender 4.x / 5.x** ### 快速开始 ```bash git clone https://github.com/harveyxiacn/blender-mcp-ai.git cd blender-mcp-ai uv sync # 打包 Blender 插件 python build_addon.py # 启动 MCP 服务器 uv run blender-mcp-ai ``` > 目前尚未发布到 PyPI。请从源码安装 —— `pip install blender-mcp` > 装到的是**另一个**无关的第三方包（见顶部说明）。 然后在 Blender 中： 1. `编辑` → `偏好设置` → `插件` → `安装...` 2. 选择 `dist/blender_mcp_addon.zip` 3. 启用 **Blender MCP** 4. 在 3D 视图侧边栏打开 **MCP** 面板 IDE 配置： ```json { "mcpServers": { "blender": { "command": "uv", "args": ["run", "--directory", "/path/to/blender-mcp-ai", "blender-mcp-ai"] } } } ``` ### 上手试一下（分层演示） 想先看看它到底能做什么？保持 Blender 打开、插件已启用，然后运行： ```bash uv run python scripts/demo_tour.py --clean ``` 脚本会通过 MCP socket 执行 46 次调用，并把结果按图层分到各自的集合里，方便你逐层查看： | 集合 | 演示内容 | 怎么看 | |---|---|---| | `L1_场景基础` | 物体创建与变换 | 大纲视图选中 `L1_Cube`，按 **N** 看变换数值 | | `L2_建模` | Bevel / 细分 / 布尔 修改器 | 右侧**扳手图标**，逐个开关修改器看差异 | | `L3_材质` | 金属 vs 塑料、Principled BSDF 参数 | 按 **Z** → 材质预览 | | `L4_灯光相机` | 三点布光 + 相机 | 按 **Z** → 渲染预览；选中灯光看功率 | | `L5_UV` | Smart UV 展开 | 打开 **UV 编辑器**，按 `Tab` 进编辑模式再按 `A` | | `L6_动画` | 关键帧弹跳 + 自转 | 时间轴按 **空格** 播放 | | `L7_角色骨骼` | 程序生成角色 + 骨架 | 隐藏其他图层，对 `L7_Rig` 进**姿势模式** | | `L8_物理` | 布料 + 刚体模拟 | 播放时间轴 | **逐层详解请看：[docs/zh/TOUR.md](docs/zh/TOUR.md)**（English：[docs/en/TOUR.md](docs/en/TOUR.md)） 每一层都显示 `OK`，就说明整套流程跑通了。想连渲染和导出一起验证，选中 `L4_Cam` 按 **F12**， 或对任意物体调用 `blender_export_fbx`。 重复运行时请带上 `--clean`（如上），否则上一轮的对象会和新的重名冲突。 ### 社区 - **[GitHub Discussions](https://github.com/harveyxiacn/blender-mcp-ai/discussions)** — 提问、讨论、展示作品 - **[Issues](https://github.com/harveyxiacn/blender-mcp-ai/issues)** — 问题反馈与功能建议 ### 文档 所有文档均提供 **English** 和 **中文** 版本，详见上方[文档表格](#documentation)。 ### 系统要求 - Python 3.10+ - Blender 4.0+ - 任意兼容 MCP 的客户端 ### 许可证 [MIT](LICENSE) — Copyright (c) 2026 Harvey Xia