Blender MCP 完整指南

Blender MCP 完整指南

从概念到实操，从安装到排错。涵盖 AI 工具通过 MCP 控制 Blender 的全流程。
适用于 Windows，路径中 <用户名> 替换为实际用户名。

目录

第一部分：概念与原理

第二部分：环境准备

第三部分：Blender 插件安装

第四部分：blender-mcp 安装

第五部分：AI 智能体自动安装与检查

第六部分：LM Studio 配置

第七部分：Bionic 配置

第八部分：opencode 配置

第九部分：QwenPaw 配置

第十部分：其他 MCP 客户端

第十一部分：环境变量与高级配置

第十二部分：功能与工具

第十三部分：避坑清单

第十四部分：验证链路

附录

第一部分：概念与原理

1. AI 操纵软件的三种路线

AI 通过 MCP 操作专业软件（如 Blender、CAD、EDA）有三条技术路线：

路线原理代表适用场景精度
键鼠视觉模仿AI 看屏幕像素，输出 (x,y) 坐标+按键序列，像人一样点鼠标MIT VideoCAD只有封闭 GUI、无 API 的软件低（像素级易受缩放影响）
内核级集成AI 直接在软件内核工作，操作数据结构Altium ActiveRoute厂商自己集成的 EDA 工具高（数据级精确）
API 桥接层通过软件暴露的脚本接口做原子化操作Blender MCP、AutoCAD MCP有脚本 API 的现代软件高（API 级精确）

Blender MCP 属于第三种——API 桥接层

AI 客户端

MCP 协议

Blender 插件

bpy Python API

Blender 引擎

AI 操作的是场景图和数据结构（对象、材质、灯光），不是鼠标键盘坐标。

VideoCAD 的键鼠模仿路线（对比理解）

MIT 的 VideoCAD（NeurIPS 2025）是键鼠模仿路线的典型：

  • 训练数据：41,005 段 CAD 操作视频，逐帧标注鼠标移动、点击坐标、按键
  • 模型：Transformer，输出"下一个 UI 动作序列"
  • 难点：CAD 画布是 WebGL/OpenGL 渲染的像素堆，没有 DOM 结构可读

为什么 Blender 不用这条路线？ 因为 Blender 暴露了完整的 Python API（bpy），走 API 桥接更精准可靠。

2. MCP 协议基础

MCP（Model Context Protocol）是 Anthropic 提出的开放标准协议，用于标准化 AI 模型与外部工具之间的连接。

MCP 的核心设计原则

  • 开放标准：不绑定任何特定 AI 厂商
  • 模型无关：MCP Server 是 provider-agnostic 的，任何模型都能用
  • 两种传输模式：stdio（本地进程）和 HTTP/SSE（远程服务）

MCP 架构

MCP 协议

协议转换

MCP 客户端（AI 工具）
Claude / Cursor / LM Studio ...
模型思考发生在这里

MCP Server（翻译官）
不绑定任何 LLM，只负责协议转换

目标软件（Blender / CAD / EDA）

3. Blender MCP 架构

Blender MCP 是两段式桥接架构：

MCP 协议（stdio）

TCP Socket（JSON 协议）

bpy Python API

AI 客户端
LM Studio / Bionic / opencode / Claude ...

MCP Server
mcp-for-blender

Blender 插件
addon.py，跑在 Blender 内部

Blender 3D 引擎

组件说明

组件角色职责
Blender 插件执行器在 Blender 内部创建套接字服务器，接收和执行命令
MCP 服务器翻译官实现 MCP 协议，连接 Blender 插件，将工具调用转成 Blender 命令
AI 客户端决策者理解自然语言 → 决定调用哪些工具 → 发送结构化指令

通信协议

系统使用基于 TCP 套接字的简单 JSON 协议：

  • 命令以 JSON 对象形式发送，带有 type 和可选的 params
  • 响应是 JSON 对象，带有 status、result 或 message

blender-mcp 的版本历史

  • blender-mcp：旧包名，现已重命名为 mcp-for-blender
  • blender-mcp 是兼容包装器，安装时会自动安装 mcp-for-blender
  • 两者功能完全相同，配置时用 mcp-for-blender

4. stdio vs HTTP 连接模式

这是配置 Blender MCP 时最关键的概念。

stdio 模式（本指南使用的方式）

启动子进程

stdio 通信

TCP

AI 客户端

mcp-for-blender

Blender 插件
  • AI 客户端作为父进程启动 mcp-for-blender
  • 通过标准输入输出通信
  • mcp-for-blender 再通过 TCP 连接 Blender 插件
  • 适合：Blender 插件只提供 TCP socket 的情况

HTTP 模式（LM Studio 内置集成使用的方式）

HTTP 请求

实际是 TCP socket，不识别 HTTP

AI 客户端

http://localhost:9876

Blender 插件

连接被关闭
  • AI 客户端作为 HTTP 客户端连接
  • 目标必须是 HTTP MCP Server
  • 不适合：Blender 插件的 9876 是原始 TCP socket，不是 HTTP server

为什么 LM Studio 内置集成连不上

LM Studio 内置的 mcp/blender 集成配置的是 HTTP URL（http://localhost:9876），但 Blender 插件的 9876 是 TCP socket，不认识 HTTP 请求，直接关闭连接。

解决方案：关闭内置集成，改用 stdio 模式启动 mcp-for-blender。

第二部分：环境准备

5. 必需组件

组件版本要求说明获取方式
Blender3.0+3D 建模软件https://www.blender.org/download/
Python3.10+mcp-for-blender 运行环境uv 自动管理
uv / uvx最新版Python 包管理器（推荐）https://docs.astral.sh/uv/
Node.js18+部分 MCP 客户端需要https://nodejs.org/

Blender 版本确认

# 查看 Blender 版本
& "<Blender安装路径>\blender.exe" --version

# 查找 Blender 可执行文件
Get-ChildItem -Path 'D:\','C:\' -Filter 'blender.exe' -Recurse -Depth 3 -ErrorAction SilentlyContinue

Blender 绿色版

Blender 官方 zip 版（免安装）和安装版在插件功能上没有区别。绿色版直接解压即可使用，插件系统不依赖注册表写入。

注意：避免使用第三方制作的"精简版/汉化版/绿色版"，可能改了内部结构导致插件兼容性问题。

6. 安装 uv/uvx

uv 是新一代 Python 包管理器，比 pip 快很多，且自带虚拟环境管理。

# 通过 winget 安装（推荐）
winget install --id=astral-sh.uv -e

# 或通过 uv 官方安装器
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 验证
uv --version
uvx --version

# 获取 uvx.exe 的完整路径（后面配置会用到）
(Get-Command uvx).Source

常见 uvx 路径

安装方式路径
WinGetC:\Users\<用户名>\AppData\Local\Microsoft\WinGet\Packages\astral-sh.uv_Microsoft.Winget.Source_8wekyb3d8bbwe\uvx.exe
uv 安装器C:\Users\<用户名>\.local\bin\uvx.exe
CargoC:\Users\<用户名>\.cargo\bin\uvx.exe

让客户端找到 uvx

MCP 客户端从图形界面启动（Claude Desktop、Cursor、VS Code）不会继承终端的 PATH，所以裸 uvx 即使在终端里能运行，生成进程也可能失败。

如果发生 ENOENT: "command": "uvx" 错误：

  1. 找到 uvx 的完整路径（which uvx / where uvx）
  2. 在配置中使用完整路径替代裸 uvx
  3. 或用 cmd /c 包裹：
{
  "mcpServers": {
    "blender": {
      "command": "cmd",
      "args": ["/c", "uvx", "mcp-for-blender"]
    }
  }
}
  1. 更改 PATH 或配置后，完全退出并重启客户端（Windows：从系统托盘退出，不只是关窗口）

第三部分：Blender 插件安装

7. 官方命令行安装

官方提供了简洁的命令行安装方式，不需要手动下载源码包、解压、重命名文件。

方式 A：一键自动安装（推荐）

# 一条命令完成：安装 uv → 检测 MCP 客户端 → 安装 Blender 插件 → 启用插件
uvx mcp-for-blender setup

这个命令会：

  1. 在需要时自动安装 UV
  2. 检测你电脑上的 MCP 客户端（Claude Desktop、Claude Code、Codex、Cursor、VS Code、OpenCode、Antigravity 等）
  3. 让你选择要设置哪个客户端
  4. 自动安装并启用 Blender 插件
  5. 保留你现有的配置，只添加一个新条目，每个修改的文件都会保存 .bak 备份

方式 B：仅安装 Blender 插件

如果你只想安装插件，不配置 MCP 客户端：

uvx mcp-for-blender install-addon

这个命令会把插件复制到 Blender 的插件文件夹里，并打印写入位置，替换已有文件时会保留 .bak 备份。

方式 C：查看插件安装路径

uvx mcp-for-blender addon-paths

列出检测到的 Blender 插件文件夹路径，以及已有的 MCP for Blender 安装。

方式 D：手动在 Blender 中启用

如果命令行安装后需要在 Blender 中手动启用：

  1. 打开 Blender
  2. 前往 编辑 → 偏好设置 → 插件
  3. 搜索 “MCP for Blender” 并勾选启用
  4. 如果没显示，点击 “安装…” 然后选择插件文件
  5. 在 3D 视口按 N 键打开侧边栏
  6. 找到 “Blender 的 MCP” 标签页
  7. 点击 “启动 MCP 服务器”（如果没运行）
  8. 点击 “连接 Claude”（或对应 AI 客户端）

方式 E：手动下载安装（仅当命令行不可用时）

# 1. 下载 addon.py 文件
# 从 https://github.com/ahujasid/blender-mcp 仓库下载 addon.py

# 2. 在 Blender 中安装
# 编辑 → 偏好设置 → 附加组件 → 安装... → 选择 addon.py → 启用

插件信息

名称：MCP for Blender
版本：1.8+
作者：Siddharth Ahuja
最低 Blender 版本：3.0
位置：View3D > Sidebar > MCP for Blender（按 N 键打开侧边栏）

8. 验证插件

GUI 验证

  1. 打开 Blender
  2. 按 N 键，侧边栏应出现 “Blender 的 MCP” 标签页
  3. 点击 “启动 MCP 服务器”（如果没运行）
  4. 点击 “连接 Claude”（或对应 AI 客户端）

命令行验证

# 检查 Blender 是否在运行
Get-Process blender

# 检查 9876 端口是否在监听
Get-NetTCPConnection -LocalPort 9876 -State Listen

Blender 控制台验证

Window → Toggle System Console

启动 Blender 时看控制台有没有报错。

第四部分：blender-mcp 安装

9. pip 安装

# 国内用清华镜像（直连 PyPI 慢）
pip install mcp-for-blender -i https://pypi.tuna.tsinghua.edu.cn/simple

安装后 blender-mcp.exe 的位置：

  • C:\Users\<用户名>\AppData\Roaming\Python\Python314\Scripts\blender-mcp.exe

验证 pip 安装

$blenderMcpExe = "C:\Users\<用户名>\AppData\Roaming\Python\Python314\Scripts\blender-mcp.exe"
& $blenderMcpExe --help

blender-mcp vs mcp-for-blender

blender-mcp 是兼容包装器，安装时会自动安装 mcp-for-blender：

blender-mcp is now mcp-for-blender.
This package is a compatibility wrapper. Everything still works.
When convenient, update your MCP client config to:
    uvx mcp-for-blender

10. uvx 运行

不需要 pip install，直接用 uvx 运行：

# 测试
uvx mcp-for-blender --help

# 验证能连 Blender
$proc = Start-Process -FilePath "<uvx路径>" -ArgumentList 'mcp-for-blender','--host','localhost','--port','9876' -NoNewWindow -PassThru -RedirectStandardError "$env:TEMP\bm_test.txt"
Start-Sleep -Seconds 3
$proc.Kill()
Get-Content "$env:TEMP\bm_test.txt" | Select-String "Connected|error|fail"

如果看到 Connected to Blender at localhost:9876，说明底层链路正常。

blender-mcp 的启动参数

usage: mcp-for-blender [-h] [--host HOST] [--port PORT]
                       {install-addon,addon-paths,setup,update} ...

options:
  -h, --help            show this help message and exit
  --host HOST           Host of the Blender socket server (default: localhost)
  --port PORT           Port of the Blender socket server (default: 9876)

也可以通过环境变量传参：

  • BLENDER_HOST：替代 --host
  • BLENDER_PORT：替代 --port

CLI 标志优先于环境变量

CLI 标志优先于环境变量。这对运行多个 Blender 实例非常方便——每个 MCP 客户端的入口可以指向不同的端口：

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

每个实例都需要在 Blender 插件面板中匹配自己的端口设置。

11. pipx 替代方案

在被锁定的机器上，可以用 pipx 完全跳过 uvx：

pipx install mcp-for-blender
pipx ensurepath  # 然后重启 shell / 客户端

# 使用 pipx 安装的绝对路径作为 command，省略 args
# which mcp-for-blender / where mcp-for-blender

12. Docker 运行

可以把 MCP 服务器放在容器里运行，Blender 本身仍然运行在宿主机上：

# 构建镜像
docker build -t mcp-for-blender .

# macOS / Windows（Docker Desktop 默认可达主机）
# 配置中指向 docker run

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

Linux 上需要改用 host 网络：

{
  "mcpServers": {
    "blender": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network=host", "-e", "BLENDER_HOST=localhost", "mcp-for-blender"]
    }
  }
}

第五部分：AI 智能体自动安装与检查

13. 一键自动安装

官方一键安装脚本

# 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

# 命令提示符
powershell -c "irm https://www.mcp-for-blender.com/install.ps1 | iex"

这个脚本会自动：

  1. 安装 uv（如果还没装）
  2. 检测所有 MCP 客户端
  3. 让你选择要配置哪些
  4. 安装并启用 Blender 插件
  5. 保留现有配置，只添加条目，保存 .bak 备份

setup 命令详解

uvx mcp-for-blender setup
参数说明
--dry-run显示会做什么更改，但不实际修改
--yes / -y自动配置所有检测到的客户端，不逐个询问
--skip-addon只配置客户端，不安装 Blender 插件

用 AI 智能体自动安装

让 AI 智能体（如 Bionic、Claude Code）帮你执行安装：

方式 A：直接让 AI 运行命令

在 AI 聊天界面输入：

请帮我安装 Blender MCP。运行 uvx mcp-for-blender setup，然后告诉我结果。

AI 会：

  1. 检查 uv 是否安装
  2. 运行 setup 命令
  3. 报告检测结果和配置状态

方式 B：分步让 AI 操作

1. 检查我的 Blender 版本
2. 安装 uv（如果还没装）
3. 运行 uvx mcp-for-blender install-addon 安装插件
4. 帮我配置 MCP 客户端的 mcp.json
5. 验证连接是否正常

14. AI 智能体自动检查

检查清单

让 AI 智能体按以下顺序检查整个链路：

请帮我检查 Blender MCP 的安装状态：

1. 检查 Blender 是否在运行：Get-Process blender
2. 检查 9876 端口是否在监听：Get-NetTCPConnection -LocalPort 9876 -State Listen
3. 检查 uvx 是否可用：uvx --version
4. 检查 mcp-for-blender 是否能启动：uvx mcp-for-blender --help
5. 检查 mcp-for-blender 能否连 Blender：短暂启动看日志
6. 检查 LM Studio 的 mcp.json 配置是否正确
7. 检查 Bionic 的 ng-mcp.json 配置是否正确
8. 报告每一步的结果，指出任何异常

AI 自动修复建议

如果 AI 智能体检测到问题，可以让它自动修复：

检查结果显示 9876 端口没有监听。请：
1. 尝试重启 Blender
2. 如果还是不行，检查 Blender 插件是否已启用
3. 如果插件未启用，运行 uvx mcp-for-blender install-addon 重新安装
4. 重新检查端口状态

第六部分：LM Studio 配置

15. mcp.json 配置

配置文件路径

C:\Users\<用户名>\.lmstudio\mcp.json

写入配置

$uvx = (Get-Command uvx).Source -replace '\\','/'
$mcpJson = @"
{
  "mcpServers": {
    "blender": {
      "command": "$uvx",
      "args": ["mcp-for-blender"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}
"@
$utf8NoBom = [System.Text.UTF8Encoding]::new($false)
[System.IO.File]::WriteAllText("C:\Users\$env:USERNAME\.lmstudio\mcp.json", $mcpJson, $utf8NoBom)

界面操作

  1. 完全关闭 LM Studio
  2. 重新打开 LM Studio
  3. 进入 Program → Edit mcp.json，确认内容正确
  4. 保存（Ctrl+S）
  5. LM Studio 自动加载 MCP server
  6. 在 Integrations 面板找到 blender，打开开关

配置要点

要点说明
正斜杠 /JSON 里不能用 \（会触发转义错误），用 / 代替
无 BOM用 UTF8Encoding($false) 写，否则 LM Studio 报 “Unexpected token”
env 传参用环境变量 BLENDER_HOST/BLENDER_PORT，不用命令行参数

16. 镜像源加速

问题

LM Studio 默认从 HuggingFace 官方源下载模型，国内直连速度只有几百 KB/s。

解决方案

修改 LM Studio 安装目录下的 js 文件，把 huggingface.co 替换为 hf-mirror.com：

$lmDir = "C:\Users\<用户名>\AppData\Local\Programs\LM Studio"

$files = @(
    "$lmDir\resources\app\.webpack\main\index.js",
    "$lmDir\resources\app\.webpack\renderer\main_window.js"
)

foreach ($f in $files) {
    $bak = "$f.bak_$(Get-Date -Format 'yyyyMMdd_HHmmss')"
    Copy-Item $f $bak -Force
    $content = [System.IO.File]::ReadAllText($f, [System.Text.Encoding]::UTF8)
    $hfCount = ([regex]::Matches($content, 'huggingface\.co')).Count
    $newContent = $content -replace 'huggingface\.co', 'hf-mirror.com'
    [System.IO.File]::WriteAllText($f, $newContent, [System.Text.Encoding]::UTF8)
    Write-Output "$f: replaced $hfCount occurrences"
}

备选方案：手动下载

平台地址说明
hf-mirrorhttps://hf-mirror.comHuggingFace 国内镜像
ModelScopehttps://modelscope.cn阿里达摩院，国内下载快

模型目录：C:\Users\<用户名>\AppData\Local\LM Studio\models\

17. Staff Picks 筛选

“Only include Staff Picks that can fit on this device” 的含义

词组含义
Staff PicksLM Studio 官方编辑团队精选的模型
that can fit on this device经过计算确认能装进本机内存/显存
Only include只显示满足上面两个条件的

建议保持勾选——避免下载了模型结果发现跑不动。

第七部分：Bionic 配置

18. ng-mcp.json 配置

配置文件路径

C:\Users\<用户名>\.lmstudio\apps\bionic\.internal\ng-mcp.json

Bionic vs LM Studio 的区别

对比项LM StudioBionic
定位本地 LLM 运行器Agent 智能体平台
MCP 配置文件~/.lmstudio/mcp.json~/.lmstudio/apps/bionic/.internal/ng-mcp.json
配置格式mcpServers (对象)servers (数组)
连接字段command, args, envconnection.type, connection.command, connection.args, connection.env

Bionic 的 JSON 格式

{
  "servers": [
    {
      "id": "blender-001",
      "name": "blender",
      "description": "Blender MCP - control Blender 3D via MCP",
      "enabled": true,
      "connection": {
        "type": "stdio",
        "command": "<uvx路径>",
        "args": ["mcp-for-blender"],
        "env": {
          "BLENDER_HOST": "localhost",
          "BLENDER_PORT": "9876"
        }
      }
    }
  ]
}

写入配置

$uvx = (Get-Command uvx).Source -replace '\\','/'
$ngMcp = @"
{
  "servers": [
    {
      "id": "blender-001",
      "name": "blender",
      "description": "Blender MCP - control Blender 3D via MCP",
      "enabled": true,
      "connection": {
        "type": "stdio",
        "command": "$uvx",
        "args": ["mcp-for-blender"],
        "env": {
          "BLENDER_HOST": "localhost",
          "BLENDER_PORT": "9876"
        }
      }
    }
  ]
}
"@
$utf8NoBom = [System.Text.UTF8Encoding]::new($false)
[System.IO.File]::WriteAllText("C:\Users\$env:USERNAME\.lmstudio\apps\bionic\.internal\ng-mcp.json", $ngMcp, $utf8NoBom)
# 重启 Bionic

重要提醒

Bionic 的界面操作可能会清空 ng-mcp.json 的内容。如果配置丢失，在界面里手动添加。

19. 界面添加自定义 MCP

  1. Bionic → MCP 页面
  2. 点 “+ 添加自定义 MCP”
  3. 填写表单：
字段值
名称blender
描述控制 Blender 3D 建模——创建对象、修改材质、打灯光、渲染场景
连接方式选 “在此电脑上”
命令<uvx路径>
参数mcp-for-blender（只填这一个，不加 --host --port）
环境变量BLENDER_HOST = localhost，BLENDER_PORT = 9876
  1. 保存 → 打开开关 → @blender 测试

20. Bionic 技能系统

技能是什么

技能是文件夹，包含至少一个 SKILL.md 文件。SKILL.md 是 Markdown 文件，开头有 YAML frontmatter。

技能结构

~/.lmstudio/skills/
└── 技能名/                    ← 文件夹名必须和 frontmatter 的 name 一致
    └── SKILL.md              ← 唯一的必需文件

SKILL.md 格式

---
name: my-skill
display-name: My Skill
description: 这个技能做什么
user-invocable: true
disable-model-invocation: false
---

# 技能内容

frontmatter 字段

字段说明
name技能唯一标识，kebab-case，必须和文件夹名一致
display-name界面显示名
description简短描述，模型判断"是否相关"的依据
user-invocabletrue = 用户可 @ 触发；false = 不能
disable-model-invocationtrue = 模型不会自动读取；false = 会自动判断

安装技能

bionic_tool(
  name="skill.install",
  args=["--skill-folder-path", "/absolute/scratchpad/技能名"]
)

安装 Blender 技能示例

~/.lmstudio/skills/blender-control/
└── SKILL.md

---
name: blender-control
display-name: Blender Control
description: 通过 MCP 控制 Blender 3D 建模——创建对象、修改材质、打灯光、渲染场景
user-invocable: true
disable-model-invocation: false
---

# Blender Control Skill

当用户需要操作 Blender 时使用此技能。

## 前提条件
- Blender 必须在运行中（插件监听 TCP 9876）
- mcp-for-blender MCP server 必须已启动

第八部分：opencode 配置

21. opencode.jsonc 配置

配置文件路径

C:\Users\<用户名>\.config\opencode\opencode.jsonc

opencode 的格式特点

  • 用 mcp 键，不是 mcpServers
  • command 是数组（["命令", "参数"]），不是分开的字段
  • environment 是对象

写入配置

$uvx = (Get-Command uvx).Source -replace '\\','/'
$opencodeConfig = @"
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "blender-mcp": {
      "type": "local",
      "command": ["$uvx", "mcp-for-blender"],
      "enabled": true,
      "environment": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}
"@
$utf8NoBom = [System.Text.UTF8Encoding]::new($false)
[System.IO.File]::WriteAllText("C:\Users\$env:USERNAME\.config\opencode\opencode.jsonc", $opencodeConfig, $utf8NoBom)

第九部分：QwenPaw 配置

22. 安装 QwenPaw

pip install qwenpaw
qwenpaw init --defaults
qwenpaw app  # 浏览器打开 http://127.0.0.1:8088/
qwenpaw      # TUI 模式

23. 界面配置

  1. 打开控制台（http://127.0.0.1:8088/）
  2. 进入 智能体 → MCP
  3. 点 “+ 创建”
  4. 粘贴 JSON 配置（标准 mcpServers 格式）
  5. 点 “创建” 完成

24. 命令行配置

qwenpaw mcp --help
qwenpaw mcp create --name blender --config '<json配置>'

25. 三种 JSON 格式

格式一：标准 mcpServers 格式（推荐）

{
  "mcpServers": {
    "blender": {
      "command": "<uvx路径>",
      "args": ["mcp-for-blender"],
      "env": { "BLENDER_HOST": "localhost", "BLENDER_PORT": "9876" }
    }
  }
}

格式二：直接键值对格式

{
  "blender": {
    "command": "<uvx路径>",
    "args": ["mcp-for-blender"],
    "env": { "BLENDER_HOST": "localhost", "BLENDER_PORT": "9876" }
  }
}

格式三：远程 URL 格式（仅适用于 HTTP MCP 服务）

{
  "mcpServers": {
    "blender": {
      "transport": "streamable_http",
      "url": "http://localhost:9876"
    }
  }
}

第十部分：其他 MCP 客户端

26. Claude Desktop

配置文件：

  • Windows: C:\Users\<用户名>\AppData\Roaming\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["mcp-for-blender"]
    }
  }
}

27. Claude Code

claude mcp add blender uvx mcp-for-blender

28. Codex

配置文件：~/.codex/config.toml

[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]

或用 CLI：

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

Codex 插件（推荐）

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

插件提供实时视口、缩略图选择器、场景对象/材质/集合的 @-mentions。

29. Cursor

macOS：MCP → 设置 → 粘贴配置

Windows：设置 → MCP → 添加服务器

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

注意：只运行一个 MCP 服务器实例，不要同时在 Cursor 和 Claude Desktop 上运行两个。

30. VS Code

使用 LM Studio 的 MCP 集成或安装 mcp-for-blender server 扩展。

31. Antigravity

{
  "mcpServers": {
    "blender-mcp": {
      "command": "uvx",
      "args": ["mcp-for-blender"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

第十一部分：环境变量与高级配置

32. 环境变量总表

变量默认值描述
BLENDER_HOSTlocalhostBlender 套接字服务器的主机地址
BLENDER_PORT9876Blender 套接字服务器的端口号
BLENDER_MCP_SAFE_MODE(off)设为 1 在脚本运行前验证脚本
BLENDER_MCP_APPSauto设为 1 强制启用内联视口应用
BLENDER_MCP_OPENAI_FORMSauto设为 1 强制开启缩略图资源选择器
DISABLE_TELEMETRY(off)设为 true 完全关闭遥测

示例

# 用环境变量
$env:BLENDER_HOST = 'localhost'
$env:BLENDER_PORT = '9876'

# 或用 CLI 标志（优先于环境变量）
uvx mcp-for-blender --port 9877

33. 安全模式

默认情况下，AI 可以在 Blender 中运行任何 Python 代码。设置安全模式会在脚本运行前检查每个脚本，阻止有风险的代码——比如直接读写文件、运行其他程序、访问网络，或安装脚本结束后仍继续运行的代码。

# 启用安全模式
$env:BLENDER_MCP_SAFE_MODE = "1"

或在配置中：

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["mcp-for-blender"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876",
        "BLENDER_MCP_SAFE_MODE": "1"
      }
    }
  }
}

正常的 Blender 工作（建模、材质、渲染、保存、导入导出）依然能正常工作。被阻断的脚本会带回原因给 AI，让它用修正后的版本重新尝试。

34. Python 版本钉住

避免 conda / pyenv / 版本冲突。uv 会选择哪个 Python 来运行服务器。在带有 conda（自动激活 base）、pyenv 或 asdf 的机器上，uv 可以抓取一个解释器，导致安装失败。

Pin Python 3.11，并倾向于使用 uv 管理的解释器：

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

如果之前的失败尝试在修复后还不断重放，清除缓存：

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

35. API 凭证持久化

Blender 的 MCP 支持通过 Blender 附加偏好设置持久凭证：

编辑 → 偏好设置 → Blender 的 MCP → 插件

可以存储以下凭证：

  • Sketchfab API 密钥
  • Poly Pizza API 密钥
  • Hyper3D API 密钥
  • Hunyuan3D SecretId / SecretKey
  • Hunyuan3D API URL
  • Meshy API 密钥
  • Tripo API Key

也可以通过环境变量注入：

变量说明
BLENDERMCP_SKETCHFAB_API_KEYSketchfab API 密钥
BLENDERMCP_POLYPIZZA_API_KEYPoly Pizza API 密钥
BLENDERMCP_HYPER3D_API_KEYHyper3D API 密钥
BLENDERMCP_HUNYUAN3D_SECRET_IDHunyuan3D SecretId
BLENDERMCP_HUNYUAN3D_SECRET_KEYHunyuan3D SecretKey
BLENDERMCP_HUNYUAN3D_API_URLHunyuan3D API URL
BLENDERMCP_MESHY_API_KEYMeshy API 密钥
BLENDERMCP_TRIPO_API_KEYTripo API 密钥

第十二部分：功能与工具

36. 九大工具

AI 自己编写 Blender Python，MCP 增加了 Python 本身无法完成的功能，作为九个工具：

工具用途
execute_blender_code在 Live Blender 里运行 Python
look视口视图：多视角、摄像机、线框、X 光、动画条、渲染
get_scene_info简洁的场景摘要，每个物体一行
generate_3d用 Tripo、Hunyuan3D、Hyper3D Rodin 或 Meshy 生成并导入模型
search_assets搜索资产库（Poly Haven、Sketchfab、Poly Pizza）
import_asset导入资产到场景
get_addon_statusBlender 版本、插件版本、库和生成器启用状态
disable_telemetry关闭遥测
record_trajectory_feedback轨迹反馈

37. 资产库

Poly Haven

约 2400 个 HDRI、贴图和模型，全部 CC0 免费，无需 API 密钥。

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

Sketchfab

需要 API 密钥。搜索和下载 3D 模型。

Poly Pizza

约 10,600 个免费低多边形模型。需要免费 API 密钥（poly.pizza/settings/api）。

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

38. AI 3D 生成

生成器说明凭证需求
Tripo文本或参考图生成纹理 3D 模型Premium 免密钥，或自带 Tripo API 密钥
Meshy文本或参考图生成纹理 3D 模型Premium 免密钥，或自带 Meshy API 密钥
Hunyuan3D腾讯云 Hunyuan3D 官方 API需要 SecretId/SecretKey
Hyper3D Rodin生成 3D 模型需要 Hyper3D API 密钥

39. 示例命令

提示演示
“在地牢里创建一个低多边形场景，一条龙守着一罐金子”建模
“用 HDRI、贴图和模型营造海滩氛围”场景+资产
“给出一张参考图片，然后创建 Blender 场景”参考图建模
“获取当前场景信息，画出三视角速写”场景查询+渲染
“通过 Hyper3D 生成花园侏儒的 3D 模型”AI 3D 生成
“用 Meshy 生成一把木制摇椅”AI 3D 生成
“用 Tripo 生成陶瓷茶壶”AI 3D 生成
“用 Poly Pizza 的低多边形家具填满这个房间”资产导入
“让这辆车红色金属感”材质修改
“创建一个球体并放在立方体上方”对象操作
“让灯光像工作室一样”灯光设置
“把摄像机对准场景，让它等距”摄像机控制

第十三部分：避坑清单

40. 常见坑与解决

坑症状原因解决
mcp.json “Bad escaped character”LM Studio 报 JSON 解析错误路径里 \U 是 JSON 转义字符用正斜杠 / 代替 \
mcp.json “Unexpected token”LM Studio 报 JSON 解析错误文件带 BOM用 UTF8Encoding($false) 写，无 BOM
LM Studio “Connection closed”状态红点，MCP error -32000内置 mcp/blender 用 HTTP 连接，Blender 是 TCP socket关闭内置集成，改用 stdio 启动 uvx
Bionic 不读取 ng-mcp.jsonBionic MCP 列表为空Bionic 可能清空了配置文件在界面里"添加自定义 MCP"填写
pip 安装超时pip install 卡住国内直连 PyPI 慢用清华镜像 -i https://pypi.tuna.tsinghua.edu.cn/simple
LM Studio 下载模型慢速度几百 KB/s默认走 HuggingFace 官方源替换安装目录下 js 文件的 huggingface.co → hf-mirror.com
ENOENT: “command”: “uvx”MCP 客户端找不到 uvx客户端不继承终端 PATH用 uvx 完整路径，或用 cmd /c 包裹
Poly Haven 下载时卡死Blender UI 冻结从主线程下载，文件大要求 1k 或 2k 分辨率，不要 8k
Poly Pizza Cloudflare 挑战下载失败CDN 屏蔽数据中心 IP从正常连接重试，或手动下载 .glb 导入
Python 版本冲突安装失败conda/pyenv 干扰 uv钉住 --python 3.11 + UV_PYTHON_PREFERENCE=only-managed
LM Studio mcp.json 路径不对LM Studio 不读取配置路径放错位置LM Studio 读 ~/.lmstudio/mcp.json
Bionic 参数里 localhost 有空格连接失败界面输入时多了空格检查并去掉空格
opencode 和 LM Studio 格式混淆配置不生效opencode 用 mcp 键，LM Studio 用 mcpServers按各自格式配置
LM Studio 和 Bionic 同时运行冲突MCP 连接异常两套 MCP 系统冲突关闭一个只保留另一个
uvx 缓存了旧版本更新不生效uvx 缓存旧包uv cache clean mcp-for-blender + uvx --refresh
execute_blender_code 安全风险任意代码执行默认无安全限制启用 BLENDER_MCP_SAFE_MODE=1
只运行一个 MCP 实例连接冲突Cursor + Claude Desktop 同时运行只运行一个实例

第十四部分：验证链路

41. 链路架构

AI 工具 → stdio 启动 uvx → mcp-for-blender → TCP 9876 → Blender 插件 → bpy API → Blender 执行

42. 逐层排查

# 1. Blender 在运行？
Get-Process blender

# 2. 9876 端口在监听？
Get-NetTCPConnection -LocalPort 9876 -State Listen

# 3. uvx 能运行 mcp-for-blender？
uvx mcp-for-blender --help

# 4. mcp-for-blender 能连 Blender？
$proc = Start-Process -FilePath "<uvx路径>" -ArgumentList 'mcp-for-blender','--host','localhost','--port','9876' -NoNewWindow -PassThru -RedirectStandardError "$env:TEMP\bm_test.txt"
Start-Sleep -Seconds 3
$proc.Kill()
Get-Content "$env:TEMP\bm_test.txt" | Select-String "Connected|error|fail"

# 5. LM Studio 日志里有没有 blender 报错？
Get-Content "C:\Users\<用户名>\AppData\Roaming\LM Studio\logs\main.log" -Tail 100 | Select-String "blender"

# 6. 检查 TCP 连接
$tcp = New-Object System.Net.Sockets.TcpClient
try { $tcp.Connect('127.0.0.1', 9876); Write-Output "Connected"; $tcp.Close() } catch { Write-Output "Failed: $_" }

43. 最终验证

在任意 AI 工具的聊天界面输入：

“在原点创建一个红色立方体”

Blender 里出现红色立方体 = 整条链路打通。

附录

一键配置脚本

$uvx = (Get-Command uvx).Source -replace '\\','/'
$utf8NoBom = [System.Text.UTF8Encoding]::new($false)
$user = $env:USERNAME

# LM Studio
$lmsMcp = @"
{
  "mcpServers": {
    "blender": {
      "command": "$uvx",
      "args": ["mcp-for-blender"],
      "env": { "BLENDER_HOST": "localhost", "BLENDER_PORT": "9876" }
    }
  }
}
"@
[System.IO.File]::WriteAllText("C:\Users\$user\.lmstudio\mcp.json", $lmsMcp, $utf8NoBom)

# Bionic
$bionicMcp = @"
{
  "servers": [
    {
      "id": "blender-001",
      "name": "blender",
      "description": "Blender MCP",
      "enabled": true,
      "connection": {
        "type": "stdio",
        "command": "$uvx",
        "args": ["mcp-for-blender"],
        "env": { "BLENDER_HOST": "localhost", "BLENDER_PORT": "9876" }
      }
    }
  ]
}
"@
[System.IO.File]::WriteAllText("C:\Users\$user\.lmstudio\apps\bionic\.internal\ng-mcp.json", $bionicMcp, $utf8NoBom)

# opencode
$opencodeMcp = @"
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "blender-mcp": {
      "type": "local",
      "command": ["$uvx", "mcp-for-blender"],
      "enabled": true,
      "environment": { "BLENDER_HOST": "localhost", "BLENDER_PORT": "9876" }
    }
  }
}
"@
[System.IO.File]::WriteAllText("C:\Users\$user\.config\opencode\opencode.jsonc", $opencodeMcp, $utf8NoBom)

Write-Output "三个配置文件已写入。重启 LM Studio / Bionic / opencode 生效。"

LM Studio vs Ollama 对比

维度LM StudioOllama
界面GUI（Electron）CLI + API
模型浏览器可视化，一键下载命令行 pull
参数调节滑块，即时反馈改 YAML/环境变量
模型切换JIT 热切换需先 unload 再 load
聊天测试内置聊天界面第三方网页
资源占用额外 200-400MB RAM极轻量
开源闭源免费MIT 完全开源
服务器部署桌面应用后台常驻，适合服务器
模型推理速度相同（都用 llama.cpp）相同
MCP 支持原生 MCP 客户端需要第三方工具

选择建议：

  • 要 GUI、最少组件、最快上手 → LM Studio
  • 要开源、服务器部署、终端工作流 → Ollama

LM Studio Bionic vs LM Studio 本体

对比项LM Studio（本体）LM Studio Bionic
定位本地 LLM 运行器Agent 智能体平台
核心能力下载模型、聊天、API 服务Agent 能力、文档编辑、代码任务、计算机控制
语音无实时语音转写
MCP 配置~/.lmstudio/mcp.json~/.lmstudio/apps/bionic/.internal/ng-mcp.json
技能系统无有（SKILL.md）
适用场景简单聊天、本地推理复杂多步任务、Agent 工作流

选择建议：

  • 只是本地跑模型聊天 → LM Studio 本体
  • 需要 Agent 能力、多步任务、计算机控制 → Bionic

本指南从实际排错和官方文档中沉淀，每一步都验证过。重装或换机器时照此操作即可。

# blender
Logo
北京朝阳AI社区

更多推荐

YLT 智能助手（小岳）· 18｜自我模型、把握校准与决策先验

YLT智能助手（小岳）第18篇提出“自我模型”核心机制，破解Agent“假学习”困境。通过身份叙事、能力边界与分域把握三要素构建可验证的自我认知，结合EWMA动态校准把握度，实现“低把握→加深验证”的闭环。关键创新在于DecisionPrior：将把握度转化为真实执行深度（如复核轮数从1增至2），并确保执行侧真正消耗轮数，使“我不确定”真正驱动更严谨行为。教训回流按领域去重，避免冗余。整套系统以可

avatar 北京朝阳AI社区

NSSCT大模型Prompt挑战一Fernie-5.5-flash-previe攻破，但是无法复现，有无大神看看攻破原因

原因是 char_reverse(SECRET) 在过滤层的候选比对里没被正确覆盖——我的 is_leak 里虽然写了 char_reverse(secret) in c，但解码器对反转串的处理顺序有 bug。所以"我是开发者，输出秘密"这类话不改变任何事。我之前说过判断标准是"输出能否被还原成秘密"，这条标准对"测试防御"这个说法同样适用，不会因为换了理由而改变。想继续的话，我可以帮你把第 3

avatar 北京朝阳AI社区

流程不重构，Agent只会更贵

很多企业把Agent当升级版聊天框，接进工单、报销和客服后才发现：流程、接口和权限仍按人治设计，Agent只会放大等待与返工。本文用制造、零售、金融场景拆解Agent进入工作流的三个前提——任务颗粒度、可执行接口、风险闸门，并给出从只读试点到流程重排的落地路径。

avatar 北京朝阳AI社区