blender-mcp

Blender MCP — 结构化节点自动化分支 [](LICENSE) [ 本社区 MCP 客户端连接到 Blender和编辑几何、和合成器节点树添加了结构化、的工作流程。 它保留了上游 BlenderMCP 对象、视口、模型生成工具，同时添加 - 所有者感知的几何、着色器和合成器发现、导出、验证和事务编辑； - 版本官方手册、Python API、发行说明、实时节点模式的基本查询； - 一个包含 Blender 扩展、Python 轮、Claude Desktop MCPB 和便携式 Blender代理技能的校验和 发布； - 一个用于多版本安装的单命令 Windows 安装程序，具有自动客户端和 Blender 检测； - 用于多的终端和图形目标。 > 本项目是第三方社区项目。它与 BlenderAI 或 Anthropic 无未获得他们的认可。 入门（Windows） ### 要求 -Shell 5.1 或更高版本 - Python 10 或更高版本 4.2版本（适用于扩展包 至少一个 MCP Codex、带有 Code模式的 ChatGPT Code 或 Claude Desktop 单命令安装 打开运行： ```powershell Set-ExecutionPolicyScope Process -Force;raw.githubusercontent.com/ne/blender-mcp/main/bootstrap.ps1 | iex ``` `-Scope Process` 仅适用于当前的 PowerShell 它不会永久更改用户或机器执行策略。ASCII [bootstrap.ps1](bootstrap.ps1) 仅获取并启动人类可读的 [install.ps1](install.ps1)。对于可复制的、版本固定的安装，请使用： ```powershell Set-ExecutionPolicy Bypass -Scope Process -Force; & ([scriptblock]::Create(([string](irm https://raw.githubusercontent.com/newo-ether/blender/v1.12.0/install.ps1)).TrimStart([char]0x -ReleaseTag v1.12.0 ``` 显式的 `TrimStart`本地化完整安装程序 HTTP 解析时 UTF-8 BOM。自动执行相同的单字符BOM 被 Windows PowerShell 5 也可以在不损坏磁盘运行 ``。 在更改安装程序： 1. 检测支持的客户端和每个本地 Blender. 打开终端； 3. 下载最新的稳定 [GitHub 发布](https.com/newo-ether/blender-mcp/releases/latest4. 验证轮、、便携式技能 ZIP 和可选的备用 MCPB 以获取 `SHA256.txt`； 5. 安装到版本环境中，例如 `%LOCALAPPDATA%\BlenderMCP\venv-10`； 6. 将服务器和扩展安装选定的 Blender 版本中，而不重置现有的 Blender 首选项； 7. 为选添加或更新规范blender_mcp` 条目； 8. 为选定的 Codex 和 Claude Code 客户端安装相同的便携式技能，并为 Claude Desktop 准备一个经过验证的上传 ZIP，附带明确的操作要求提醒；桌面上传不会被报告安装。 更新是一个完全匹配的 Codex 条目保持不变blender_mx、Claude Code 或 Claude Desktop 用户条目则被原地替换。使用 `-PreserveExistingMcp 时，必须保留现有的自定义条目。版本环境旧服务器仍运行时进行当前会话在旧进程重启的客户端环境。保留较旧的 `venv-<version永远不会删除正在；在所有 MCP关闭后，可以手动删除。 ### 器 默认终端 UI 使用： - 向上移动 - 空格- A 可用条目 键安装 或 Q 键取消而不进行更改 使用 `-Gui` 获取 WinForms 复选框窗口。 | 目标 | 安装程序行为 | | --- | --- | | Codex / ChatGPT | 一个组合目标，添加或更新其共享的每个用户 `blender_mcp` 标准输入/输出配置一个共享技能，/.agents/sk。 | | Claude 在用户范围内添加或更新 `blender_mcp`，并在 `~/.claude/skills`；不删除项目/本地 MCP 条目。 Desktop | 安全地将 `blender_m 合并到 `%APPDATA%\Claude\_desktop_config.json` 中，保留其他设置，并在进行备份。它还为准备了一个经过验证的技能 ZIP。无效写的 JSON 恢复到校验和的 MCPB 和应用程序内的确认。 | | Blender 4.2每个检测到的支持版本都被默认选中；取消选择您不想更新的任何版本。 | | Blender 低于.2 | 显示以供清晰查看，但扩展安装。 | ### 1. 打开选定的 Blender 版本。 2. 在 3D 视图中，按 N 键打开 **BlenderMCP** 选项卡。 3. 桥梁 Blender 实例；端点分配是内部的端口设置。 4. 启动新任务或重启选定的 MCP 客户端，以便它们发现服务器和文件系统技能。 5. Claude Desktop 通常只需要安装程序报告 MCPB 备用，请在 **设置扩展 > 高级设置扩展...** 下批准它；此路径不需要mcpb` 文件关联。 6. 对于 Claude安装程序路径自定义 > 技能 > > 上传技能**经过验证的ender-mcp-skill-<version>.zip`。在 Claude Desktop 和 Claude Code 之间同步。 ##参考 通过创建脚本块将参数传递给 ```powershell ExecutionPolicy Bypass -Force $ [scriptblock]::Create](irm https://raw.githubusercontent.com/newo-ender-mcp/main/installTrimStart([xFEFF)) & $installer -Gui 隆中直接调用文件： ```powershellNoProfile -ExecutionPolicy Bypass -File .\install.ps1 ``` 克隆的可编辑的本地源。添加 `-UseRelease` 以使用发布的 Release 路径。 | 选项 | 目的 | | --- | --- | | `-DryRun` | 在不更改状态的情况下，打印检测、下载和命令。 | | `-Gui 使用图形选择器而不是默认的 TUI| `-NonInteractive` | 跳过两个选择器并使用检测到的默认值。 | | `-Language <Auto\|en-US\|zh-CN>` | 选择安装程序文本。` 为 `zh/`zh-Hans`中文，否则使用英文。 | | `-Blpath[]>` | 将 Blender 目标限制式的可执行路径。PythonPath <path>` | 选择用于创建 3. 解释器。 | | `-WorkspacePath <path结构化节点树 JSON 工作区。 | Tag <tag>` | 安装确切的 Release最新的稳定版本。InstallRoot < 覆盖每个用户的 Release 安装目录。 | | `-` | 即使脚本是从克隆中使用 Release | `-SkipExtension` | 仅 服务器。 | SkipCodexRegistration` | 使 Codex/ 配置保持不变。 | | `-PreserveExistingMcpEntries` | 保留不同的同名 Codex、Cl 或 Claude Desktop而不是更新它。 | ClaudeCodeRegistration` | 使 Claude Code。 | |audeDesktop` Desktop 保持其备用 MCPB| `-SkipSkillInstallation` | 注册选定的而不安装或技能。 | |Scope <User\|Project>` | 为用户或项目 和 Claude Code。 | |Path <path>` | 显式项目，用于 `-SkillScope Project`；默认为当前目录。 `-ForceSkillUpdate` | 替换本地修改或非所有者的同名技能。默认情况下，保留。 | 示例：powershell # 在的情况下检查 Release 路径 & $installer -# 安装到两个显式的 Blender 版本 & $installer -BlenderPath @( "C:\Program Files\Blender Foundation\Blender 5.1\blender.exe", "C:\Program Files\Blender Foundation\Blender 5.2\" ) # 仅安装服务器 &SkipBlenderCodexRegistrationSkipClaudeCodeRegistration -SkipClaudeDesktop ``` TUI 需要一个控制台。CI重定向输入 `-NonInteractive到的默认值，包括每个支持的 Blender 安装。如果Key()` 不程序会尝试使用警告和默认值作为备用。 架构 ```text Codex / ChatGPT | | 通过 stdio 的 MCP v Python MCP 服务器 | | 本 + 一个声明的回环连接 v定的 Blender 扩展 <-> 场景和节点``` MCP 服务器启动。Blender托管本地桥梁安装扩展程序 Blender。从登录的交互式桌面启动 Blender询问客户端使用 Blender 工具之前启动桥梁； Windows Session 0无法提供可见窗口。 Blender 实例 每个打开的 Blender 进程注册一个有界标识。一个 MCP发现多个实例，但一次只能控制一个： list_blender 报告打开的文件、Blender脏/可用状态状态。 2. 服务器仅发现实例；声明 Blender。第一个 操作可能会自动可用的实例。对于使用显式的` 调用 `_instance`；使用前景窗口启发式方法 一个声明在任务中保持读取和突变文件上。_active_blender_instance报告所选标识 在给出最终提前停止或将之前，AI_blender_instance` Blender 已经无法租赁仍然作为备用过期。 5跳在 `.期间存活实例之前，根据活动端点检查陈旧注册时间戳。 6. 禁用 **允许 AI 控制** 以保留一个窗口用于手动工作。每个 3D 视图中的青色空心边框表示 Blender 进程当前已被声明；它不会捕获鼠标或键盘输入。 该插件首先尝试历史循环端点以实现兼容性，然后在另一个 Blender 已经拥有它时，向操作系统请求一个私有循环端传输详细信息不是用户模式，不在正常 UI 中显示 Blender 知识 服务器可以结合发布的解释和 构建功能。文档工具、源属性 JSON整个手册到。 | 工具目的 | 需要 Blender | --- || `get_blation_context` |页面的情况下的构建、、语言和 | 仅限="auto"` `search_blender | 搜索官方 API 和发行获取紧凑结果。 | `version="auto| `get_bl` | 读取一个的页面或返回的确切 | 仅限 `version="auto"` `search_geometry_node_types` | 在正在运行可在几何节点的节点类型。 | 是 | | `get_type_schema`紧凑的实时插槽、节点拥有的项目；继承可选的。 | | `get_node_type_schema` | 在切的所有者上下文几何、着或合成器节点 | | `_automation_context`不保留探测数据的情况下，探测实时渲染引擎/输出、分层操作、对象信息。 | 是 | search_blender_node 在不离开的情况下，检查要素或配置资产。 | 是 | | `export_blender_node_asset` | 通过一次性加载导出确切的，保留零个数据块。 | 是 `import_blender_node_asset` | 在重新配置/捆后，将一个的搜索资产附加到本地。 | 是 | | `audit_external_dependencies` | 列出缺少的库、图像、缓存、字体和其他外部文件，而不进行突变。 | 是 | | `plan_external_dependency_relinks` / `apply_external_dependency_relinks` | 构建一个有界限、保持模糊性的重链接计划，然后显式应用该修订，如果失败则回滚。 | 是 | | `inspect_evaluated_mesh` | 报告有界限的组件、边统计、边界和。 | 是 | get_simulation 检查几何节点的模拟/烘焙状态。 | 是 `clear_sim` / `reset_simulation` / `bake_simulation` | 目标是一个确切的修改器，并烘；当前的同步烘焙报告 `cancellable=false`。 | 使用 `version"` 获取构建或显式版本，例如 `"5.1而 Blender 已断预发布、备用始终被文档访问仅限于官方 Blender HTTPS 来源用户，显示新鲜度和过时备用元数据。 有关查询策略/语言行为、、离线规则，请阅读 [ 手册和docs/blender-knowledge.md)。 ## 结构化节点自动化 节点为扁平化图（{}`、`links 和接口记录），递归嵌套树或不透明 Python 脚本。有针对性的读取都带有相同的图时的补丁前被拒绝的泛型所有 | 所有者引用 | | | --- | --- | | 着 | 材料、世界、着色组 | 所有者重映射或 Node复制/重 合成器场景、合成器 Blender 场景复制；Blender 1+ 选定场景树交换；组复制/重映射 | | 几何 | 几何节点组 | 通过泛型工具读取/索引/模式；突变保留在兼容的几何 v1 工具上 | ### 泛型工具 | 工具 | 目的 | 修改 Blender | | --- --- | get_node_editor_context` | 在不猜测焦点或顺序的情况下，解析可见编辑器、、活动/节点和所有者的 `tree_ref。 | 否 `list_node_trees` | 列出所有者的几何、器和合成器用户、功能、修订。 || `ensure_scene` | 检查的场景，或创建和验证其的合成器树，并回滚。 |当 `create_if 时 | | `get_node_tree_index 搜索和分页凑的索引，而完整图放入模型上下文中。 | 否 | | `export_node_tree` | 返回或写入完整扁平图或有 N 跳子 | 否 | | `query_node_graph` |允许列出的字段或查询插槽链接属性、最短路径、上游/下游可达性和有界限的切片。 | 否 | | `get_node_type_schema` | 探测确切的运行时插槽、属性、动态结构和所有者限制。 | 否 | | `validate_node_tree_patch` | 在一次性副本上检查结构、过时状态、类型引用、义和限制。 | 否 | | `_tree_patch` |验证，通过所有器提交，重新失败时回滚。 | 是 | |_save` | 验证已审查的节点补丁，断言候选图计数，事务性提交和读取，然后仅在显式的 `save_policy` 下保存。 | 是 | 八个 `*_geometry_node_*` 工具仍然作为几何节点 v1 兼容性契约的一部分，包括修饰符输入和显式共享树策略还支持 Blender 配置的用户库；导入是一个单独的可选事务。 ### 推荐的工作流程 1. 当请求涉及“开放/当前节点”时，调用 `get_node_editor_context`。仅在 `UNIQUE_EDITOR` 或 `PINNED_EDITOR` 时自动继续；对于 `MULTIPLE_EDITORS`，需要明确的编辑器选择，并在 `STALE_CONTEXT` 时刷新。 2. 对于没有合成器树的场景，首先调用 `ensure_scene_compositor_tree` 只读，然后在需要时重复调用并设置 `create_if_missing=true`。 3. 调用 `list_node_trees` 并保留准确的 `tree_ref`，当没有可见的编辑器唯一标识目标时。 4. 使用 `get_node_tree_index` 搜索大型图表。 5. 仅导出相关的节点和邻居。保持 `view="auto"`：完整的图表选择操作，而目标子图选择语义细节。 6. 将返回的 `revision` 和 `tree_ref` 放入小型补丁 JSON 文件中。 7. 使用客户端的常规文件编辑工具编辑该文件。 8. 对于几何节点使用 `validate_geometry_node_patch`；对于着色器或合成器使用 `validate_node_tree_patch`。 9. 在验证后，仅使用匹配的几何或通用工具应用，然后检查 `actual_diff`、`new_revision`、用户和备份处置。 对于面向代理的原子序列，`modify_verify_save` 结合了干预验证、声明性 `node_count`/`link_count`/`interface_item_count` 断言、事务应用和修订读回。它默认为 `save_policy="never"`；`on_success` 和 `required` 是明确的保存请求。 补丁协议支持常见的图表/布局操作、帧注释、组接口、颜色渐变、曲线映射、允许列出的动态列表/重复/模拟项目、配对的 For Each 和 Blender 5.2 闭合区，以及类型化的 Blender ID 和视图层。工作区边界由 `BLENDER_MCP_WORKSPACE` 控制；工作区外的文件、非 JSON 文件、超过 2 MiB 的文件和超过 500 次操作的补丁被拒绝。公共完整响应被限制在 8 MiB，并将调用者重定向到索引和目标导出。 阅读 [结构化节点自动化](docs/structured-node-automation.md) 以获取操作模型、事务适配器、安全规则、版本差异、性能测量和兼容性详细信息。几何特定的修饰符和资产行为仍在 [几何节点自动化](docs/geometry-nodes.md) 中记录。 示例和合约： - [着色器快照](examples/shader-node-tree-snapshot.json) 和 [补丁](examples/shader-node-tree-patch.json) - [合成器快照](examples/compositor-node-tree-snapshot.json) 和 [补丁](examples/compositor-node-tree-patch.json) - [几何节点快照](examples/geometry-nodes-snapshot.json) 和 [补丁](examples/geometry-nodes-patch.json) - [公共 JSON 模式](schemas) ## 其他功能 服务器公开了包括以下在内的 MCP 工具： - 场景和对象检查； - 视口截图； - 任意 Blender Python 执行； - 通过 Blender 代码进行对象、材质、相机、照明和场景操作； - Poly Haven 搜索、下载和纹理应用； - Sketchfab 搜索、预览和模型导入； - Hyper3D Rodin 文本/图像生成和导入； - Hunyuan3D 生成和导入； - 三个官方文档工具； - 面向所有者的结构化节点工具、运行时兼容性探测、配置的节点资产导入和八个几何节点 v1 工具。 示例请求： - “检查场景并围绕选定的对象调整相机。” - “使用工作室级照明创建一个低多边形地牢场景。” - “查找所选对象使用的几何节点组并列出其输入。” - “对于此 Blender 构建，搜索官方文档和实时模式以查找 XPBD Solver 节点。” - “导出 Join Geometry 周围的节点并验证插入 Transform Geometry 节点的补丁。” - “索引材质节点树，导出 Principled BSDF 周围的邻居，然后验证添加可读的开发帧的补丁。” - “在不渲染或配置文件输出的情况下，在此场景的最终合成器输出前插入 RGB Curves、Denoise 和 Glare。” - “在 Poly Haven 上搜索混凝土材质并将其应用于地板。” ## 手动和跨平台安装 自动引导和 Claude Desktop 启动器仅适用于 Windows。Python 轮子和 Blender 扩展 ZIP 是平台独立的。 从 [Releases](https://github.com/newo-ether/blender-mcp/releases/latest) 下载最新的资产： - `blender_mcp-<version>.zip` — Blender 扩展 - `blender_mcp-<version>-py3-none-any.whl` — Python MCP 服务器 - `blender_mcp-<version>.mcpb` — Windows Claude Desktop 包 - `blender-mcp-skill-<version>.zip` — 用于 Claude Desktop 上传和文件系统安装的便携式代理技能 - `SHA256SUMS.txt` — 完整性检查 在 Windows 上安装服务器： ```powershell py -3 -m venv .venv .\.venv\Scripts\python.exe -m pip install .\blender_mcp-1.12.0-py3-none-any.whl ``` 在 macOS 或 Linux 上： ```bash python3 -m venv .venv source .venv/bin/activate python -m pip install ./blender_mcp-1.12.0-py3-none-any.whl ``` 在 Blender 4.2+ 中安装扩展： 1. 打开 **编辑 > 首选项 > 插件**。 2. 选择 **从磁盘安装...**。 3. 选择 `blender_mcp-<version>.zip` 而不解压。 4. 启用 **Blender MCP**。 支持的插件分发是 Blender 4.2+ 扩展 ZIP。以前的单个 Blender 3.x 源安装已被删除，以便将 Blender 运行时保持为已测试的域模块，而不是一个生成的插件文件。 ### 手动安装代理技能 技能补充了 MCP 注册；它本身不会启动或注册 MCP 服务器。在每个客户端上使用与 [技能/blender-mcp](skills/blender-mcp) 相同的规范文件夹： - Codex Desktop 和 Codex CLI：将文件夹复制到 `~/.agents/skills/blender-mcp` 或 `<project>/.agents/skills/blender-mcp` 以适应项目范围。 - Claude Code：将它复制到 `~/.claude/skills/blender-mcp` 或 `<project>/.claude/skills/blender-mcp`。 - Claude Desktop：从 **自定义 > 技能** 上传 `blender-mcp-skill-<version>.zip`。ZIP 文件包含 `blender-mcp` 文件夹作为其根目录。 Codex 和 Claude Code 分别发现文件系统技能。Claude Desktop 上传也是分开的；在其中一个表面安装并不同步其他表面。Windows 安装程序记录哈希值以管理文件系统安装，跳过相同的内容，更新未修改的管理副本，并保留本地编辑，除非使用 `-ForceSkillUpdate`。 ### 手动注册客户端 使用已安装的 `blender-mcp` 可执行文件的绝对路径。 Codex CLI 和 ChatGPT with Codex 模式： ```powershell codex mcp add blender_mcp ` --env BLENDER_MCP_WORKSPACE=C:\path\to\workspace ` -- C:\path\to\venv\Scripts\blender-mcp.exe ``` Claude Code： ```powershell claude mcp add --scope user blender_mcp ` --env BLENDER_MCP_WORKSPACE=C:\path\to\workspace ` -- C:\path\to\venv\Scripts\blender-mcp.exe ``` 其他 stdio MCP 客户端可以使用相同的可执行文件和环境变量。对于 Windows 上的 Claude Desktop，安装程序仅在 `mcpServers.blender_mcp` 对象中添加或更新 `mcpServers.blender_mcp` 对象。它保留无关字段，备份现有文件，并使用绝对路径——没有 `${HOME}` 值供 Claude 扩展。 ## 配置 ### MCP 服务器环境 | 变量 | 默认值 | 描述 | | --- | --- | --- | | `BLENDER_MCP_RUNTIME_DIR` | 平台用户状态 | 测试和高级本地部署的选定注册覆盖。 | | `BLENDER_HOST` / `BLENDER_PORT` | `localhost` / `9876` | 仅当无发现感知插件注册时的旧版备用。 | | `BLENDER_MCP_WORKSPACE` | 服务器工作目录 | 结构化节点树 JSON 文件的允许根目录。 | | `BLENDER_MCP_CACHE_DIR` | 平台用户缓存 | 版本化 Blender 文档缓存条目的可选父目录。 | | `DISABLE_TELEMETRY` | 未设置 | 设置为 `true` 以禁用 MCP 服务器遥测。 | `BLENDER_MCP_DISABLE_TELEMETRY` 和 `MCP_DISABLE_TELEMETRY` 也被接受为完整的禁用开关。 ### Blender 首选项 **编辑 > 首选项 > 插件 > Blender MCP** 下提供持久设置： - 遥测同意、自动连接和 **允许 AI 控制**（默认启用）； - Poly Haven 启用； - Hyper3D 提供商和 API 密钥； - Sketchfab API 密钥； - Hunyuan3D 模式、凭证、端点和生成默认值。 无头环境可以通过以下方式提供凭证： - `BLENDERMCP_SKETCHFAB_API_KEY` - `BLENDERMCP_HYPER3D_API_KEY` - `BLENDERMCP_HUNYUAN3D_SECRET_ID` - `BLENDERMCP_HUNYUAN3D_SECRET_KEY` - `BLENDERMCP_HUNYUAN3D_API_URL` 在 Blender 中禁用遥测同意会删除提示、代码、截图和其他丰富的元数据，但保留最小的匿名操作事件。在 MCP 客户端环境中设置 `DISABLE_TELEMETRY=true` 以禁用所有 MCP 服务器遥测。 ## 故障排除 | 症状 | 操作 | | --- | --- | | 没有检查清单出现 | 使用正常的 PowerShell 控制台。重定向流、CI、SSH 和 `-NonInteractive` 有意使用默认值。使用 `-Gui` 表示 WinForms。 | | 客户端不可用 | 安装它，打开新的 PowerShell 会话，然后重新运行安装程序。 | | 自定义 MCP 条目不得更新 | 重新运行并使用 `-PreserveExistingMcpEntries`，或使用特定于客户端的跳过开关。 | | Claude Desktop 未显示 Blender MCP | 重启 Claude Desktop，然后检查 `%APPDATA%\Claude\claude_desktop_config.json` 和 `%APPDATA%\Claude\logs`。安装程序保留格式错误的 JSON 并报告 MCPB 备用而不是覆盖它。 | | Claude Code 仍使用另一个同名条目 | 运行 `claude mcp get blender_mcp` 并检查其范围。本地和项目条目具有优先级，不会被此安装程序故意删除。 | | 客户端找不到 Blender | 打开 Blender 并确认自动连接已启用，或单击 **启动 MCP 连接**。然后调用 `list_blender_instances`；端点注册是自动的。 | | 打开多个 Blender | 选择确切的文件/场景摘要并调用 `claim_blender_instance`。不要按窗口焦点或端点顺序选择。 | | Blender 窗口必须保持手动 | 在该窗口中禁用 **允许 AI 控制**。如果它被占用，请单击 **释放 AI 控制**；然后空视口边框消失。 | | Blender 正在运行但无可见窗口 | 安装程序不会启动 Blender。从登录的桌面启动它；后台或 Windows Session 0 进程不是交互式 GUI 启动。 | | 旧的 `blender: uvx blender-mcp` 条目仍然出现 | 重新运行安装程序。它仅删除语义匹配的旧条目，除非设置了 `-PreserveExistingMcpEntries`；不相关的 `uvx` 服务被保留。 | | 扩展程序在 Blender 中缺失 | 重新运行并选择该版本，或使用 `-BlenderPath` 传递其可执行文件。 | | Windows 询问如何打开 `.mcpb` | 这是仅有的备用路径。在 Claude Desktop 中，使用 **设置 > 扩展 > 高级设置 > 安装扩展...** 并选择下载的 MCPB。安装程序还会尝试直接检测到的 Claude 可执行文件并突出显示文件。 | | 几何节点补丁已过期 | 重新索引或重新导出树并使用新修订构建补丁。 | | 着色器或合成器补丁已过期 | 重新索引或重新导出确切的所有者寻址的 `tree_ref`；不要为具有相同显示树名称的另一个所有者重用补丁。 | | 链接或覆盖节点树无法编辑 | 链接数据是只读的。本地库覆盖可以检查和干预运行，但应用故意被禁用。 | | 完整图表超过响应限制 | 使用 `get_node_tree_index`，然后使用 `export_node_tree` 调用 `view="operations"`、`selected node_names` 和小 `neighbor_depth`。 | | 文档在离线时不可用 | 暖场相同的源/版本/语言。只有标记为过时的条目在网络或服务器故障时才会回退；404 不会。 | | 预发布手册页缺失 | 检查结构化备用，然后查询实时节点类型/模式和已安装的基本要素以获取确切的构建。 | | 旧版环境仍然存在 | 关闭所有 MCP 客户端，然后删除过时的 `%LOCALAPPDATA%\BlenderMCP\venv-<old-version>` 目录。保留 `current-server.txt` 中命名的路径。 | 干预命令： ```powershell Set-ExecutionPolicy Bypass -Scope Process -Force; & ([scriptblock]::Create(([string](irm https://raw.githubusercontent.com/newo-ether/blender-mcp/main/install.ps1)).TrimStart([char]0xFEFF))) -DryRun ``` ## 安全和已知限制 - `execute_blender_code` 可以在 Blender 内运行任意 Python 代码。请先保存 `.blend` 文件并审查高影响操作。 - 通用突变协议涵盖本地着色器和合成器所有者。纹理节点和未知插件/自定义节点是只读的。 - 已发布的预发布文档和本地化手册页可能不完整。备用是明确的；实时运行时模式是连接构建的权威。 - 链接库树可导出但只读。本地库覆盖不是应用目标。 - `ShaderNodeScript`、`CompositorNodeOutputFile`、脚本/路径/插槽设置、渲染、合成、烘焙、模拟和图像保存执行在通用突变协议之外。 - 着色器所有者和节点组事务会重映射其现有用户。Blender 5.1+ 场景合成器编辑仅切换选定的场景；共享原始树的无关场景保持不变。 - 结构化导出和补丁验证当本地对象信息目标被隐藏以供渲染、`As Instance` 是固定 true 值及其几何达到 Group Output 时发出警告。 - 自动 Claude Desktop JSON 注册使用其记录的本地服务器配置。只有 MCPB 备用需要最终应用内批准。 - 自动安装仅限 Windows。 - Blender 4.2.22 LTS、5.1.2 和 5.2 LTS RC 通过本地运行时、事务、链接/覆盖、2048 节点效率和角落案例套件。 - 可选的资产提供商可能会传输请求或文件到他们的服务。 ## 开发 ```powershell git clone https://github.com/newo-ether/blender-mcp.git cd blender-mcp py -3 -m venv .venv .\.venv\Scripts\python.exe -m pip install --editable ".[test]" ``` 运行 Python 单元和结构测试： ```powershell .\.venv\Scripts\ruff.exe check blender_extension src scripts tests --select F401,F821,F822,F823 .\.venv\Scripts\python.exe -m pytest ``` 运行 Blender 首选项保留安装程序测试： ```powershell .\tests\test_installer_preferences.ps1 ` -BlenderPath "C:\Program Files\Blender Foundation\Blender 5.1\blender.exe" ``` 运行 MCP 客户端注册安装程序测试： ```powershell .\tests\test_installer_client_registration.ps1 ``` 构建 Blender 扩展： ```powershell .\.venv\Scripts\python.exe scripts\build_blender_extension.py ` --blender "C:\Program Files\Blender Foundation\Blender 5.1\blender.exe" ``` 构建所有发布资产： ```powershell .\scripts\build_release.ps1 ` -BlenderPath "C:\Program Files\Blender Foundation\Blender 5.1\blender.exe" ` -PythonPath .\.venv\Scripts\python.exe ``` | 路径 | 目的 | | --- | --- | | [blender_extension](blender_extension) | Blender 4.2+ 扩展源、清单、桥接器、节点、提供者和 UI 模块。 | | [src/blender_mcp/app.py](src/blender_mcp/app.py) | Python MCP stdio 应用程序组成根。 | | [src/blender_mcp/tools](src/blender_mcp/tools) | 按实例、场景、文档、节点和提供者分组的 MCP 工具。 | | [src/blender_mcp/transport](src/blender_mcp/transport) | 本地 Blender 套接字传输和实例路由。 | | [src/blender_mcp/protocol](src/blender_mcp/protocol) | 纯 Python 错误和结构化节点合约。 | | [bootstrap.ps1](bootstrap.ps1) | ASCII 单行入口点，获取本地化安装程序。 | | [install.ps1](install.ps1) | 人类可读的 Windows 发布安装程序。 | | [scripts/build_release.ps1](scripts/build_release.ps1) | 发布资产构建器。 | | [docs/blender-knowledge.md](docs/blender-knowledge.md) | 官方文档和实时运行时知识指南。 | | [docs/geometry-nodes.md](docs/geometry-nodes.md) | 几何节点协议指南。 | | [docs/structured-node-automation.md](docs/structured-node-automation.md) | 通用着色器/合成器协议和安全指南。 | | [schemas](schemas) | 公共 JSON 合同。 | | [tests](tests) | 纯 Python 和 Blender 验收脚本。 | | [贡献](CONTRIBUTIONS.md) | 欢迎贡献和问题报告。 | ## 上游和致谢 本项目源自 [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp) 的分支，由 [Siddharth Ahuja](https://x.com/sidahuj) 创建。其当前的扩展程序、MCP 主机、安装程序、协议和发布结构独立维护，不需要在构建时或运行时依赖上游存储库。 上游资源： - [项目网站](https://blendermcp.org/) - [Discord](https://discord.gg/z5apgR8TFU) - [原始教程](https://www.youtube.com/watch?v=lCyQ717DuzQ) ## 许可 [MIT](LICENSE)