Blender MCP
This server lets an AI client drive Blender end-to-end — creating and managing scenes and objects, inspecting and describing the scene graph, capturing visual feedback, exporting to game-engine formats, and dynamically loading tool groups — over MCP.
Scene management — create (optionally copying an existing scene), list, inspect, switch, delete, and configure scenes (frame range, FPS, unit system/scale).
Object creation — build primitives, curves, text, empties, armatures, lattices, cameras, and lights, with mesh-specific parameters (segments, radii, subdivisions, etc.).
Object editing — delete, duplicate (independent or linked), transform (absolute or delta), select by name/wildcard, rename, parent/unparent, join, set origin (geometry, cursor, bottom, center of mass/volume), and apply transforms.
Scene & object introspection — structured scene summaries, full parent-child hierarchies, deep object inspection (topology, materials, modifiers, constraints, bounds), plus object info and Blender version/connection status.
Arbitrary scripting — run Python code inside Blender with a configurable timeout for anything the built-in tools don't cover.
Visual feedback — capture viewport screenshots and quick low-sample render previews (returning file paths for multimodal review), plus a simpler viewport screenshot tool.
File I/O — save the current Blender file (with optional compression) and open existing files (optionally loading UI).
Export — write FBX (with Unity-oriented presets, axis/scale control, animation and modifier baking), glTF/GLB (with Draco option), and OBJ.
Export QA — re-import an exported FBX and verify engine-readiness (origin at (0,0,0), triangle budget, single-object-per-file, materials/emissive slots).
History control — undo and redo multiple steps.
Dynamic skill loading — list the available skill groups, activate one to register its tools on demand, and deactivate it to free context.
Controls Blender through natural language, providing tools for modeling, materials, animation, rendering, rigging, and more.
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., "@Blender MCP create a red cube"
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.
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
(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.
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 server that lets AI assistants control Blender 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 toolsBlender 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)
BlenderRelated MCP server: Blender MCP
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
skillprofile starts with 38 tools; 12 skill groups activate on demand to keep AI context lean6 profiles — from
minimal(35 tools) tofull(377 tools)Visual feedback —
blender_snapshot_viewportandblender_snapshot_render_previewfor multimodal AI review loopsCheckpoint 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+
An MCP-compatible client
Install & Run
There is no PyPI release yet. Install from source —
pip install blender-mcpwould install an unrelated third-party package (see the notice at the top).
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-aiSet Up Blender
Open Blender →
Edit→Preferences→Add-ons→Install...Select
dist/blender_mcp_addon.zipEnable Blender MCP
Open the MCP panel in the 3D View sidebar
Configure Your IDE
Add to your MCP client config:
{
"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:
uv run python scripts/demo_tour.py --cleanIt 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 |
| Object creation and transforms | Outliner → select |
| Bevel / Subdivision / Boolean modifiers | Properties → wrench tab, toggle each modifier |
| Metal vs plastic, Principled BSDF values | Press Z → Material Preview |
| Three-point lighting and a camera | Press Z → Rendered; select a light to read its power |
| Smart UV project | Open a UV Editor, |
| Keyframed bounce + spin | Timeline → press Space |
| Generated character plus an armature | Hide other layers, then Pose Mode on |
| Cloth and rigid-body simulation | Play the timeline |
Full step-by-step walkthrough: docs/en/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 |
| 35 | Core scene/object/utility/export only |
| 38 | Default — core + on-demand skill loading |
| 124 | Curated workflow set |
| 186 | Broader daily-use coverage |
| 215 | Adds physics & batch operations |
| 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 contextSkills 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 | ||
Guided Tour | ||
Installation | ||
Architecture | ||
API Reference | ||
Skill System | ||
Tutorials | ||
Contributing | ||
Changelog | ||
Roadmap | ||
Security | ||
Code of Conduct |
Community
GitHub Discussions — questions, ideas, long-form discussion
Issues — bug reports and feature requests
Contributing Guide — how to add tools, fix bugs, improve docs
Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Fork the repo & create a feature branch
Install dev dependencies:
uv sync --all-extrasMake changes and add tests
Run checks:
pytest && ruff check src/ && black --check src/Submit a pull request
Security
For security concerns, please see SECURITY.md. Do not open a public issue for security vulnerabilities.
Known Caveats
If
.venvbreaks after copying the repo to another machine, delete.venvand re-runuv sync
License
MIT — Copyright (c) 2026 Harvey Xia
中文
本项目与其他任何同名 Blender MCP 项目均无关联。
这是一套独立、原创的代码库,不是任何项目的 fork,也不共用任何代码。特别地,本项目与
ahujasid/mcp-for-blender(其旧版在 PyPI 上
叫 blender-mcp)毫无关系。PyPI 上的 blender-mcp 属于那个项目,安装它不会安装本软件。
安装本项目请克隆本仓库,见快速开始。
来源说明: 「MCP 服务器 + Blender 插件、走本地 socket」这个整体形态是本类工具的通用做法, 其他 Blender MCP 项目也采用类似结构,因此架构层面看起来会相似。本仓库不是 fork, 实现为独立完成。
概述
Blender MCP AI 是一个开源的 Model Context Protocol 服务器,让 AI 助手可以通过自然语言控制 Blender。支持 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
快速开始
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 中:
编辑→偏好设置→插件→安装...选择
dist/blender_mcp_addon.zip启用 Blender MCP
在 3D 视图侧边栏打开 MCP 面板
IDE 配置:
{
"mcpServers": {
"blender": {
"command": "uv",
"args": ["run", "--directory", "/path/to/blender-mcp-ai", "blender-mcp-ai"]
}
}
}上手试一下(分层演示)
想先看看它到底能做什么?保持 Blender 打开、插件已启用,然后运行:
uv run python scripts/demo_tour.py --clean脚本会通过 MCP socket 执行 46 次调用,并把结果按图层分到各自的集合里,方便你逐层查看:
集合 | 演示内容 | 怎么看 |
| 物体创建与变换 | 大纲视图选中 |
| Bevel / 细分 / 布尔 修改器 | 右侧扳手图标,逐个开关修改器看差异 |
| 金属 vs 塑料、Principled BSDF 参数 | 按 Z → 材质预览 |
| 三点布光 + 相机 | 按 Z → 渲染预览;选中灯光看功率 |
| Smart UV 展开 | 打开 UV 编辑器,按 |
| 关键帧弹跳 + 自转 | 时间轴按 空格 播放 |
| 程序生成角色 + 骨架 | 隐藏其他图层,对 |
| 布料 + 刚体模拟 | 播放时间轴 |
逐层详解请看:docs/zh/TOUR.md(English:docs/en/TOUR.md)
每一层都显示 OK,就说明整套流程跑通了。想连渲染和导出一起验证,选中 L4_Cam 按 F12,
或对任意物体调用 blender_export_fbx。
重复运行时请带上 --clean(如上),否则上一轮的对象会和新的重名冲突。
社区
GitHub Discussions — 提问、讨论、展示作品
Issues — 问题反馈与功能建议
文档
所有文档均提供 English 和 中文 版本,详见上方文档表格。
系统要求
Python 3.10+
Blender 4.0+
任意兼容 MCP 的客户端
许可证
MIT — Copyright (c) 2026 Harvey Xia
Available Tools
38 toolsblender_activate_skillA
Activate a skill to dynamically load its tool group.
This registers new MCP tools that become available for immediate use. Each skill provides a set of related tools and a workflow guide.
Use list_skills first to see available skills.
Args: skill_name: Name of the skill to activate (e.g., 'modeling', 'materials', 'animation')
Inputs: skill_name (required). Returns: result
blender_connection_statusARead-onlyIdempotent
Query the current connection status and statistics with Blender.
Can be used to diagnose connection issues and confirm whether Blender is online.
Returns: Connection status information
Inputs: params (required). Returns: result
blender_deactivate_skillA
Deactivate a skill, removing its tools to free up context.
Use this when you no longer need a skill's tools, especially before activating a different skill group.
Args: skill_name: Name of the skill to deactivate
Inputs: skill_name (required). Returns: result
blender_describe_hierarchyARead-onlyIdempotent
Get the full parent-child object tree of the scene as indented text or JSON.
Example: Show the hierarchy to understand how objects are organized and parented.
Inputs: params (required). Returns: result
blender_describe_objectARead-onlyIdempotent
Deep inspection of a single object: topology stats (verts/edges/faces/ngons), material slots, modifier stack, constraints, parent chain, and bounding box.
Example: Inspect 'Cube' to check its polygon count and applied modifiers.
Inputs: params (required). Returns: result
blender_describe_sceneARead-onlyIdempotent
Get a structured summary of the current scene: object counts by type, materials, lights, camera, render settings, and frame range.
Example: Describe the scene to understand what objects exist before making changes.
Inputs: params (required). Returns: result
blender_execute_pythonADestructive
Execute Python code in Blender.
Note: Use with caution as this may modify the scene or perform dangerous operations.
Args: params: Python code and timeout
Returns: Execution result
Inputs: params (required). Returns: result
blender_export_fbxBIdempotent
Export as FBX format (suitable for Unity, Unreal, etc.).
Args: params: Export settings
Returns: Export result
Inputs: params (required). Returns: result
blender_export_gltfBIdempotent
Export as glTF format (suitable for Web, Three.js, etc.).
Args: params: Export settings
Returns: Export result
Inputs: params (required). Returns: result
blender_export_objCIdempotent
Export as OBJ format.
Args: params: Export settings
Returns: Export result
Inputs: params (required). Returns: result
blender_file_openBDestructive
Open a Blender file.
Note: This will replace the current scene; unsaved changes will be lost.
Args: params: File path
Returns: Open result
Inputs: params (required). Returns: result
blender_file_saveCIdempotent
Save the Blender file.
Args: params: File path and compression options
Returns: Save result
Inputs: params (required). Returns: result
blender_get_infoBRead-onlyIdempotent
Get Blender version and status information.
Returns: Blender info
Inputs: params (required). Returns: result
blender_get_viewport_screenshotCRead-only
Get a screenshot of the current viewport.
Args: params: Output path and dimensions
Returns: Screenshot path
Inputs: params (required). Returns: result
blender_list_skillsA
List all available skills and their activation status.
Skills are groups of tools that can be loaded on demand. Start here to discover what capabilities are available, then use activate_skill to load the tools you need.
Returns a summary of all skills with their descriptions, tool counts, and current activation status.
Inputs: no named parameters. Returns: result
blender_object_apply_transformAIdempotent
Apply object transforms (location, rotation, scale).
Applies transform data to the mesh data and resets object transforms to default values.
Args: params: Object name and transform types to apply
Returns: Apply result
Inputs: params (required). Returns: result
blender_object_createB
Create a new object in Blender.
Supports creating various types of objects including meshes (cube, sphere, etc.), curves, text, etc.
Args: params: Object type, name, location, rotation, scale
Returns: Creation result
Inputs: params (required). Returns: result
blender_object_deleteBDestructive
Delete the specified object.
Args: params: Object name and deletion options
Returns: Deletion result
Inputs: params (required). Returns: result
blender_object_duplicateA
Duplicate an object.
Can create an independent copy or a linked copy (sharing mesh data).
Args: params: Source object name, new name, whether to link, position offset
Returns: Duplication result
Inputs: params (required). Returns: result
blender_object_get_infoBRead-onlyIdempotent
Get detailed information about an object.
Includes transform, mesh statistics, modifiers, materials, and other info.
Args: params: Object name and inclusion options
Returns: Detailed object information
Inputs: params (required). Returns: result
blender_object_joinCDestructive
Join multiple objects into one.
Args: params: List of objects to join and target object
Returns: Join result
Inputs: params (required). Returns: result
blender_object_listBRead-onlyIdempotent
List objects in the scene.
Can filter by type or name pattern.
Args: params: Filter and format options
Returns: Object list
Inputs: params (required). Returns: result
blender_object_parentAIdempotent
Set the parent-child relationship for objects.
Args: params: Child object and parent object names
Returns: Setting result
Inputs: params (required). Returns: result
blender_object_renameCIdempotent
Rename an object.
Args: params: Current name and new name
Returns: Rename result
Inputs: params (required). Returns: result
blender_object_selectBIdempotent
Select objects.
Can select objects by name list or wildcard pattern.
Args: params: Selection parameters
Returns: Selection result
Inputs: params (required). Returns: result
blender_object_set_originAIdempotent
Set the origin point of an object.
Supports multiple origin setting methods including geometry center, 3D cursor, bottom center (suitable for character feet), etc.
Args: params: Object name and origin type
Returns: Setting result
Inputs: params (required). Returns: result
blender_object_transformBIdempotent
Transform an object (location, rotation, scale).
Can set absolute values or delta transforms.
Args: params: Object name and transform parameters
Returns: Transform result
Inputs: params (required). Returns: result
blender_redoC
Redo operations.
Args: params: Number of redo steps
Returns: Redo result
Inputs: params (required). Returns: result
blender_scene_createB
Create a new scene in Blender.
Creates a new scene, optionally copied from an existing scene.
Args: params: Contains scene name and optional copy source
Returns: Creation result as JSON string
Inputs: params (required). Returns: result
blender_scene_deleteADestructive
Delete the specified scene.
Note: Cannot delete the last remaining scene.
Args: params: Name of the scene to delete
Returns: Deletion result
Inputs: params (required). Returns: result
blender_scene_get_infoARead-onlyIdempotent
Get detailed information about a scene.
Returns the scene's frame range, FPS, unit settings, and other detailed info.
Args: params: Scene name (optional)
Returns: Detailed scene information
Inputs: params (required). Returns: result
blender_scene_listARead-onlyIdempotent
List all scenes in Blender.
Returns a list of all scenes including name, object count, and other info.
Args: params: Output format options
Returns: Scene list (Markdown or JSON format)
Inputs: params (required). Returns: result
blender_scene_set_settingsBIdempotent
Set scene settings.
Can set frame range, frame rate, unit system, etc.
Args: params: Scene settings parameters
Returns: Settings result
Inputs: params (required). Returns: result
blender_scene_switchBIdempotent
Switch to the specified scene.
Args: params: Target scene name
Returns: Switch result
Inputs: params (required). Returns: result
blender_snapshot_render_previewARead-onlyIdempotent
Quick render at reduced resolution for preview. Returns the file path.
Example: Render a 512px wide preview with 16 samples to check lighting and materials.
Inputs: params (required). Returns: result
blender_snapshot_viewportARead-onlyIdempotent
Capture the 3D viewport as a PNG image. Returns the file path for multimodal AI analysis.
Example: Capture an 800x600 screenshot of the current viewport to see the scene layout.
Inputs: params (required). Returns: result
blender_undoC
Undo operations.
Args: params: Number of undo steps
Returns: Undo result
Inputs: params (required). Returns: result
blender_verify_fbxARead-onlyIdempotent
Re-import an exported FBX and assert game-engine readiness.
Checks world origin == (0,0,0), triangle budget, one-object-per-file, and reports materials / emissive slots. Use after blender_export_fbx to self-verify each export instead of post-hoc bulk QA.
Returns: PASS/FAIL with the per-object report.
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 38 tools
Most tools are clearly distinct, but blender_get_viewport_screenshot and blender_snapshot_viewport have highly overlapping purposes, potentially confusing an agent.
All tools use a consistent snake_case naming with a clear pattern: resource-specific tools are prefixed with blender_<resource>_ (e.g., blender_object_, blender_scene_) and general actions are blender_<action>_<object>, making the overall pattern predictable.
With 38 tools, the count exceeds the 'too many' threshold of 25+. While Blender is complex and the skills system helps, the base set is still large and may overwhelm context windows.
The base tool set covers core scene and object operations, export, and file I/O, but lacks tools for materials, modifiers, animations, and other essential Blender workflows. The skills system can fill gaps, but as presented, notable operations are missing.
Maintenance
Related MCP Connectors
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
Blender and GLB/FBX/USD/STL rendered on cloud GPUs for AI agents: product shots, turntables, MP4
Generate 3D models, worlds, PBR materials, and coordinated asset packs from AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered 3D content creation in Blender through natural language, including text-to-3D, image-to-3D, animation, rigging, rendering, and export.3MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to create, inspect, and animate 3D scenes in Blender through natural language and structured tool calls.6MIT
- FlicenseNot gradedqualityDmaintenanceConnects AI assistants to Blender 3D for natural language 3D modeling, scene inspection, material creation, and rendering.-
- AlicenseCqualityBmaintenanceEnables AI agents to control Blender through 150+ tools across 24 modules, including modeling, materials, lighting, animation, rendering, mesh quality analysis, and visual feedback, plus expert prompts and goal-first workflow management.2092MIT