Skip to main content
Glama
Sign In
deenesjakoruzh
tattooinmtl

Blender MCP

by tattooinmtl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Blender MCP — 面向 Blender 5.2 LTS 的 Streamable-HTTP 桥接

一个 Model Context Protocol 桥接，让任何 MCP 客户端（Antigravity、Cursor、Claude Desktop、VS Code 1.101+、MiniMax Code、Windsurf、Continue、Cline、OpenCode、Codex、MCP Inspector……）都能通过自然语言驱动 Blender 5.2 LTS。

该插件在 Blender 内部的后台线程上运行一个 MCP Streamable-HTTP 服务器。客户端只需指向它——不会派生子进程，也无需维护 socket 对。

为什么采用这种形态

  • Blender 内部单一安装路径。 MCP 服务器使用 bpy 在进程内运行，因此无需 uvx/pipx 的繁琐操作，也无需保持 socket 对同步。

  • localhost 上的 Streamable HTTP。 适用于所有现代 MCP 客户端。

  • 插件内手写的 MCP 服务器。 Blender 5.2 LTS 默认捆绑 Python 3.13，且不包含外部包。一个约 300 行的 MCP 服务器比引入 mcp[cli] 并编辑 sys.path 更具可移植性。

  • 与客户端无关。 没有专有插件格式。任何能够访问 HTTP 端点（或通过 stdio 代理访问）的 MCP 客户端都可以工作。

Related MCP server: blender-mcp

项目结构

blender_addon_mcp/
├── README.md                      ← you are here
├── LICENSE                        ← MIT
├── pyproject.toml                 ← dev tooling for the add-on (ruff, mypy, pytest)
├── .gitignore
├── addon/
│   └── blender_mcp_addon/         ← zips into a Blender-installable .zip
│       ├── __init__.py            ← bl_info, register/unregister, preferences
│       ├── server/
│       │   ├── __init__.py
│       │   ├── mcp_server.py      ← MCP protocol (initialize, tools/list, tools/call, ping)
│       │   ├── transport.py       ← stdlib http.server, runs on a daemon thread
│       │   └── protocol.py        ← JSON-RPC 2.0 + MCP 2025-03-26 types
│       ├── tools/
│       │   ├── __init__.py        ← tool registry
│       │   ├── scene.py           ← scene_info, frame control
│       │   ├── objects.py         ← list, get, create, delete, transform
│       │   ├── materials.py       ← create, assign, modify
│       │   ├── modifiers.py       ← add, set params, remove
│       │   ├── render.py          ← render_image, screenshot_viewport
│       │   └── code.py            ← execute_python (with confirmation)
│       └── utils/
│           ├── __init__.py
│           ├── bpy_helpers.py     ← bpy → JSON serialization
│           └── safe_eval.py       ← ast-validated code execution
├── scripts/
│   ├── install_addon.ps1          ← zip and install into Blender
│   ├── blender_mcp_proxy.js       ← optional stdio/socket ↔ HTTP bridge for
│   │                                Antigravity builds that don't accept `url`
│   └── start_blender_mcp_bridge.ps1  ← start/stop/status lifecycle for the bridge
├── examples/
│   ├── mcp-configs.md             ← copy-paste configs for every major MCP client
│   ├── basic_scene.md
│   ├── material_setup.md
│   └── render_workflow.md
└── docs/
    ├── architecture.md
    ├── blender_5_2_notes.md
    └── tools_reference.md

快速开始

1. 安装插件

# clone
git clone https://github.com/tattooinmtl/Blender_MCP.git
cd Blender_MCP

# install the add-on into every Blender version on this machine
pwsh ./scripts/install_addon.ps1

2. 在 Blender 中启用服务器

  1. 打开 Blender。

  2. Edit → Preferences → Add-ons → 搜索 "Blender MCP" → 勾选复选框。

  3. 设置端口（默认 8765）并点击 Start Server（或使用 3D 视口侧边栏中的 Blender MCP 面板）。

  4. 控制台应打印：

[Blender MCP] Server listening on http://127.0.0.1:8765/mcp

3. 配置你的 MCP 客户端

选择你使用的客户端，并从 examples/mcp-configs.md 粘贴对应的代码片段。Antigravity 的 url 形式最简单：

{
  "mcpServers": {
    "blender": { "url": "http://127.0.0.1:8765/mcp" }
  }
}

Cursor、Claude Desktop、VS Code、MiniMax Code、Windsurf、Continue、Cline 和 MCP Inspector 的代码片段都在该文件中。

4. 验证

在任何 MCP 客户端聊天中：

使用 blender 服务器：ping。

你应该会看到代理对 ping 调用 tools/call 并报告一个空的成功结果。从终端：

curl -s -X POST http://127.0.0.1:8765/mcp `
  -H "Content-Type: application/json" `
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

BlenderMCP Dominator Bundle

此仓库还随附完整的 DomiNations/OpenCivilizations 项目，嵌套在插件内，路径为 blender_mcp_addon/dominator/。

附加工具：

工具

用途

dominator_health_check

验证插件、捆绑包、MCP 端点、Node/npm、MongoDB、Redis

dominator_setup_scene

配置 Dominator 渲染场景

dominator_build_unit

构建程序化单位（例如 ranged_shooter）

dominator_build_building

构建程序化建筑（wall、town_center）

dominator_render_asset

将场景渲染为 PNG

dominator_list_units

列出单位构建器

dominator_list_buildings

列出建筑构建器

dominator_apply_nation_palette

应用国家材质调色板

暴露的工具

工具

用途

只读

get_addon_info

能力握手——名称、版本、协议、工具列表。请先调用此工具。

是

scene_info

场景摘要（对象、灯光、相机、帧）

是

list_objects

列出场景对象，可选类型过滤器

是

get_object

完整对象详情（位置、旋转、缩放、修改器、材质）

是

create_object

创建基本体（立方体、球体、平面、圆柱体、圆锥体、圆环、空对象、相机、灯光）

否

delete_object

按名称删除对象

否

transform_object

设置位置/旋转/缩放

否

set_material

创建或分配带有 Principled BSDF 的材质

否

set_texture

将图像文件应用到材质输入（base_color、roughness、normal 等）

否

import_asset

导入 GLB/GLTF/FBX/OBJ/STL/PLY/DAE/USD/X3D/ABC

否

add_modifier

添加修改器（细分、镜像、实体化、阵列、倒角）

否

remove_modifier

按名称移除修改器

否

frame_get / frame_set

读取/移动时间线

混合

render_image

将当前帧渲染到文件

否

screenshot_viewport

捕获当前视口

否

execute_python

运行任意 bpy 代码（受 ast 验证保护）

否

ping

健康检查

是

完整模式和示例请参阅 docs/tools_reference.md。

开发

# syntax-check the add-on (Blender's Python is at <blender>/python/bin/python.exe)
python -m py_compile addon/blender_mcp_addon/__init__.py
python -m py_compile addon/blender_mcp_addon/server/mcp_server.py
# ...etc

# lint
ruff check addon/
mypy addon/

# test the MCP server in isolation (no bpy required)
pytest addon/tests/ -v

许可证

MIT。请参阅 LICENSE。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Blender MCP VXAI

    VxASI
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables natural language control of Blender 3D through MCP clients, allowing creation, modification, and manipulation of 3D models, animations, and scenes.
    300
    MIT

  • blender-mcp

    sandraschi
    A
    license
    C
    quality
    A
    maintenance
    Enables AI-powered control of Blender through natural language, allowing users to create, manipulate, and automate 3D scenes, objects, materials, animations, and more via Claude or other MCP clients.
    71
    62
    MIT

  • Blender MCP

    tattooinmtl
    A
    license
    Not graded
    quality
    C
    maintenance
    This server enables natural language control of Blender 5.2 LTS through any MCP client, allowing scene inspection, object and material manipulation, rendering, and safe Python execution.
    1
    MIT

  • Blender MCP

    tattooinmtl
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables any MCP client to drive Blender 5.2 LTS through natural language, with tools for scene inspection, object creation and transformation, material and modifier handling, rendering, viewport capture, and guarded Python execution.
    2
    MIT