Blender MCP Plus
Provides tools for controlling Blender through its official MCP add-on, including executing bpy code, running background Blender jobs, inspecting scenes and blend files, searching Blender Python API and manual documentation, capturing screenshots/rendering views, and navigating viewport objects and tabs.
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 Plus Search Poly Haven for a chair, import it at 1.2 m, and render a preview."
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.
Blender MCP Plus
一个 MCP 服务器,同时拥有官方 Blender Lab 的工具集和 Poly Haven 资产库。
无需在多个 MCP 之间来回切换,也不会出现两个服务抢 localhost:9876 端口的问题。
基于官方 blender_mcp(GPL-3.0-or-later)扩展,
Blender 侧使用官方插件,本仓库只增强 MCP 服务器。
One MCP server for Blender: the official Blender Lab tool set plus a Poly Haven asset library. It talks to Blender's official
MCPadd-on, so you only need one add-on and one MCP client entry. Tested with Blender 5.2.2 LTS.
特性
28 个工具:任意
bpy代码执行、后台 Blender 执行、场景/工程体检、Blender Python API 与用户手册全文检索、截图/渲染、视口跳转。Poly Haven 资产库(新增,免费 CC0,无需 API key):
search_assets:搜索 500+ 模型、HDRI、贴图import_asset:模型按真实尺寸缩放导入;HDRI 设为世界环境光;贴图建材质赋给对象
一个插件、一个 MCP:Blender 里只需启用官方
MCP插件,客户端只配一条服务器。可选的
.mcpb一键安装包:支持 MCP Bundle 的客户端可直接导入。可发布:自带 PyPI / GitHub Release 一键发布脚本和 GitHub Actions 工作流。
Related MCP server: Blender Open MCP
架构
MCP 客户端 (Claude Desktop / Cursor / DSH / ...)
│ stdio
▼
blender-mcp-plus (本仓库,Python MCP 服务器)
│ TCP localhost:9876
▼
官方 Blender 插件 "MCP"(Blender 5.1+)
│
▼
Blender 5.x / bpy前置条件
依赖 | 要求 |
Blender | 5.1 或更新(官方插件要求;已在 5.2.2 LTS 实测) |
官方 MCP 插件 |
|
Python | 3.10+(用 |
Windows: | |
MCP 客户端 | Claude Desktop / Cursor / DSH / 任意支持 stdio MCP 的客户端 |
安装
1. 安装 Blender 官方插件
方式 A:脚本一键安装(推荐)
# 自动查找 Blender;也可以显式指定路径
powershell -ExecutionPolicy Bypass -File scripts\install_blender_addon.ps1 `
-BlenderExe "E:\Blender 5.2\blender.exe"脚本会从 Blender Lab 官方 release 下载 mcp-1.0.3.zip 并用 Blender CLI 安装、启用。
方式 B:手动安装
下载 https://projects.blender.org/lab/blender_mcp/releases/download/v1.0.3/mcp-1.0.3.zip
打开 Blender → 编辑 → 偏好设置 → 插件 → 右上角下拉 → 从磁盘安装
搜索
MCP,勾选启用确认偏好设置 → 系统 → 允许在线访问(插件需要)
3D 视图按
N可看到MCP面板;插件默认在 Blender 启动后自动监听localhost:9876
2. 安装并运行 MCP 服务器
发布到 PyPI 后(最简单):
uvx blender-mcp-plus从 GitHub 直接运行(无需发布):
uvx --from git+https://github.com/lusilong/blender-mcp-plus blender-mcp-plus本地 wheel:
uv pip install dist\blender_mcp_plus-1.0.3-py3-none-any.whlMCP Bundle(.mcpb): 在 dist\ 里找到 blender-mcp-plus-1.0.3.mcpb,
在支持 MCP Bundle 的客户端里双击/导入即可。
3. 配置 MCP 客户端
Claude Desktop(claude_desktop_config.json)或 Cursor:
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": ["blender-mcp-plus"]
}
}
}Windows 上若客户端找不到 uvx(GUI 启动不继承 PATH),使用:
{
"mcpServers": {
"blender": {
"command": "cmd",
"args": ["/c", "uvx", "blender-mcp-plus"]
}
}
}DeepSeek Harness(~/.dsh/profiles/desktop/cordis.patch.yml)追加:
- id: mcp-blender
name: "@deepseek-ai/dsh-mcp-client"
config:
serverName: blender
transport: stdio
command: "uvx"
args: ["blender-mcp-plus"]
env:
BLENDER_PATH: "E:\\Blender 5.2\\blender.exe"
BLENDER_PATH只用于*_for_cli系列(后台 Blender)。不配置也能用其余工具。
4. 开始使用
保持 Blender 打开,对 AI 说:
「在 Blender 里建一个低多边形咖啡杯加托盘,青绿陶瓷材质,三点布光,渲染预览。」
「搜索 Poly Haven 的椅子,把 ArmChair_01 导入并缩放到 1.2 米。」
「用 HDRI studio_small_03 做环境光,强度 1.2。」
「给选中的椅子贴上 Poly Haven 的木纹贴图,渲染 1200x900 的 EEVEE 预览。」
「把刚才的杯子改成磨砂金属赤陶色,杯身拉高 18%,再渲染对比。」
工具清单(28)
官方 Blender Lab 工具(26)
类别 | 工具 |
代码执行 |
|
工程体检 |
|
场景读取 |
|
文档检索 |
|
观察 |
|
视图 |
|
本仓库新增(2)
工具 | 参数 | 说明 |
|
| 搜索 Poly Haven 资产,按下载量排序 |
|
| 下载并导入模型 / HDRI / 贴图 |
与官方版的关系
本仓库是官方 blender_mcp 的衍生版本,
保留其全部工具,新增 Poly Haven 资产工具,并修复了官方 *_for_cli 工具在
“MCP 服务器本身使用管道 stdio”时可能卡满 120 秒超时的问题(改为临时文件承接子进程输出)。
Blender 插件没有修改,仍是官方版本。
安全
execute_blender_code及其 CLI 版本会以你的用户权限执行任意 Python。执行前保存工程; 不要对不可信的.blend运行。官方插件 socket 只监听 localhost,无鉴权、无加密,禁止端口转发。
第三方资产/场景的元数据可能包含提示注入内容,处理不可信文件时使用副本。
官方文档也明确建议在虚拟机或无敏感数据的机器上使用此类 MCP。
开发与发布
# 安装开发依赖
uv sync --extra dev
# 构建 wheel / sdist
uv build
# 构建 .mcpb
python scripts/build_mcpb.py
# 一键发布(创建 GitHub 仓库 + push + tag + Release + 可选 PyPI)
$env:UV_PUBLISH_TOKEN = "pypi-..." # 需要发布 PyPI 时
powershell -ExecutionPolicy Bypass -File scripts\publish.ps1 -CreateRepo -PyPIscripts\publish.ps1 会:
从
pyproject.toml读取版本号,清理并重新构建dist/构建
.mcpbgit init(如需要)、提交、打 tagv<version>用
gh创建/推送仓库(-CreateRepo)并创建 GitHub Release,上传 wheel/sdist/.mcpb若设置了
UV_PUBLISH_TOKEN且带-PyPI,执行uv publish
GitHub Actions 也提供了 ci.yml 和 publish.yml(打 tag 自动发布,支持 PyPI Trusted Publishing)。
目录结构
blender-mcp-plus/
├── blender_mcp_plus/ # Python 包(MCP 服务器)
│ ├── tools/ # 自动发现的工具模块
│ ├── tools_helpers/ # socket 桥、CLI、文档检索
│ └── data/ # 内置 API 参考 + 用户手册(RST)
├── scripts/
│ ├── install_blender_addon.ps1
│ ├── build_mcpb.py
│ └── publish.ps1
├── tests/
├── manifest.json # MCPB manifest
├── pyproject.toml
├── LICENSE # GPL-3.0
└── NOTICE致谢与许可
上游:Blender Lab / blender_mcp,GPL-3.0-or-later
资产:Poly Haven,CC0
本仓库的修改同样以 GPL-3.0-or-later 发布,详见
LICENSE与NOTICE。
Available Tools
28 toolsexecute_blender_codeADestructive
Execute Python code in the connected Blender instance.
The code runs in Blender's Python environment with full access to bpy.
To return data, assign a JSON-serialisable dict to a variable named result.
Deferred completion via check_is_finished is only supported by the
interactive addon server, and is rejected in background mode.
Inputs: code (required). Returns: object
execute_blender_code_for_cliADestructive
Execute Python code in a background Blender process.
Opens blend_file with blender --background and runs code.
Assign a dict to result to return data.
Inputs: code (required), blend_file (required). Returns: object
get_blendfile_summary_datablocksARead-only
Return a summary of the blend file: data-block counts, active workspace, and render engine.
Inputs: no named parameters. Returns: object
get_blendfile_summary_datablocks_for_cliBRead-only
Return a data-block summary by opening blend_file in background Blender.
Inputs: blend_file (required). Returns: object
get_blendfile_summary_missing_filesARead-only
Report external file references that are missing from disk (images, libraries, fonts, sounds, movie clips, caches, sequences).
Inputs: no named parameters. Returns: object
get_blendfile_summary_missing_files_for_cliBRead-only
Report missing file references by opening blend_file in background Blender.
Inputs: blend_file (required). Returns: object
get_blendfile_summary_of_linked_librariesARead-only
Return a tree of directly and indirectly linked library files.
Inputs: no named parameters. Returns: object
get_blendfile_summary_of_linked_libraries_for_cliBRead-only
Return linked-library info by opening blend_file in background Blender.
Inputs: blend_file (required). Returns: object
get_blendfile_summary_path_infoARead-only
Simple/fast access to the blend file's path, save status, age, and backups.
Inputs: no named parameters. Returns: object
get_blendfile_summary_path_info_for_cliBRead-only
Return path info by opening blend_file in background Blender.
Inputs: blend_file (required). Returns: object
get_blendfile_summary_usage_guessARead-only
Guess the primary use-cases of the current blend file (scored 0-100 with certainty).
Inputs: no named parameters. Returns: object
get_blendfile_summary_usage_guess_for_cliARead-only
Guess use-cases by opening blend_file in background Blender.
Inputs: blend_file (required). Returns: object
get_object_detail_summaryARead-only
Return a structured summary of the object identified by name.
Includes type, transforms, parent, children, modifiers, constraints, materials, visibility, data-block name, and collections.
Inputs: name (required). Returns: object
get_objects_summaryARead-only
Return the scene's collection hierarchy and their objects.
Each collection lists its objects (name, type, parent, data name, selection, visibility) and nested child collections.
Inputs: no named parameters. Returns: object
get_python_api_docsARead-only
Return the Blender Python API docs for identifier, or list
modules matching a trailing-* discovery pattern.
identifier should be a fully-qualified Python name (e.g.
bpy.app or bpy.types.Scene.frame_current).
The trailing-* forms are supported as discovery entry-points:
*enumerates the top-level modules (bpy,bmesh,mathutils,gpu, ...).X.*enumerates the direct-child identifiers under the X namespace (bpy.*->bpy.app,bpy.context, ...).
Both return a namespace response even when X.rst would
otherwise resolve to exact; the .* form lets an agent
force the child listing.
The response always carries kind, found, and identifier.
The remaining keys depend on kind:
"exact"(found=True):<identifier>.rstwas read. Extra keys:content(RST text),examples. When the file exceeds 32 KB,contentis replaced with a dot-point summary of the file's top-level definitions (prefixed by a header noting the truncation) andexamplesis empty - re-query individual members for their rendered blocks."namespace"(found=True): no<identifier>.rstbut<identifier>.<child>.rstsiblings exist. Extra key:submodules(list of child identifiers)."definition"(found=True): identifier is defined inside a parent RST (e.g.bpy.props.IntPropertylives inbpy.props.rst). Extra keys:content(rendered block),examples."partial"(found=False): the parent RST was located but the trailing component isn't defined in it. Extra keys:parentthe identifier whose RST was loaded.availabletop-level definitions in that RST.submodulessibling identifiers<parent>.<child>with their own RSTs, filtered to those whose last component contains every character of the missing tail.
For a toctree landing page like
bpy.typesavailableis empty andsubmodulesis the near-miss list; for a self-contained module likebpy.propsit's the reverse."suggestions"(found=False): no direct match, but identifier appears as a component of other files. Extra key:suggestions(list of full identifiers)."missing"(found=False): nothing matched.
examples (present on the exact and definition kinds)
is a list of {path, content} entries referenced from this documentation.
Inputs: identifier (required). Returns: object
get_screenshot_of_area_as_imageARead-only
Take a screenshot of a single Blender area and return it as a PNG image.
area_ui_type matches the area's ui_type.
size_limit_in_bytes caps the image size in bytes. Zero (the default) uses the MCP message size limit.
Inputs: area_ui_type (required), size_limit_in_bytes.
get_screenshot_of_window_as_imageARead-only
Take a screenshot of the entire Blender window and return it as a PNG image.
size_limit_in_bytes caps the image size in bytes. Zero (the default) uses the MCP message size limit.
Inputs: size_limit_in_bytes.
get_screenshot_of_window_as_jsonARead-only
Return a JSON description of the Blender window layout, areas, active object, and selection.
Inputs: no named parameters. Returns: object
import_assetADestructive
Download a Poly Haven asset and import it into the connected Blender scene.
id is the asset id returned by search_assets (for example
ArmChair_01). For models the glTF version is imported; for
hdris the HDRI becomes the world environment at strength; for
textures the diffuse map is put on a new material applied to
apply_to (or the active mesh object). target_size > 0 scales the
imported model so its largest dimension is that many meters.
Inputs: id (required), source, apply_to, strength, +3 more. Returns: object
jump_to_tab_by_nameBDestructive
Switch the active workspace tab to name.
Inputs: name (required). Returns: object
jump_to_tab_by_space_typeADestructive
Switch to a workspace whose main area matches space_type.
If allow_edits is True and no matching workspace exists, a new one is created by duplicating the current workspace.
Inputs: space_type (required), allow_edits. Returns: object
jump_to_view3d_object_by_nameADestructive
Move the 3D viewport to focus on an object by name.
If allow_edits is True the object may be un-hidden and its collections enabled to make it visible.
Inputs: name (required), allow_edits. Returns: object
jump_to_view3d_object_data_by_nameADestructive
Move the 3D viewport to the object whose data block matches name.
If allow_edits is True the object may be un-hidden and its collections enabled to make it visible.
Inputs: name (required), allow_edits. Returns: object
render_thumbnail_to_pathBDestructive
Render a small, low-quality thumbnail to output_path (temporarily overrides settings).
Inputs: output_path (required). Returns: object
render_viewport_to_pathARead-only
Render the current scene to output_path using current render settings.
Inputs: output_path (required). Returns: object
search_api_docsARead-only
Full-text search over the bundled Blender Python API reference.
Returns a ranked list of hits. Each hit has:
path: file path relative to the bundled docs.text: the matching paragraph pluscontextparagraphs on either side.breadcrumb: the section path containing the hit (Section > Sub-section > ...).index: the hit's position in the result list.score: a relevance score; higher is better.
The query is tokenised on whitespace and matched
case-insensitively. Every token must appear somewhere in
the paragraph body, the file path, or an enclosing section
title - in any order. Common English stop-words (the,
a, how, to, ...) are dropped, so natural
phrasings like "how to bake" work as expected. Regular
expressions are not supported.
Use context to pull more surrounding paragraphs into
each hit (symmetric, default 0). Use index with the
position of a previous hit (same query) to get that hit
alone with its text widened to its enclosing section.
Read-only; consults bundled RST files only.
Inputs: query (required), index, context, max_results. Returns: object
search_assetsARead-only
Search the Poly Haven library for free CC0 models, HDRIs and textures.
asset_type is one of models, hdris, textures or all.
query matches words in the asset id, name, tags and category
(all words must match). category filters on Poly Haven's taxonomy
path (for example Furniture or Metal/Sheet & Corrugated).
min_size_m drops assets whose largest real-world dimension is smaller
than this value in meters (models and textures only).
Inputs: limit, query, source, category, +2 more. Returns: object
search_manual_docsARead-only
Full-text search over the bundled Blender user manual.
Returns a ranked list of hits. Each hit has:
path: file path relative to the bundled docs.text: the matching paragraph pluscontextparagraphs on either side.breadcrumb: the section path containing the hit (Section > Sub-section > ...).index: the hit's position in the result list.score: a relevance score; higher is better.
The query is tokenised on whitespace and matched
case-insensitively. Every token must appear somewhere in
the paragraph body, the file path, or an enclosing section
title - in any order. Common English stop-words (the,
a, how, to, ...) are dropped, so natural
phrasings like "how to bake" work as expected. Regular
expressions are not supported.
Use context to pull more surrounding paragraphs into
each hit (symmetric, default 0). Use index with the
position of a previous hit (same query) to get that hit
alone with its text widened to its enclosing section.
Read-only; consults bundled RST files only.
Inputs: query (required), index, context, max_results. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tool families are clearly separated (objects, screenshots, jumps, assets, renders, docs), but ten blend-file summary tools form five near-identical pairs distinguished only by a '_for_cli' suffix that encodes execution mode rather than a different task. An agent must know whether it is talking to an interactive addon or a background process to pick correctly, which is a real misselection risk even though the descriptions explain the difference.
Names consistently use snake_case verb_noun phrasing (get_*, search_*, jump_to_*, execute_*, import_*, render_*) and the '_for_cli' suffix is applied uniformly across the five summary pairs. Minor deviations exist, such as 'get_blendfile_summary_missing_files' vs 'get_blendfile_summary_of_linked_libraries' and 'get_screenshot_of_area_as_image' vs 'get_screenshot_of_window_as_json', where the trailing noun does not follow a clean pattern.
28 tools is well above the comfortable 3-15 range, and a large share of the surface is duplication: five summary types each require a paired '_for_cli' variant instead of a single parameterised tool. The core distinct capabilities (inspect, navigate, screenshot, execute, assets, render, docs) could be expressed in far fewer tools.
The surface covers inspection, navigation, screenshots, doc search, asset import, and rendering, with execute_blender_code acting as a general escape hatch for anything not modelled directly. Minor gaps remain (no explicit save/export, no animation render, no scene-open tool independent of the blend_file parameter), but agents can work around them via code execution.
Maintenance
Related MCP Connectors
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
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.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Cloud Blender for AI agents: build, inspect, render and animate 3D scenes over remote MCP. Keep editable .blend projects and export GLB or STL. Make your first 3D asset free—30 compute minutes per UTC month, no credit card. First 100 eligible Free account owners to use all 30 minutes in one UTC month by December 31, 2026 UTC receive one calendar month of beta free: 4 compute hours per UTC month, 2 concurrent workers per deployment, 2 deployments, 2048×2048 renders at up to 256 samples, and 10 GiB storage. Existing usage counts toward the 4-hour allowance. Limited to 100 rewards; expires January 1, 2027 00:00 UTC. Free resumes afterward without an automatic charge. Examples, eligibility and terms: https://sceneplane.online/launch?utm_source=glama&utm_medium=directory&utm_campaign=first100
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to control a live Blender session through MCP tools for scene and object manipulation, rendering, PolyHaven asset search/download/texturing, and guided scene workflows, while allowing runtime switching between local or OpenAI-compatible LLM providers.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to control a live Blender session, including scene and object operations, rendering, and PolyHaven asset workflows. Supports provider-agnostic LLM backends that can be switched at runtime through MCP tools.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to drive a live Blender session over MCP — inspecting and creating scene objects, applying materials, rendering, executing code, and fetching PolyHaven assets. It also exposes prompt, provider, and model tools backed by a provider-agnostic LLM layer (Ollama, LM Studio, llama.cpp, OpenAI-compatible, Azure) that can be switched at runtime.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to inspect and control a live Blender session through MCP tools that create, modify, and delete objects, apply materials, render images, execute Python, and pull PolyHaven assets over a local TCP add-on. It also exposes a provider-agnostic LLM layer that can be pointed at Ollama, LM Studio, llama.cpp, OpenAI-compatible, or Azure endpoints and switched at runtime.-