Skip to main content
Glama

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 MCP add-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 插件

mcp-1.0.3.zip(下方脚本会下载并安装)

Python

3.10+(用 uvx 时自动管理,无需手动安装)

uv

Windows: winget install --id=astral-sh.uv -e

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:手动安装

  1. 下载 https://projects.blender.org/lab/blender_mcp/releases/download/v1.0.3/mcp-1.0.3.zip

  2. 打开 Blender → 编辑 → 偏好设置 → 插件 → 右上角下拉 → 从磁盘安装

  3. 搜索 MCP,勾选启用

  4. 确认偏好设置 → 系统 → 允许在线访问(插件需要)

  5. 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.whl

MCP 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)

类别

工具

代码执行

execute_blender_code、execute_blender_code_for_cli

工程体检

get_blendfile_summary_datablocks、..._missing_files、..._of_linked_libraries、..._path_info、..._usage_guess(各含 _for_cli 版本)

场景读取

get_objects_summary、get_object_detail_summary

文档检索

get_python_api_docs、search_api_docs、search_manual_docs

观察

get_screenshot_of_window_as_image、get_screenshot_of_area_as_image、get_screenshot_of_window_as_json、render_viewport_to_path、render_thumbnail_to_path

视图

jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name、jump_to_tab_by_name、jump_to_tab_by_space_type

本仓库新增(2)

工具

参数

说明

search_assets

query, asset_type(models/hdris/textures/all), category, limit, min_size_m

搜索 Poly Haven 资产,按下载量排序

import_asset

id, asset_type, resolution(1k/2k/4k/8k), target_size, apply_to, strength

下载并导入模型 / 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 -PyPI

scripts\publish.ps1 会:

  1. 从 pyproject.toml 读取版本号,清理并重新构建 dist/

  2. 构建 .mcpb

  3. git init(如需要)、提交、打 tag v<version>

  4. 用 gh 创建/推送仓库(-CreateRepo)并创建 GitHub Release,上传 wheel/sdist/.mcpb

  5. 若设置了 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

致谢与许可

Available Tools

28 tools
execute_blender_codeA
Destructive

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_cliA
Destructive

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_datablocksA
Read-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_cliB
Read-only

Return a data-block summary by opening blend_file in background Blender.

Inputs: blend_file (required). Returns: object

get_blendfile_summary_missing_filesA
Read-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_cliB
Read-only

Report missing file references by opening blend_file in background Blender.

Inputs: blend_file (required). Returns: object

get_blendfile_summary_of_linked_librariesA
Read-only

Return a tree of directly and indirectly linked library files.

Inputs: no named parameters. Returns: object

get_blendfile_summary_of_linked_libraries_for_cliB
Read-only

Return linked-library info by opening blend_file in background Blender.

Inputs: blend_file (required). Returns: object

get_blendfile_summary_path_infoA
Read-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_cliB
Read-only

Return path info by opening blend_file in background Blender.

Inputs: blend_file (required). Returns: object

get_blendfile_summary_usage_guessA
Read-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_cliA
Read-only

Guess use-cases by opening blend_file in background Blender.

Inputs: blend_file (required). Returns: object

get_object_detail_summaryA
Read-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_summaryA
Read-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_docsA
Read-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>.rst was read. Extra keys: content (RST text), examples. When the file exceeds 32 KB, content is replaced with a dot-point summary of the file's top-level definitions (prefixed by a header noting the truncation) and examples is empty - re-query individual members for their rendered blocks.

  • "namespace" (found=True): no <identifier>.rst but <identifier>.<child>.rst siblings exist. Extra key: submodules (list of child identifiers).

  • "definition" (found=True): identifier is defined inside a parent RST (e.g. bpy.props.IntProperty lives in bpy.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:

    • parent the identifier whose RST was loaded.

    • available top-level definitions in that RST.

    • submodules sibling 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.types available is empty and submodules is the near-miss list; for a self-contained module like bpy.props it'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_imageA
Read-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_imageA
Read-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_jsonA
Read-only

Return a JSON description of the Blender window layout, areas, active object, and selection.

Inputs: no named parameters. Returns: object

import_assetA
Destructive

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_nameB
Destructive

Switch the active workspace tab to name.

Inputs: name (required). Returns: object

jump_to_tab_by_space_typeA
Destructive

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_nameA
Destructive

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_nameA
Destructive

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_pathB
Destructive

Render a small, low-quality thumbnail to output_path (temporarily overrides settings).

Inputs: output_path (required). Returns: object

render_viewport_to_pathA
Read-only

Render the current scene to output_path using current render settings.

Inputs: output_path (required). Returns: object

search_api_docsA
Read-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 plus context paragraphs 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_assetsA
Read-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_docsA
Read-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 plus context paragraphs 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

    B3.4/5.0

    Scored across 28 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -