Blender AI MCP

MCP设计创作

提供方 PatrykIti

设计创作 stdio · 本地进程 无需鉴权 社区 / 第三方 Claude
查看接入方式

一个为Blender设计的MCP服务器,通过稳定的工具API让AI模型如Claude、ChatGPT等控制Blender,提供安全、可靠的建模工作流程。

一句话选型结论

按资料字段整理

Blender AI MCP 属于设计创作类 MCP 服务器,stdio · 本地进程,无需鉴权,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类设计创作 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 24 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

设计创作
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

AI建模Python本地部署Blender插件自动化工具3D建模BlenderAI控制

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
docker run -i --rm \

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Docker,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
出图与素材

生成配图、图标与素材。

设计稿处理

读取设计稿、批量改尺寸或导出。

内容生成

按主题生成文案与视觉草稿。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在设计创作场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Blender AI MCP当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Cursor Talk To Figma MCP Da1c7911 40 未标注 未标注 无 2026-05-17
Blender MCP 17 stdio · 本地进程 本地部署 有 2026-05-18
Nova Canvas MCP Server 2 stdio · 本地进程 本地部署 有 2026-05-17
Figma Context MCP 3aaa8d28 未标注 未标注 支持远程部署 无 2026-05-17
kreuzberg 未标注 stdio · 本地进程 本地部署 有 2026-04-12

服务器档案

设计创作
字段来自项目仓库与公开索引,中文说明由本站标注
提供方PatrykIti上游标注的维护方 PatrykIti
分类设计创作本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Docker本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

40.2 KB
来自项目仓库与上游目录的原文,未做删改

搅拌机ai-mcp

Blender的生产型MCP服务器。

blender-ai-mcp 让Claude、ChatGPT、Codex和其他MCP客户端通过稳定的工具API控制Blender,而不是专门生成Python。其结果是为真实的建模工作提供了一个更安全、更小、更可靠的表面:目标优先的路由、精心策划的公共工具、确定性检查和不依赖于猜测的验证。

为什么存在

大多数“AI+Blender”设置仍然要求模型编写原始代码 bpy 脚本。这恰好打破了生产工作变得有趣的地方:

  1. Blender API在不同版本之间漂移。
  2. 当活动对象、模式或选择错误时,上下文相关运算符会失败。
  3. 当出现问题时,原始脚本会给出微弱的反馈。
  4. 愿景可以描述结果,但不能被信任为最终权威。

blender-ai-mcp 采取相反的方法:将Blender控件视为产品表面,而不是代码生成噱头。

为什么使用MCP服务器而不是原始Python

  • 稳定的合约胜过脚本合成。 该模型调用具有经过验证的参数的工具,而不是即兴编写Blender代码。
  • 目标优先编排。 正常的指导课程从开始 router_set_goal(...),因此系统在开始调用低级操作之前就知道模型试图构建什么。
  • 公共面积小。 默认值 llm-guided profile公开了一个微小的、搜索优先的引导层,而不是用整个运行时清单淹没模型。
  • 真相第一验证。 检查、测量和断言工具确定Blender中的实际情况。
  • 安全执行边界。 Blender插件在Blender的主线程上执行操作,而MCP服务器处理路由、验证、发现和结构化响应。

产品法

商业理念在 TASK-113 很简单:

  • 原子工具 是实现的基础。它们保持小而精确,并且大多隐藏在正常的公共表面之外。
  • 宏工具 是有意义任务大小工作的首选LLM面层。
  • 工作流工具 是有界的多步骤流程工具,具有明确的报告,而不是开放式的“做任何事情”端点。
  • 目标优先编排 使会话固定在一个积极的意图上,而不是让模型在每次转弯时都重新发现上下文。
  • 视觉辅助解读,而确定性测量和断言提供了最终的真值层。
  • 可插拔的视觉运行时间 现在涵盖了本地MLX加上外部OpenRouter和Google AI Studio/GGemini提供程序路径,以及用于提示/模式/解析器行为的特定于模型系列的外部契约配置文件。

这就是将该项目从“通过MCP公开的Blender工具”转变为用于建模管道的可用AI控制产品的原因。

LLM引导公共表面

llm-guided 是默认的面向生产的曲面。它故意设计得很小,搜索优先,并围绕目标感知会话进行设计。

正常引导流量:

  1. router_set_goal(...)
  2. browse_workflows, search_tools,或 call_tool
  3. 使用分组/公共工具,如 check_scene, inspect_scene,或 configure_scene
  4. 通过检查加验证 scene_measure_* 和 scene_assert_*

提示规则:

  • 使用prompt库资产 _docs/_PROMPTS/README.md 作为规范的指导操作说明
  • 当客户流失时,预先添加 guided_session_start 作为通用搜索第一稳定器
  • 如果工具在当前表面/相位上尚未直接可见,请使用 search_tools(...) 之前 call_tool(...)

当有界建模意图匹配时,默认的公共工作层应该是宏层:

  • macro_cutout_recess 用于凹槽、开口和切割器驱动的切口
  • macro_relative_layout 用于对齐/放置/接触间隙零件布局
  • macro_attach_part_to_surface 用于将一个零件放置在另一个物体的表面/主体上
  • macro_align_part_with_contact 对于几乎合身的鞋子,只需轻轻推一下即可修复
  • macro_place_symmetry_pair 用于在显式镜像平面周围放置/校正镜像对
  • macro_place_supported_pair 用于在一个共享支撑表面上放置/校正镜像对
  • macro_cleanup_part_intersections 无需自由碰撞求解的有界成对重叠清理
  • macro_adjust_relative_proportion 用于相关对象之间的有界比率修复
  • macro_adjust_segment_chain_arc 用于有序分段链上的有界弧调整
  • macro_finish_form 用于预设驱动斜面/细分/固化精加工
  • reference_images 有界视觉比较前的目标范围参考摄入量
  • reference_guided_creature_build 作为分阶段通用生物工作的本地即时资产 llm-guided
  • recommended_prompts 现在可以通过使用主动目标/会话上下文将面向生物的引导会话引导到提示路径
  • guided_reference_readiness 上 router_set_goal, router_get_status,并分阶段比较/迭代有效载荷,以便客户端可以查看参考驱动的阶段工作是否真正准备就绪
  • reference_compare_stage_checkpoint 用于在手动迭代工作期间与附加参考进行确定性多视图阶段比较
  • reference_iterate_stage_checkpoint 对于一个会话感知的分阶段校正循环,它会记住之前的焦点,当相同的校正重复时,可以升级为检查/验证,现在可以针对一个对象、多个对象、一个集合或完整的组装轮廓
  • 阶段比较/迭代现在也暴露了确定性 silhouette_analysis 类型化指标 action_hints,仅供咨询 part_segmentation 除非明确启用单独的sidecar,否则占位符将保持禁用状态
  • scene_scope_graph 对于一个带有锚/核心/附件角色提示的显式只读结构范围工件
  • scene_relation_graph 对于从当前真值层导出的一个显式只读对关系工件
  • scene_view_diagnostics 对于一个显式的只读视图空间伪影,具有投影范围、帧覆盖范围、中心以及命名相机的可见/部分/遮挡/帧外判断,或 USER_PERSPECTIVE
  • 这些空间图形/视图诊断工具现在是默认可见的一部分 llm-guided 支持集,使模型可以保持一个明确的3D方向层可用,而不是仅从名称、屏幕截图或部分循环有效载荷推断空间状态

当前引导引导引导曲面:

  • router_set_goal
  • router_get_status
  • browse_workflows
  • reference_images
  • scene_scope_graph
  • scene_relation_graph
  • scene_view_diagnostics
  • search_tools
  • call_tool
  • 可选提示桥接工具 MCP_PROMPTS_AS_TOOLS_ENABLED=true:
  • list_prompts
  • get_prompt

有提示能力的客户端应该更喜欢本机MCP提示。快速桥是一座
仅适用于工具客户端的兼容层,可以对Streamable HTTP禁用
已经使用本机提示组件的配置文件。

当前指导的实用程序准备路径:

  • 引导/计划搜索现在可以到达:
  • scene_get_viewport
  • scene_clean_scene
  • 这些实用程序操作保持受限,不会重新打开整个遗留曲面
  • 规范引导的发现包装器是 call_tool(name=..., arguments=...)
  • 规范清理参数形状 llm-guided 是
    keep_lights_and_cameras;旧的拆分标志仅用于兼容性
    不应作为有文件记录的公共表格使用
  • reference_images(action="attach", source_path=...) 每次通话有一个参考;
    批处理形状现在会在引导恢复指导下失败,而不是原始模式噪声
  • collection_manage(action=..., collection_name=...) 保持规范
    公共形态;遗产 name 只是一个狭义的兼容性别名
  • modeling_create_primitive(...) 仅限于 primitive_type,
    radius/size, location, rotation,可选 name;不受支持
    快捷方式,如 scale, segments, rings, subdivisions,或
    原始时间 collection_name 现在,在这两方面都有可操作的指导,但都失败了
    直接路径和代理引导路径
  • 构建目标仍应从以下方面开始 router_set_goal(...),但截图/
    视口/场景重置请求应使用引导的实用程序路径
  • 如果只有在进入引导构建后才发现过时的场景状态
    表面, scene_clean_scene(...) 也可以在那里作为有界
    回收舱;目标前的清理仍然是首选路径
  • 需要恢复时,仍然允许进行构建阶段清理

上的当前公共别名 llm-guided:

内部工具 llm-guided 公共名称 公共参数更改
scene_context check_scene action -> query
scene_inspect inspect_scene object_name -> target_object
scene_configure configure_scene settings -> config
workflow_catalog browse_workflows workflow_name -> name, query -> search_query

为什么这很重要:

  • 引导配置文件从一个紧凑的可见引导集开始,而不是
    完整目录
  • 分组/公共工具易于发现
  • 隐藏的原子工具仍然可以作为基础设施使用,而不是作为默认的公共心智模型
  • 在宏观表面更宽之前,专业家庭不会进入正常的引导进入层

原子基础和文件

根 README.md 是故意的 不 完整的工具目录。

详细的工具清单和原子族文档应保留在文档中,而不是在首页上。这是正确的长期结构 TASK-113.

根据您的需要使用这些文档:

  • 工具分层策略
  • 规范政策 atomic / macro / workflow、隐藏的原子工具、目标优先的使用和愿景/断言边界。
  • MCP服务器文档
  • Surface配置文件、引导别名、版本化合同和运行时/平台指导。
  • MCP客户端配置示例
  • 准备粘贴本地MCP客户端配置示例,用于指导/手动表面以及MLX、OpenRouter和Gemini视觉变体。
  • 视觉层文档
  • 运行时/后端、捕获包、参考图像、宏/工作流视觉集成说明,以及用于直接用户视图和固定相机透视捕获的仓库跟踪的真实视口评估包。
  • LLM指南v2
  • 类型化空间智能层、紧凑关系状态和有界下一步切换的策略文档,用于指导操作。
  • 空间智能研究简报
  • LLM/VLM空间推理、多视图推理和几何感知规划的外部研究切换。
  • 空间智能升级方案
  • 研究驱动的场景图、符号关系表示法和支持几何库选择的升级建议。
  • 可用工具摘要
  • 完整的库存和分组/公共工具概述。
  • 工具架构索引
  • MCP表面下方面向维护人员的工具系列图。

如果您想查看服务器构建的原子族,请从这里开始:

  • 场景工具架构
  • 建模工具架构
  • 网格工具架构
  • 超级工具架构

推荐解释:

  • 保持 /_docs/TOOLS/ 作为面向原子/分组架构图的维护者
  • 保持 README.md 产品外观紧凑
  • 保持 /_docs/AVAILABLE_TOOLS_SUMMARY.md 作为运行时清单

提供商备注

当前简短版本:

  • 本地默认值: mlx_local 具有Qwen VL 4B类模型路径;当前回购验证基线为 mlx-community/Qwen3-VL-4B-Instruct-4bit
  • 外部迭代比较候选: OpenRouter x-ai/grok-4.20-multi-agent
  • 外部谷歌家族比较路径: OpenRouter托管的谷歌家族模型加上谷歌人工智能工作室/双子座现在通过解析共享相同的窄阶段比较合同 vision_contract_profile 路由

外部视觉运行时注意事项:

  • VISION_EXTERNAL_PROVIDER 选择传输/提供商分支
  • VISION_EXTERNAL_CONTRACT_PROFILE 可选地覆盖外部比较流的提示/模式/解析器契约
  • 当未设置覆盖时,运行时会自动匹配Google系列型号ID,例如 gemma / gemini / learnlm,然后回退到提供程序默认值

每个提供商表的详细信息:

  • 视觉层文档->提供者注释

建筑

系统被故意拆分:

  • MCP服务器(server/):FastMCP表面、公共工具定义、转换、发现和响应契约。
  • 路由器(server/router/):目标解释、安全/纠正策略、工作流程匹配、会话上下文和指导执行行为。
  • 搅拌机插件(blender_addon/):实际 bpy 执行、RPC处理程序和Blender主线程安全操作调度。

通信通过TCP套接字上的JSON-RPC进行。

更多细节:

  • 建筑.md
  • 路由器文档
  • 运行时责任边界
  • 插件文档

结构化合同基线

服务器正在将关键表面移向机器可读的有效载荷,而不是繁重的JSON字符串。

当前结构化合同基线包括:

  • macro_cutout_recess
  • macro_finish_form
  • macro_attach_part_to_surface
  • macro_align_part_with_contact
  • macro_place_supported_pair
  • macro_cleanup_part_intersections
  • macro_relative_layout
  • scene_create
  • scene_configure
  • mesh_select
  • mesh_select_targeted
  • mesh_inspect
  • scene_snapshot_state
  • scene_compare_snapshot
  • scene_measure_distance
  • scene_measure_dimensions
  • scene_measure_gap
  • scene_measure_alignment
  • scene_measure_overlap
  • scene_assert_contact
  • scene_assert_dimensions
  • scene_assert_containment
  • scene_assert_symmetry
  • scene_assert_proportion
  • router_set_goal
  • router_get_status
  • workflow_catalog

这对于自动化、审计和未来的宏/工作流组合非常重要。

接触真理语义学

对于弯曲或圆形形状的接触敏感检查,现在使用真值层
区别:

  • 当有界网格感知路径为
    可用的
  • 当网格感知路径不可用时,bbox回退语义

这意味着一对仍然可以显示bbox接触,而主要的测量关系
残余 separated 如果真实网格表面仍然有可见的间隙。引导
混合真相跟踪现在在面向操作员的情况下延续了这一区别
摘要,而不是将其折叠为通用的“联系人通过/失败”
索赔。

当网格感知路径发现真正的重叠时,主要的测量关系也
停留 overlapping,因此重叠拒绝 scene_assert_contact(...) 仍然
它作为一个单独的真理条件起作用,而不是崩溃成简单的接触。

结构化澄清流程

引导表面支持将缺失的输入处理作为产品合同的一部分,而不是事后的想法。

  • 模型第一澄清 是的默认值 router_set_goal(...) 上 llm-guided:缺少工作流参数将返回类型化的 needs_input 首先将有效载荷传输到外部模型。
  • 键入回退有效载荷 保持相同的流在纯工具或兼容客户端上可用。
  • 人为/本地澄清保留用于后续/回退策略,而不是工作流执行的默认第一步。
  • router_set_goal(...) 可以请求受限选项、布尔值、枚举或工作流确认。
  • partial answers 在后续的转折中幸存下来。
  • workflow_catalog 导入冲突重用相同的澄清模型。

指导交接合同

引导式界面现在将工作流回退视为显式类型的契约,而不是隐藏在散文中的阶段副作用。

  • router_set_goal(...) 回报 guided_handoff 在有界连续路径上,例如 continuation_mode="guided_manual_build" 和 continuation_mode="guided_utility".
  • guided_handoff 命名 target_phase, direct_tools, supporting_tools,以及 discovery_tools 下一步 llm-guided.
  • workflow_import_recommended 停留 False 在这些回退路径上,除非用户明确要求工作流导入/创建行为。
  • router_get_status(...) 保留活动 guided_handoff 会话中诊断,以便客户端可以恢复预期的继续路径。

服务器驱动的引导流状态

引导表面现在带有一个明确的机器可读表面 guided_flow_state
合同除 guided_handoff.

  • router_set_goal(...), router_get_status(...),
    reference_compare_stage_checkpoint(...),以及
    reference_iterate_stage_checkpoint(...) 可以暴露 guided_flow_state
    对于活跃的 llm-guided 会话
  • guided_flow_state 报告:
  • flow_id
  • domain_profile
  • current_step
  • completed_steps
  • active_target_scope
  • spatial_scope_fingerprint
  • spatial_state_version
  • spatial_state_stale
  • last_spatial_check_version
  • spatial_refresh_required
  • required_checks
  • next_actions
  • blocked_families
  • allowed_families
  • allowed_roles
  • completed_roles
  • missing_roles
  • required_role_groups
  • required_prompts
  • preferred_prompts
  • step_status
  • 当前的域覆盖是:
  • generic
  • creature
  • building
  • 早期的引导构建会话现在从阶梯式空间上下文开始
    阶段,而不是立即暴露整个构建表面
  • scene_scope_graph(...) 在没有活动时绑定活动的引导目标范围
    范围还存在;空间刷新检查必须继续使用已绑定的空间
    目标作用域,而不是重新绑定到不同的对象集
  • 不相关的视图检查,例如
    scene_view_diagnostics(target_object="Camera", ...) 不满足a
    生物/建筑空间检查
  • 如果为主动引导目标附加了参考图像,请将其视为
    在决定第一个身体/头部/尾部质量之前的主要接地输入
    轮廓粗糙
  • 使用完整的语义对象名称,例如 Body, Head, Tail,
    ForeLeg_L,以及 HindLeg_R 而不是像这样不透明的缩写 ForeL
    / HindR,因为引导接缝/角色启发式算法在可读性方面更可靠
    名字
  • 上 llm-guided,服务器现在可以对弱角色敏感名称发出警告
    阻止明显不透明的占位符名称,例如 Sphere / Object 当他们
    用作语义零件名称
  • 不要打电话 scene_scope_graph(...), scene_relation_graph(...),或
    scene_view_diagnostics(...) 没有明确的范围,并假设这意味着
    “检查整个现场”
  • 在主动引导空间门或空间刷新重新启动期间
    这些空间助手应该被视为显式作用域工具,而不是
    全景探测器
  • 那些固定的只读空间助手在上可见时仍可调用
    llm-guided;指导性家庭封锁不得拒绝
    scene_scope_graph(...), scene_relation_graph(...),或
    scene_view_diagnostics(...) 仅仅是因为当前的构建步骤
    allowed_families 省略 spatial_context
  • 在引导门之外,作用域/关系图构建器仍然需要
    明确的 target_object, target_objects,或 collection_name;光秃秃的
    呼叫现在失败,而不是默默地返回空 scene 范围
  • 默认占位符范围,如股票 Cube 或通用根
    Collection 不再被视为有意义的指导目标/工作集
    自行绑定
  • 但对于之前的“这个场景已经不是空的了吗?”引导决策,
    搅拌机库存 Cube 加上库存相机/灯光助手仍然进入
    空场景主工作集引导路径
  • 这个非空的决定是有意在启动后命名为轻:真实
    具有默认基本体名称的多对象粗略分块,例如 Cube 或
    Sphere 仍然算作现有几何体,而仅辅助对象的场景仍然可以
    进入 bootstrap_primary_workset
  • 显式引导作用域现在从调用者意图而不是名称绑定
    启发式,所以真实的对象命名为 Cube, Sphere,或 Sunflower
    当操作员瞄准它们时,它们仍然可以成为活动的引导工作集
  • 在材质场景更改后,例如 scene_clean_scene(...),
    scene_duplicate_object(...), scene_rename_object(...),
    modeling_create_primitive(...), modeling_transform_object(...),
    modeling_join_objects(...), modeling_separate_object(...),或有界
    附件/对齐宏,引导运行时可以标记空间层
    停止并重新武装所需的检查
  • 相同的脏状态更新现在立即重新应用FastMCP可见性,
    因此,客户一看到所需的空间支持工具
    spatial_refresh_required 持续存在
  • 在流式HTTP上,引导脏状态和可见性终结器必须完成
    在主动工具响应返回之前;更改场景的路由同步工具
    状态将这些终结器推迟到MCP异步包装器,而不是调度
    分离会话状态写入
  • 异步包装器和本机异步建模助手保持阻塞
    同步工作线程上的路由器/RPC执行;只有引导式终结器运行
    在Streamable HTTP响应完成之前返回事件循环
  • 异步脏宏助手,例如 macro_cutout_recess(...) 和
    macro_finish_form(...) 使用等待的异步路由路径,以便可见性
    在Streamable HTTP响应完成之前重新应用
  • 异步空间助手,例如 scene_scope_graph(...),
    scene_relation_graph(...),以及 scene_view_diagnostics(...) 路线他们
    Blender支持的图形/诊断在记录之前读取事件循环
    引导式空间检查完成
  • 异步引导身份终结器,如成功 scene_rename_object(...)
    验证还可以在之前将Blender支持的场景查找排除在事件循环之外
    更新引导部件注册表
  • 使用路由器执行报告的本机异步建模工具必须仍然
    表面 guided_naming 通过活动MCP上下文发出警告;否则
    弱语义名称可能会失去其模型,面临更正提示
    可流式传输的HTTP
  • 原生异步建模和清理终结器导出成功的场景
    结构化突变 report.steps,而不是呈现的传统路线文本;
    多步校正的路由前缀为传统线路,不是可靠的来源
    用于指导脏状态或角色注册决策
  • 异步引导角色注册在决赛后重新应用FastMCP可见性
    先进的 guided_flow_state 坚持,所以 list_tools() 反映了
    Streamable HTTP响应完成前的新引导步骤
  • 异步公共工具变体必须保留原始公共文档字符串,
    特别是对于可视化引导的空间和建模助手,其描述
    教授所需的范围参数、工作流顺序和参数约束
  • 当路由器成功纠正错误时 modeling_transform_object(...) 呼叫
    到另一个有效的对象名称、引导的空间脏状态和引导的角色
    后续使用最终建模返回的转换对象名称
    step,而不是原始调用者提供的名称
  • 引导式网格编辑工具,如 mesh_extrude_region(...),
    mesh_loop_cut(...),以及 mesh_bevel(...) 现在已映射到
    secondary_parts 家庭,因此它们在空间上下文门期间被阻止
    并在成功编辑几何图形后重新进行空间检查
  • 当其中一个所需的空间检查完成并推进制导装置时
    流,服务器现在立即重新应用FastMCP可见性,而不是
    等待稍后的状态/搜索刷新
  • 支持/对称感知关系对现在保持支持和对称
    即使它们共享相同的注释 (from_object, to_object) 密钥为a
    通用的主要目标对,因此后来的引导规划者仍然可以看到
    支持/对称语义,而不仅仅是通用边
  • 包含所需生物接缝的关系图仍然增加了回退
    primary_to_other 在请求的范围内为非接缝对象配对,因此
    未分类对象不会从混合引导诊断中消失
  • 健康的支撑/对称对不再仅仅因为其
    中心不同或它们不是字面上的接触对;仅 unsupported /
    asymmetric 支持/对称性判断在那里被视为失败
  • 当 guided_flow_state.spatial_refresh_required == true,治疗
    next_actions=["refresh_spatial_context"] 作为权威服务器状态,
    不是咨询性散文;焕然一新 scene_scope_graph(...) 反对
    已先绑定目标作用域,然后重新运行剩余的所需空间
    检查同一范围
  • scene_view_diagnostics(...) 仅在以下情况下计入导向空间门
    它返回真实的可用视图空间证据;无头/不可用的探头
    保持只读,本身不满足所需的检查
  • 如果阶段比较/迭代在当前指导下发现重要问题
    角色/工作集切片仍然不完整,调控器现在可以保留会话
    在有界构建中继续,而不是过早升级到
    inspect_validate
  • 当未完成的阶段保持返回时
    loop_disposition="continue_build",坚持 guided_flow_state
    保持在当前步骤中,不标记未完成的角色切片
    已完成;继续关注 missing_roles 在依赖后期之前
    可见性
  • 这种不完整的阶段保持也适用于阶段迭代没有
    correction_focus 或 action_hints;无行动比较结果不得
    推进具有所需缺失角色的指导构建 finish_or_stop
  • 在流程到达后续步骤之后,例如 place_secondary_parts,the
    服务器仍然可以在缺少的主质量作为其一部分时保持可用
    相同的有界工作集,而不是强制松鼠/建筑物运行
    立即放弃未完成的核心质量
  • 对于生物遮挡接缝, intersecting 仍然可以接受
    嵌入耳朵/头部或鼻子/头部位置,但 floating_gap 在头部/身体上,
    尾巴/身体,或四肢/身体仍然可以操作
  • 如果所需的工具系列被流隐藏/阻挡,请检查
    router_get_status().guided_flow_state,填写所列内容
    required_checks,并遵循 next_actions 而不是猜测隐藏的工具
    名字进入 call_tool(...)
  • 如果明确的指导目标停留在手动/无匹配路径上
    模式建议工作流仍可以扩展;那里面还压抑着什么
    状态是较低置信度的启发式重新开放路径
  • 现在,在引导曲面上进行精确的工具名称搜索,以返回
    更紧凑、更小的结果集,而不是用完整的结果集淹没模型
    扩展有效载荷以实现简单查找
  • 对于角色敏感的构建步骤,请处理 allowed_roles 和 missing_roles 作为
    执行合同的一部分,而不是咨询性散文
  • 内务管理/工作台操作,如 collection_manage(...) 应该留下来
    可用于已创建的对象,即使它们的语义角色是
    在较早的步骤中注册
  • 可以保留已注册主对象的有界细化
    在会话进入下一步后可能;后续步骤不是
    旨在完全冻结所有早期的物质
  • 使用 guided_register_part(object_name=..., role=...) 作为规范
    告诉服务器一个对象代表什么语义部分的方法;可选的
    guided_role=... 关于构建工具的提示只是为了方便
  • 可选的 role_group=... 值必须与服务器的域角色映射匹配;
    呼叫者无法重新分类 body_core, head_mass,或类似
    角色敏感突变呼叫 utility 或另一个家庭绕过
    电流导向相位门
  • guided_register_part(...) 现在验证命名的Blender对象
    实际存在之前,它可以算作引导角色完成;拼写错误
    不自行创建已完成的角色
  • 如果引导对象验证根本无法读取Blender场景,
    guided_register_part(...) 现在显然失败了,而不是在指导下变异
    未经验证的对象名称的会话状态
  • 传入的显式目标名称 scene_scope_graph(...) /范围构建
    在引导之前,路径现在遵循相同的Blender真理验证规则
    范围可以绑定
  • 那些可选 guided_role=... 提示仅在激活时自动注册
    引导流已经存在;在主动引导流之外,它们不会产生
    自身持续的角色状态
  • 失败的create调用现在对于引导角色状态也保持不变:
    如果 modeling_create_primitive(...) 返回一个失败字符串,请求
    角色不会仅仅因为语义而自动注册 name 已供应
  • 上 modeling_create_primitive(...), guided_role=... 现在还需要一个
    显式语义 name;引导创建不允许自动生成Blender
    名称将成为语义部分注册
  • 当路由器预先准备纠正步骤时,例如 scene_set_mode(...),
    成功的引导创建/转换调用仍会注册生成的角色
    反对最终建模步骤,而不是放弃便利性
    注册只是因为通话变得多步骤
  • 引导式角色便利注册现在还可以处理有效的对象名称
    包含撇号,例如 King's Crown,而不是截断
    存储对象名称
  • 引导运行时成功解析还处理引号对象内的撇号
    名称作为创建/转换/重命名/连接结果的对象名称的一部分,
    因此,成功后仍会运行过时状态标记和引导注册表同步
    突变
  • 规范的配对名称,如 ForeLeg_L, ForeLeg_R,以及 ForeLegPair
    现在将其视为强语义名称 foreleg_pair / hindleg_pair
    而不是在更严格的命名策略下发出警告或阻止
  • 上 modeling_create_primitive(...),引导角色自动注册现在绑定
    到Blender返回的实际创建的对象名称,因此角色状态保持不变
    即使Blender自动为默认名称编号,如 Cube.001 或
    使用不同的默认对象名称,例如 Suzanne
  • 上 modeling_transform_object(...),引导角色自动注册现在绑定
    到最终路由步骤返回的实际转换对象名称,因此
    路由器纠正的对象身份仍然会重新进行空间检查和更新
    真正更改的对象的角色状态
  • 成功的 scene_rename_object(...) 调用现在保留引导部件注册表
    与重命名的Blender对象对齐,以便以后进行角色敏感的转换
    仍然可以恢复已注册的角色,而无需手动重新注册
  • 成功的 scene_rename_object(...) 呼叫还重新启用了手臂引导的空间
    检查,因为绑定的目标范围指纹是基于名称的
  • 成功的 scene_duplicate_object(...) 呼叫还重新启用了手臂引导的空间
    检查,因为重复会更改可见的工作集/范围关系事实
  • 普通字符串突变结果失败,例如 Object 'Missing' not found
    现在保持引导会话状态不变;它们不会重新武装空间
    仅仅因为包装器返回,就检查或重写引导角色注册
    一串
  • scene_clean_scene(...) 现在清除引导部件注册表并返回
    引导流至 bootstrap_primary_workset 而不是携带完成
    在空旷的场景中向前移动
  • 现在,在同一会话中启动不同的指导目标会重置指导部分
    注册新流程,而不是继续执行已完成的角色
    从上一个对象
  • 破坏性的身份/拓扑变化,如 modeling_join_objects(...)
    或 modeling_separate_object(...) 现在放弃过时的引导部件注册;
    如果结果对象仍然计数,则显式重新注册它们
    朝向引导式角色完成
  • 这些相同的破坏性拓扑变化也重新武装了引导的空间检查,
    因为之前捕获的范围/视图事实在以下情况下不再可信
    对象被合并或拆分
  • 对于宏观捕捉/视觉伪影, macro_attach_part_to_surface(...) 现在
    在额外的网格表面轻推后刷新其动作后捕捉包,
    因此,附上的图片和真相摘要描述了最终的坐姿
    前轻推中间姿势
  • 路由宏报告可以是 partial 并且仍然携带 error;MCP
    适配器保留该结构化报告,包括 actions_taken,
    修改对象、验证建议、捕获/真相数据,以及
    后续指导,而不是把它塞进一个失败的空信封里
  • 如果在运行时配置中启用了可选的分段sidecar,但尚未启用
    在当前比较路径上执行,现在分阶段比较/迭代响应
    报告 part_segmentation.status="unavailable" 而不是默默地呆着
    disabled
  • 如果服务器警告或阻止引导命名,请重命名或创建对象
    使用建议的语义名称之一,而不是重试相同的弱名称
    缩写
  • 引导命名和引导空间角色推理现在使用标记边界样式
    匹配而不是原始子字符串匹配,因此以下名称 Heart 或
    TruthBodyAnchorHead 不要成为偶然的语义耳朵/身体/头部角色
  • 这 required prompt bundle 和 preferred prompt bundle 命名为
    guided_flow_state 是提示的资产名称,而不是替代
    服务器驱动流;提示支持流,它们不会成为流

引导参考准备

参考驱动的分阶段工作现在有一个明确的准备就绪合同,而不是
隐藏的排序假设。

  • router_set_goal(...) 和 router_get_status(...) 揭露 guided_reference_readiness.
  • 有效载荷报告 attached_reference_count, pending_reference_count,
    compare_ready, iterate_ready,加上机器可读 blocking_reason 和
    next_action
  • reference_images(action="attach", source_path=...) 可以等待,直到导游
    目标会话实际上已经准备就绪,然后自动采用
  • 如果同一个进球已经有了活跃的裁判,并且在
    needs_input,上演的裁判与已经活跃的进球分开
    参考,直到准备就绪返回
  • 如果就绪会话仍然携带另一个目标的明确未决参考,
    reference_images(action="list" · "remove" · "clear", ...) 现在治疗
    一致地合并可见集,而不是留下损坏的未决记录
  • reference_compare_stage_checkpoint(...) 和
    reference_iterate_stage_checkpoint(...) 现在会话失败很快
    未准备好,并重复同样的操作 guided_reference_readiness 有效载荷
  • 如果 reference_iterate_stage_checkpoint(...) 回报
    loop_disposition="inspect_validate",停止自由形式建模并切换到
    立即检查/测量/断言
  • 如果它回来了 loop_disposition="continue_build" 当
    guided_flow_state.missing_roles 仍然非空,继续当前
    角色切片;服务器有意将引导步骤保持在适当的位置
    即使比较结果本身已经产生,也要进入下一阶段
    没有可操作的纠正提示
  • router_set_goal(..., gate_proposal={...}) 可以接受可选型号-或
    参考导出主动引导目标的门建议。服务器
    将其标准化为 active_gate_plan,开始每个门 pending,以及
    回报 gate_intake_result.policy_warnings 对于删除的隐藏工具名称,
    不支持的门类型,原始Blender/Python指令,不可用,需要
    目标时间摄入表面上的参考/感知证据,或
    客户提供的完工索赔,如 passed.
  • router_get_status(...), router_set_goal(...),并上演
    引用比较/迭代有效载荷可以公开 active_gate_planLLM
    reference_understanding、轮廓、分割、分类和VLM
    检查点源可以提出或支持门,但场景/空间/网格和
    断言证据仍然是通过/失败状态的真相权威。
  • 分阶段参考比较/迭代有效载荷还可以预测主动门计划
    进入顶级 gate_statuses, completion_blockers,
    next_gate_actions,以及 recommended_bounded_tools,因此客户不需要
    从嵌套的平面形状推断出即时修复路径。
  • scene_relation_graph(...) 更新第一个确定性门切片
    required_part, attachment_seam, support_contact,以及 symmetry_pair
    有权威证据参考文献、状态原因、完成障碍,以及
    有界修复工具提示;后来引导的场景突变标记了受影响的人
    验证器支持的状态 stale 通过现有的空间污染路径。
  • 主动门阻断器将引导视线/搜索范围缩小到现有区域
    验证器和维修工具;一个失败的接缝闸门应该导致以下关系
    图形/测量/断言/宏修复工具,而不是广泛的目录或目标重置。
  • 未解决的 completion_blockers 关于分阶段迭代响应,现在也推
    loop_disposition="inspect_validate" 即使比较循环没有
    重复同样的视力只矫正焦点。
  • 如果分阶段比较降级,但强确定性真理发现仍然存在
    存在,使用相同的检查/测量/断言切换,而不是即兴创作
    另一个大型自由形式校正
  • 错误阶段迭代切换到 inspect_validate 或
    finish_or_stop 返回前也重新应用引导能见度
  • 对于分阶段比较/迭代, goal_override 不再是会话
    替代;改为使用主动引导式目标会话
  • 对于集合或多对象分段捕捉,捕捉焦点现在落下
    当没有明确的目标时,返回到组装好的目标范围的主要目标
    target_object 已供应
  • 确定性轮廓度量更倾向于目标/焦点捕捉
    请求 target_view,而不是广义 context_wide 捕捉
  • reference_compare_current_view(..., persist_view=True, view_name=..., orbit_horizontal=..., zoom_factor=...) 保留捕获的用户视图,并执行以下操作
    在紧凑视图期间,不要再次回放这些相同的视图调整
    诊断

会话诊断

引导/运行时有效负载现在公开了显式的MCP会话元数据:

  • router_set_goal(...) 包括 session_id 和 transport
  • router_get_status(...) 包括 session_id 和 transport
  • reference_compare_stage_checkpoint(...) 包括 session_id 和 transport
  • reference_iterate_stage_checkpoint(...) 包括 session_id 和 transport

当前运行时指南:

  • 有状态的 streamable HTTP是长时间引导的推荐传输方式
    运行和调试会话感知的引用/检查点流
  • 最近的引导会话强化删除了已知的路由器记账路径
    这可能会在路由工具期间破坏活动目标/参考会话状态
    执行
  • 如果你调查未来的州损失事件,请进行比较 session_id 和
    transport 首先要区分:
  • 传输/会话重新连接
  • 应用程序级目标重置
  • 正常的指导性准备障碍,如缺少目标或参考

服务器端采样助手基线

MCP服务器现在在活动请求中有一个有界的分析辅助层。

当前用例:

  • 可选的 assistant_summary 在检查繁重的路径上,例如 scene_snapshot_state, scene_compare_snapshot, scene_get_hierarchy, scene_get_bounding_box,以及 scene_get_origin_info
  • 有界的 repair_suggestion 上 router_set_goal, router_get_status,以及 workflow_catalog

显式辅助终端状态:

  • success
  • unavailable
  • masked_error
  • rejected_by_policy

规则很严格:助手可以帮助总结或建议,但他们不会覆盖场景真相或路由器策略。

版本化表面基线

公共表面演变明确地进行了版本控制:

表面轮廓 默认接触线
legacy-manual legacy-v1
legacy-flat legacy-v1
llm-guided llm-guided-v2

兼容性说明:

  • llm-guided-v1 仍然可以选择作为回滚线
  • workflow_catalog, scene_context,以及 scene_inspect 参与引导式表面演化故事

代码模式决策

当前基准基线:

  • legacy-flat
  • llm-guided
  • code-mode-pilot

当前决定:

  • 决定:保持 code-mode-pilot 作为实验性只读表面
  • 不要将代码模式设置为写入繁重或破坏几何图形的Blender工作的默认路径

支持矩阵

  • 搅拌机:已测试 搅拌机5.0 在E2E覆盖范围内;剩余插件最小值 搅拌机4.0+ 尽最大努力。
  • python: 3.11+
  • FastMCP任务运行时: fastmcp 3.2.4 + pydocket 0.19.x
  • 代码模式沙箱额外: 毕丹蒂蒙蒂0.0.11
  • 操作系统:macOS/Windows/Linux
  • 记忆:路由器语义特征依赖于本地LaBSE模型和相关的向量基础设施

快速开始

1.安装Blender插件

  1. 下载 blender_ai_mcp.zip 从 发布页面 或者在本地构建 python scripts/build_addon.py.
  2. 打开Blender->编辑->首选项->附加组件。
  3. 点击 安装。.. 并选择zip文件。
  4. 启用插件。它在端口上启动本地Blender RPC服务器 8765.

2.在引导的配置文件上运行MCP服务器

推荐默认值:

  • ROUTER_ENABLED=true
  • MCP_SURFACE_PROFILE=llm-guided
  • 地图 /tmp 如果您想要主机可见的图像/文件输出

Docker命令示例:```bash
docker run -i --rm \
-v /tmp:/tmp \
-e BLENDER_AI_TMP_INTERNAL_DIR=/tmp \
-e BLENDER_AI_TMP_EXTERNAL_DIR=/tmp \
-e ROUTER_ENABLED=true \
-e MCP_SURFACE_PROFILE=llm-guided \
-e BLENDER_RPC_HOST=host.docker.internal \
ghcr.io/patrykiti/blender-ai-mcp:latest
``````bash
docker run --rm \
-p 8000:8000 \
-v /tmp:/tmp \
-e BLENDER_AI_TMP_INTERNAL_DIR=/tmp \
-e BLENDER_AI_TMP_EXTERNAL_DIR=/tmp \
-e ROUTER_ENABLED=true \
-e MCP_SURFACE_PROFILE=llm-guided \
-e MCP_TRANSPORT_MODE=streamable \
-e MCP_HTTP_HOST=0.0.0.0 \
-e MCP_HTTP_PORT=8000 \
-e MCP_STREAMABLE_HTTP_PATH=/mcp \
-e MCP_PROMPTS_AS_TOOLS_ENABLED=false \
-e BLENDER_RPC_HOST=host.docker.internal \
ghcr.io/patrykiti/blender-ai-mcp:latest


通用MCP客户端配置示例:```json
{
"mcpServers": {
"blender-ai-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v", "/tmp:/tmp",
"-e", "BLENDER_AI_TMP_INTERNAL_DIR=/tmp",
"-e", "BLENDER_AI_TMP_EXTERNAL_DIR=/tmp",
"-e", "ROUTER_ENABLED=true",
"-e", "MCP_SURFACE_PROFILE=llm-guided",
"-e", "BLENDER_RPC_HOST=host.docker.internal",
"ghcr.io/patrykiti/blender-ai-mcp:latest"
]
}
}
}

网络注释:

  • macOS/Windows: 使用 host.docker.internal
  • Linux: 更喜欢 --network host 和 BLENDER_RPC_HOST=127.0.0.1
  • MCP_TRANSPORT_MODE=stdio 保持当前子进程/stdio MCP模式
  • MCP_TRANSPORT_MODE=streamable 启动有状态的流式HTTP MCP服务器
  • MCP_PROMPTS_AS_TOOLS_ENABLED=false 禁用与工具兼容的提示桥
    为迅速有能力的客户;本地MCP提示仍然可用

对于更广泛的配置文件/配置示例,请使用:

  • MCP服务器文档
  • MCP客户端配置示例
  • .env.example 对于完整跟踪的运行时/config变量集

测试

单元测试:```bash
PYTHONPATH=. poetry run pytest tests/unit/ -v


单位收款计数:```bash
poetry run pytest tests/unit --collect-only

E2E测试:```bash
python3 scripts/run_e2e_tests.py


E2E收集计数:```bash
poetry run pytest tests/e2e --collect-only

预承诺:bash poetry run pre-commit install --hook-type pre-commit --hook-type pre-push poetry run pre-commit run --all-files

更多细节:

  • 测试文档
  • 开发文档

文档地图

  • 建筑
  • MCP服务器文档
  • 视觉层文档
  • 路由器文档
  • 路由器责任边界
  • 插件文档
  • LLM指南v2
  • 空间智能研究简报
  • 空间智能升级方案
  • 可用工具摘要
  • 工具架构索引
  • 提示
  • 任务

贡献

阅读 贡献.md 在打开PR之前。该仓库强制执行Clean Architecture边界、类型化Python、路由器元数据规则和预提交验证。

社区和支持

如果 blender-ai-mcp 在你的工作流程中很有用,考虑赞助它的长期发展。

赞助有助于为维护、文档、测试和更高级别的可靠性工作提供资金,这些工作使该仓库不同于原始Blender代码生成:目标优先的路由、精心策划的工具、确定性验证和生产成形的工作流支持。

成为赞助商

  • 支持.md
  • 安全.md
  • 代码_OF_CONDUCT.md
  • GitHub赞助商
  • 请我喝杯咖啡

作者

帕特里克 Ciechanski

  • github: 观察

许可证

该项目根据 Apache许可证2.0.

请参阅:

  • 许可证.md
  • 通知

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Blender AI MCP 怎么安装?

在客户端按下面的安装命令接入:docker run -i --rm \。装完在客户端配置里引用同一个包或端点。

Blender AI MCP 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Blender AI MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Blender AI MCP 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

Blender AI MCP 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Blender AI MCP 能提供哪些能力?

资料显示能力标签包括 3D建模、Python、Claude、AI控制。具体工具清单以官方文档为准。

Blender AI MCP 需要什么运行环境?

运行时为 Docker;属于本地进程,需要在本机装好运行环境。

Blender AI MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。