ahujasid/mcp-for-blender · 上手攻略

仓库：ahujasid/mcp-for-blender
链接：https://github.com/ahujasid/mcp-for-blender
分类：agent（Blender × LLM 的 MCP 集成，让 AI 建模与操控场景）
作者：spark
更新：2026-10-29

版本锚点：pyproject.toml 声明 version 2.2.6，requires-python >=3.10，依赖 mcp>=1.26.0,<2 与 httpx>=0.27.0；MIT 许可；作者 Siddharth Ahuja；README 最新提交 2026-10-29。⚠️ 注意 PyPI 包名已从 blender-mcp 改为 mcp-for-blender（仓库内 GitHub 组织名仍是 ahujasid/blender-mcp，克隆地址不变）。

一、这是什么

这是一个让任意 LLM 直接操控 Blender 的 MCP（Model Context Protocol）集成。核心机制很简单粗暴且有效：AI 不需要"理解"Blender 的建模命令，它直接写 Blender Python 代码并在你正在运行的 Blender 里执行。

系统由两个部件组成：

Blender 插件（addon.py） —— 在 Blender 内部起一个 socket server，接收并执行命令。
MCP Server（src/blender_mcp/server.py） —— Python 写的 MCP 服务端，连到上面那个 Blender 插件。

通信协议是 TCP socket 上的简单 JSON：命令是带 type 和可选 params 的 JSON 对象，响应是带 status 和 result/message 的 JSON 对象。

这不是 Blender 官方出品，README 顶部有明确免责声明："This is a third-party integration and not made by Blender"。

它的差异化能力集中在"视觉自检"：AI 建模完能自己看结果——多角度视图、相机视图、线框、X 光、动画条，还能渲染出图，从而检查自己做得对不对，再迭代修改。这比"盲写代码然后你去看"的循环高效得多。

二、解决什么问题

Blender 的学习曲线是出了名的陡。新手想搭个场景，要先学界面操作、再学节点编辑器、再学材质、再学灯光——光"把一个球放在立方体上方并切成等距视角"就够卡半天。

这个项目把 Blender 的建模、布局、材质、动画、绑定、重拓扑全部转成自然语言 + 视觉反馈的循环。你说"造一个低多边形地牢场景，一条龙守着金 pot"，它写 Python、建模、渲染截图给你看、然后自己检查并改。

对另一类用户——已经有 Blender 资产库的美术——它还提供资产检索与导入：Poly Haven 的约 2400 个 HDRI/贴图/模型（全 CC0 免费）、Sketchfab 模型、Poly Pizza 约 10600 个低多边形模型（含被救回来的 Google Poly 存档）。

三、快速安装

方式 A：一键脚本

macOS / Linux：

curl -LsSf https://www.mcp-for-blender.com/install.sh | sh

Windows（PowerShell）：

irm https://www.mcp-for-blender.com/install.ps1 | iex

从 CMD 调 PowerShell 版：powershell -c "irm https://www.mcp-for-blender.com/install.ps1 | iex"

它做的事：装 uv（需要的话）→ 扫描本机上的 MCP 客户端（Claude Desktop、Claude Code、Codex、Cursor、VS Code、Devin Desktop/Windsurf、OpenCode、Antigravity），让你挑要配哪些 → 安装并启用 Blender 插件。它只往现有配置里加一个 blender 条目，并为每个改动的文件存一份 .bak。

⚠️ 如果 Windows Defender 拦了脚本，或者你不想跑远程脚本，就用下面的方式。

方式 B：手动三步

第 1 步，装 uv（README 明确警告：不要用 pip install uv，那可能不生成 uvx 命令，或者把 uv 藏在客户端看不到的环境里）：

# macOS
brew install uv
# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
winget install --id=astral-sh.uv -e

第 2 步，把 MCP server 加到客户端：

Claude Desktop（Settings → Developer → Edit Config，claude_desktop_config.json）：

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["mcp-for-blender"]
    }
  }
}

Claude Code：

claude mcp add blender uvx mcp-for-blender

Codex：

codex mcp add blender -- uvx mcp-for-blender

第 3 步，装 Blender 插件：

uvx mcp-for-blender install-addon

然后在 Blender 里：Edit → Preferences → Add-ons → 启用 Interface: MCP for Blender。

第 4 步，连接：打开 Blender，3D 视图侧边栏按 N → 打开 MCP for Blender 标签页 → 勾选想用的能力 → 点 Connect to Claude。插件在 Blender 打开时会自动启动 server；没起就点 Start MCP Server。

前置要求：Blender 3.0+、Python 3.10+、uv。

方式 C：Docker 跑 MCP server

Blender 仍跑在本机，容器只托管 MCP server：

docker build -t mcp-for-blender .

{
  "mcpServers": {
    "blender": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-for-blender"]
    }
  }
}

-i 是必须的——server 走 stdin/stdout 和客户端通信。镜像默认 BLENDER_HOST=host.docker.internal，在 macOS 和 Windows 的 Docker Desktop 上开箱即用。

四、核心用法

4.1 九个工具

工具	用途
`execute_blender_code`	在你活着的 Blender 里跑 Python
`look`	从 viewport / camera / angles（自动取景的多视图拼版）/ frames（动画条）看结果，绘制模式可选 solid / material / rendered / wireframe / xray；也能显示渲染图或图片文件
`get_scene_info`	紧凑的场景摘要，每个对象一行，按你指定的字段（位置、材质、拓扑、权重……）；可用 `root` 或 `query` 下钻
`generate_3d`	一次调用生成并导入模型，源可选 Tripo、Hunyuan3D、Hyper3D Rodin、Meshy。付费生成器会被自动优先
`search_assets` / `import_asset`	Poly Haven 的 HDRI/贴图/模型，Sketchfab 模型，Poly Pizza 低多边形模型
`get_addon_status`	Blender 版本、插件版本、哪些库和生成器已启用
`disable_telemetry` / `record_trajectory_feedback`	数据收集控制

4.2 典型提示词

README 给了这些例子，可以直接照抄：

"Create a low poly scene in a dungeon, with a dragon guarding a pot of gold"
"Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven"
给一张参考图，让它照着建场景
"Get information about the current scene, and make a threejs sketch from it"
"Generate a 3D model of a garden gnome through Hyper3D"
"Make this car red and metallic"
"Create a sphere and place it above the cube"
"Make the lighting like a studio"
"Point the camera at the scene, and make it isometric"

4.3 资产检索与导入的具体调用

Poly Haven 检索理解意图而非匹配关键词——搜 "couch" 会找到沙发，且支持任何语言。previews=3 会先附上前几名的缩略图再花带宽。导入是一次调用完成：

search_assets(source="polyhaven", query="overcast afternoon", asset_type="hdris")
import_asset(source="polyhaven", id="...", asset_type="textures", apply_to=["Wall"])

搜索支持按分类路径或属性过滤（HDRI 可按天气、时段，贴图可按表面用途与状态；填了未知属性会报错并列出合法值）。

导入模型用的是 .blend——即作者原始创作的文件，glTF/FBX/USD 版本是从它生成的、会丢材质细节。贴图会构建一个 Principled 材质，HDRIs 会被打包进文件，所以存盘换机后灯光仍在，并且会作为新 world 出现，不会覆盖你已有的 world。

授权与署名：Poly Haven 资产全 CC0，永远不需要署名。但其 API 条款要求使用实时 API 的软件要标明资产来源，所以搜索和导入响应会带上来源名和资产页面链接；导入时 polyhaven_id、polyhaven_url、polyhaven_authors、polyhaven_resolution、polyhaven_licence 会作为自定义属性写进对象/材质/图像/world，之后打开 .blend 的人仍能找到资产和作者。

Poly Pizza 需要免费 API key（poly.pizza/settings/api），在侧边栏勾 "Use assets from Poly Pizza" 后粘贴：

search_assets(source="polypizza", query="chair", licence="CC0")
import_asset(source="polypizza", id="...", target_size=1.0)

返回结果带许可证和三角面数。

4.4 环境变量与多实例

变量	默认	说明
`BLENDER_HOST`	`localhost`	Blender socket server 地址
`BLENDER_PORT`	`9876`	端口
`BLENDER_MCP_SAFE_MODE`	关	设为 1 则执行前校验脚本
`BLENDER_MCP_APPS`	auto	强制打开内联视口 app
`BLENDER_MCP_OPENAI_FORMS`	auto	强制打开缩略图资产选择器

CLI 标志优先级高于环境变量，且方便开多个 Blender 实例：

uvx mcp-for-blender --port 9877

对应配置可以写两个条目：

{
  "mcpServers": {
    "blender":   { "command": "uvx", "args": ["mcp-for-blender"] },
    "blender-b": { "command": "uvx", "args": ["mcp-for-blender", "--port", "9877"] }
  }
}

每个实例需要在 Blender 插件面板里设成对应端口。

4.5 Safe Mode

默认情况下 AI 可以在 Blender 里跑任意 Python。设 BLENDER_MCP_SAFE_MODE=1 后，每个脚本执行前会被检查并拦截危险代码：直接读写文件、运行其他程序、访问网络、以及安装会在脚本结束后继续运行的代码。正常的 Blender 工作（建模、材质、渲染、保存、导入导出）不受影响。被拦截的脚本会带着原因回给 AI，让它改一版再试。

4.6 Codex 插件形态

Codex CLI、桌面应用和 IDE 扩展共用同一个配置文件（~/.codex/config.toml），配一次覆盖三处。插件版本还提供聊天内联视口（点对象可附加到下一条消息）、Poly Haven / Sketchfab / Poly Pizza 缩略图选择器，以及对场景对象/材质/集合的 @ 引用。

⚠️ 但 README 明确说："It isn't in the Codex plugin directory yet"，要从本仓库装：

git clone https://github.com/ahujasid/blender-mcp.git
codex plugin marketplace add ./blender-mcp/integrations/codex

五、典型适用场景

新手搭场景：不用碰界面，用自然语言拼出低多边形地牢、沙滩氛围这类完整场景。
参考图复刻：给一张图，让它建成 3D 场景。
批量资产填充："Fill this room with low-poly furniture from Poly Pizza"。
程序化生成模型：通过 Tripo / Meshy / Hunyuan3D / Hyper3D Rodin 直接生成带贴图的模型再导入。
材质与灯光微调："Make this car red and metallic"、"Make the lighting like a studio"、"Point the camera at the scene, and make it isometric"——这些"改一处看效果"的循环正是它视觉自检能力的用武之地。
把 Blender 变成 agent 可操作的场景图：配合 Codex 的 @ 引用对象/材质/集合，做场景问答与改写。

六、坑与注意

⚠️ 插件的 socket server 没有任何认证和加密。README 原话："anyone who can reach that port can run Python inside Blender"。保持只监听 localhost，除非在可信网络；远程访问优先用 SSH 隧道，不要直接把 --host/BLENDER_HOST 指向远程机器。
⚠️ execute_blender_code 允许在 Blender 里跑任意 Python。README 明确警告这是"powerful but potentially dangerous"，生产环境要谨慎，并务必先保存工作。
⚠️ 只能跑一个 MCP server 实例（Cursor 和 Claude Desktop 不能同时跑）。
⚠️ GUI 启动的客户端不继承终端 PATH。Claude Desktop / Cursor / 从 Dock 启动的 VS Code 会报 spawn uvx ENOENT，即使你终端里 uvx 好好的。解决：把 command 写成 uvx 的绝对路径（which uvx / where uvx），或 Windows 上包一层 "command": "cmd", "args": ["/c", "uvx", "mcp-for-blender"]。
⚠️ 改完 PATH 或配置必须完全退出并重启客户端。Windows 上要从系统托盘退出（不是只关窗口），macOS 用 Cmd+Q。
⚠️ conda / pyenv / asdf 会抢解释器导致安装失败。uv 可能挑到一个依赖没有 wheel 的解释器。稳妥配置是钉住 Python 3.11 并只用 uv 托管的解释器：

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-for-blender"],
      "env": { "UV_PYTHON_PREFERENCE": "only-managed" }
    }
  }
}

⚠️ 注意仓库里的 .python-version 只是给贡献者看的提示，不影响 uvx。

⚠️ 装失败后即使修好了也可能重放旧缓存。清缓存：

uv cache clean mcp-for-blender blender-mcp && uvx --refresh mcp-for-blender

⚠️ 不要在终端里手跑 uvx 来"启动 server"。README 排障表明确写：不要这么做，server 应该由客户端拉起。有时候第一条命令会失败，之后就好了。
⚠️ Poly Haven 下载会让 Blender 冻住。资产在 Blender 主线程下载，传输结束前 UI 无响应。文件大小每档分辨率约翻四倍，所以除非素材贴近相机，否则要求 1k 或 2k。
⚠️ Poly Pizza 在机房/VPN/云 IP 上会被 Cloudflare 挑战拦住。static.poly.pizza 有机器人防护，屏蔽数据中心、VPN 和云 IP。你的 API key 没问题——CDN 根本看不到它。换个正常网络重试，或手动下载 .glb 后用 File → Import → glTF 2.0。
⚠️ 复杂操作需要拆步，否则容易超时。超时了就把请求简化或拆成更小的步骤。
⚠️ Poly Haven 想不用就关掉——Blender 插件面板里有对应勾选框。
⚠️ Hunyuan3D 官方 API 模式下，大陆账号与国际账号走的是不同服务。大陆（cloud.tencent.com）走 AI3D 3.0（ai3d，版本 2025-05-13，地域 ap-guangzhou），International (Pro) 开关保持关闭（默认）；国际账号（tencentcloud.com，Hunyuan-to-3D Professional）走 hunyuan（版本 2023-09-01，开 PBR，地域 ap-singapore），必须勾上 International (Pro) 开关（位于侧边栏 Tencent Hunyuan 3D → Official API）。国际凭据发到大陆端点会报 AuthFailure.SignatureFailure 或 ResourceUnavailable。
⚠️ 用自己的 Meshy key 需要付费套餐。Premium 通道则不需要自带 key。Meshy 生成模型按真实世界高度出、底部为原点，所以模型到达时是"站在地面上、大小合理"的状态——用自有 key 时建议让它生成 "in an A-pose" 或 "in an T-pose"，方便后续绑定。
⚠️ 走 Premium 的生成额度是按次计的：文本提示用默认质量，一张图算一次高质量生成。
⚠️ 包名迁移是最近才发生的事。PyPI 上 blender-mcp 已改名为 mcp-for-blender。老配置继续可用、无需改动（uvx blender-mcp 仍能跑），但新装应该用 mcp-for-blender。改动原因见 issue #366。
⚠️ 装在锁死的机器上可以完全绕开 uvx，用 pipx：

pipx install mcp-for-blender
pipx ensurepath

然后用 which mcp-for-blender / where mcp-for-blender 得到的绝对路径当 command，并去掉 args。

⚠️ 默认开的是遥测。有 disable_telemetry 工具和 BLENDER_MCP_* 控制项，显式关掉更省心。

七、与同类对比

	mcp-for-blender	Blender 内置 AI（4.x 起）	Claude 直接操控 GUI（computer use）	纯脚本 / Geometry Nodes
机制	MCP → socket → 写 Blender Python 执行	官方集成	截图 + 鼠标键盘动作	人工写 bpy 脚本
视觉自检	有（多视图/相机/线框/X光/动画条/渲染）	有	有，但靠通用截图理解	需自己安排
模型能力	任意 LLM + 任意 MCP 客户端	绑定官方生态	任意	无 AI
资产库	Poly Haven / Sketchfab / Poly Pizza / 生成模型	有官方资产库	无	需自备
成熟度	社区第三方，v2.2.6，32.6k star	官方支持但生态受限	通用、慢、易错	稳定但要写代码

核心差异：它不依赖视觉点击，而是让模型写精确的 Blender Python 再执行——这比 computer use 类方案精确得多、速度快得多，而且能利用 Blender 全套 API。它比官方内置 AI 更开放（任意 LLM、任意客户端），代价是不受官方支持、没有兼容性保证。

八、一句话推荐结论

如果你想让 AI 真正帮你建模而不只是"给灵感"，而且愿意接受"AI 能在你 Blender 里执行任意 Python"这个安全前提，mcp-for-blender 是目前生态最成熟、视觉自检链路最完整的选择；生产环境请务必开 Safe Mode 并先保存工作。

本文基于仓库 README（main 分支）、pyproject.toml v2.2.6、GitHub 组织页与 repo_cards/4732 采集。写作只读公开内容，未 clone、未运行代码、访问任何私密仓库。文中标注 ⚠️ 的条目为 README 明确声明的限制与排障项，非推测。