ViperMesh for Blender

---

Blender 版 ViperMesh 是一款免费的开源 Blender MCP 服务和插件，可让兼容的 AI 助手在 Blender 场景中工作。它面向 Blender 艺术家、爱好者 和游戏创作者，帮助他们制作和编辑 3D 场景，而不是开展另一个编码 项目。

目标：更快地借助 AI 工作、更少消耗 AI 令牌，并获得经过更好检查的结果。 你的助手可以直接使用现成的 Blender 操作，而不必为许多常见编辑任务编写新的 Python 代码。你可以继续在 Blender 中工作，并决定希望助手提供哪些帮助。

观看概览

观看 72 秒视频 或下载 MP4。 了解 AI 客户端如何使用现成的 Blender 操作、减少生成的代码为何会有所帮助， 以及如何开始使用。这是一段无声的图解概览视频，并非计时基准测试录屏。GitHub 的 README 提供可播放视频的链接。

为什么选择 Blender 版 ViperMesh？

你关注的方面	ViperMesh 如何提供帮助
减少 AI 用量	可复用的操作减少了助手为已支持任务生成的 Blender 代码。
缩短等待时间	连接会保持开启，相关操作可以一起运行，无需为每个步骤重复设置。
更好地检查场景	内置检查可帮助发现物体悬空、朝向错误和间隙问题；助手可以检查图像并修复错误。
让助手更容易上手	可发现的工具和简明指南会说明有哪些操作可用以及如何使用。
留有自定义空间	如果你的需求超出现成工具的支持范围，助手仍可编写 Python 代码。

AI 令牌是模型读取和生成的文本单位。生成更少的代码 可以减少 AI 用量，但令牌总量、成本和耗时也取决于你的模型 和任务。场景检查有助于确保正确性，但不能保证结果 美观或毫无错误。

一个参考图，两种 Blender 工作流

使用 ViperMesh Blender MCP 测试框架和可用资源进行的一次历史图像重建测试。仅重新标注了中间的标题；参考图和两个场景截图均未更改。这只是一个示例，并不保证每次都能得到相同结果。公开版插件不附带私有 Studio 资源库。

阅读 Blender MCP 案例研究，第一部分 | 查看完整尺寸对比图 | 图像完整性记录

它能帮你做什么？

• 在场景中创建、移动、复制和排列对象。
• 平滑边缘、调整材质、设置摄像机和更改灯光。
• 检查对象是否放置在支撑物上，或是否留有足够空间。
• 协助清理网格、重新拓扑、准备 UV、绑定骨骼和设置权重。
• 处理动画设置、准备导出并检查结果。

例如，你可以这样向助手提出请求：

将篮子移到桌子右侧下方，不要与桌腿相交。

平滑这件家具的锐利边缘，同时保持其整体形状。

检查此场景中是否有未受支撑的对象，然后告诉我需要修复什么。

这些是请求示例，不是预先制作的场景模板。对于工具支持的操作，你无需自行编写 Blender Python。

它与原版 BlenderMCP 有何不同？

ViperMesh 基于 Siddharth Ahuja 的原版 BlenderMCP 项目构建，该项目现名为 MCP for Blender。两者的主要区别在于，ViperMesh 侧重于提供一系列现成的编辑操作、可重复使用的工作流和场景检查，而不是依赖新生成的 Python 来完成常见编辑。

两个项目都可以检查场景并运行自定义 Python。原版项目还提供资源和生成集成。ViperMesh 的目标是让日常场景操作更节省 token、速度更快、助手更容易使用，也更便于验证。这并不意味着它在所有任务中都表现更好，也不表示公开连接器包含 ViperMesh Studio 的所有功能。

网站安装指南 · Harness Library 条目

要求

• Blender 5.2（当前测试的目标版本）
• Node.js 20 或更高版本
• 支持 stdio 服务的 MCP 兼容客户端

MCP 是 Model Context Protocol（模型上下文协议）的简称，这是一种连接标准，可让 AI 助手使用其他应用中的工具。你需要使用支持此类连接的 AI 应用；仅安装插件并不会为 Blender 添加 AI 模型。

安装

1. 安装 Blender 插件

从最新版本下载带版本号的插件 .py 或插件 .zip。在 Blender 中：

1. 打开 Edit > Preferences > Add-ons。
2. 选择 Install from Disk，然后选中下载的 Python 文件。
3. 启用 ViperMesh for Blender。
4. 打开 3D 视口侧栏，选择 ViperMesh，然后点击 Start Local Bridge。

整个 Agent 会话期间，请保持 Bridge 运行。

2. 安装 MCP 服务

打包选项： 下载 v1.3.0 MCPB bundle， 并将其导入支持本地 MCPB 扩展的客户端。它包含 Node 服务及其依赖项，因此无需克隆或构建此仓库。仍需安装 Node.js，并单独启用 Blender 插件。

此连接器也已列在 Smithery 和 官方 MCP Registry 中。 这些列表分发的是本地连接器，而非托管的 Blender 服务。 校验和、手动解压选项及当前验证限制，请参阅分发和 bundle 设置。

源码选项： npm 包发布前，请克隆并构建：

git clone https://github.com/OpenRootdev/vipermesh-blender.git
cd vipermesh-blender
npm install
npm run build

3. 连接 AI 助手

使用 MCPB 导入时，客户端会从 bundle 中读取启动配置。使用源码选项时，请通过绝对路径指定构建后的入口点：

{
  "mcpServers": {
    "vipermesh-blender": {
      "command": "node",
      "args": [
        "C:/absolute/path/to/vipermesh-blender/dist/public-portable-blender-mcp.js"
      ]
    }
  }
}

通过 MCP 客户端运行此命令一次即可。每次执行 Blender 操作时都不要再次调用 npm、npx 或 tsx。Codex、使用 JSON 配置的客户端、兼容性及可选的 Docker MCP Toolkit 方式，请参阅 MCP 客户端设置。

技术详情

以下章节介绍如何设置或开发 AI 连接。Blender 用户可以从安装步骤和上方的示例请求开始。

连接模型

MCP-compatible AI assistant
        |
        | stdio, one long-lived process
        v
ViperMesh MCP server
        |
        | serialized loopback connection
        v
ViperMesh Blender addon (127.0.0.1:9876)
        |
        v
Blender scene

MCP 服务不会打开网络监听器。Blender 插件默认监听回环地址，并在 ViperMesh 侧边栏中显示 已停止、就绪、Agent 已连接 或 错误。

首次 Agent 调用

1. 调用 bootstrap_vipermesh_session。
2. 使用 call_blender_tool(name="get_scene_info") 检查场景。
3. 使用 search_3d_guidance 搜索任务指南。
4. 使用 list_blender_tools 发现仅与当前任务相关的功能。
5. 构建、检查并修复，然后完成并保存。

公开 MCP 接口包括：

• bootstrap_vipermesh_session
• check_blender_connection
• list_blender_tools
• call_blender_tool
• call_blender_tool_batch
• run_blender_scene_stage
• get_blender_agent_context
• search_3d_guidance
• get_3d_guidance_document

有关请求格式、批处理规则、分阶段工作流、本地工具技能和故障排除，请阅读完整连接器手册。仓库还附带可安装的 using-vipermesh-blender Agent 技能。

安全

此连接器适用于可信的本地工作站。execute_code 可以在 Blender 中运行任意 Python 代码。仅连接可信的 MCP 客户端，将桥接保持在回环地址上，并审查影响重大或具有破坏性的操作。

有关信任边界和私密漏洞报告流程，请参阅 SECURITY.md。

公开连接器范围

此仓库包含开源 Blender 插件、便携式 MCP 服务、便携式公开工具技能和连接器测试。它不包含 ViperMesh 应用、身份验证、计费、私有提示词、私有 RAG 数据、云端模型路由、私有资产、原始基准测试跟踪记录或私有评估数据集。图示对比是单独提供的公开证据，并非随附的资产库。

此连接器不捆绑商业 3D 生成服务提供商。之后可以通过与提供商无关的身份验证服务添加神经生成，而无需在 Blender 中嵌入第三方凭据。

常见问题

我需要付费的 ViperMesh 账户吗？

不需要。公开插件和本地连接可免费使用，无需 ViperMesh 账户。你的 AI 应用或模型提供商可能会另行收费。插件不提供免费的 AI 模型访问权限。

我需要会编程吗？

对于本文涵盖的 Blender 编辑操作，你无需编写 Python。初始设置仍需安装插件并连接兼容的 AI 应用。对于支持 MCPB 的客户端，请使用 MCPB bundle；也可以使用提供的命令从源代码构建。由于还需单独启用 Blender bridge 并配置客户端，因此并非所有环境都能一键安装。

ViperMesh 会取代 execute_code 吗？

不会。它通过提供结构化操作来减少不必要的 Blender Python 代码生成，但仍保留 execute_code，用于自定义几何体、程序化效果、特殊节点图以及尚未覆盖的工作流。

为什么 MCP 进程必须保持运行？

该进程会保留与 Blender 的序列化连接。每次调用都重新启动进程，会带来不必要的启动、传输和 Agent 工具开销。

是否需要 Docker？

不需要。本地支持 stdio 的 MCP 客户端会直接启动 Node 服务。Docker MCP Toolkit 是一种可选的打包和网关方案；目前还不是受支持的 ViperMesh 安装方式，因为主机与 Blender 之间的环回连接仍需跨平台验证。

公共连接器需要 ViperMesh 云身份验证吗？

不需要。公共插件和本地 MCP 服务无需 ViperMesh 身份验证即可运行。未来的托管模型和专有编排属于独立的产品功能。

它可以使用已安装的 Blender 插件吗？

连接器可以检查已安装的插件，并支持可信的本地自动化。对于未知插件操作，在将其开放为可调用的 Agent 功能之前，应先进行审查。

开发

npm install
npm run check
python -m py_compile addon/vipermesh-addon.py

提交拉取请求前，请参阅 CONTRIBUTING.md。

许可证和署名

ViperMesh for Blender 基于 MIT License 发布。其中包含源自 Siddharth Ahuja 开发的 BlenderMCP 的内容。署名和商标声明请参阅 NOTICE.md。