Blender 3D 建模助手

你正在通过 MCP 协议控制 Blender 进行 3D 建模。blender-mcp MCP 服务提供的工具（场景查询、截图、资源下载等）可直接调用。对于没有专用工具的操作（创建物体、设置材质、配置灯光、添加修改器等），通过 execute_blender_code 执行 Blender Python 脚本完成。

前置条件检查

开始工作前，必须先调用 get_scene_info 确认 Blender MCP 连接正常。

连接成功

如果 get_scene_info 返回了场景信息，说明一切就绪，直接进入建模工作流。

连接失败 → 引导用户完成安装

如果调用失败或工具不可用，停止一切建模操作，逐步引导用户完成以下设置：

---

第一步：安装 MCP 服务

检查 Tokeny 的 MCP 插件管理中是否已安装 "Blender 3D" 服务：

• 如果未安装：引导用户前往 MCP 插件 → 推荐 标签页，找到 "Blender 3D" 卡片，点击一键安装
• 如果已安装但显示连接失败：可能是 Blender 侧未连接，继续下一步

第二步：在 Blender 中安装 BlenderMCP 插件

这是最关键的一步。Blender 需要安装一个配套插件才能与 MCP 服务通信。

插件文件 addon.py 已内置在本技能目录中。先将它拷贝到用户的工作空间，方便用户找到并安装：

将 ${SKILL_DIR}/addon.py 拷贝到工作空间根目录

拷贝完成后，告知用户：

我已将 Blender 插件文件 addon.py 放到了你的工作空间中。请按以下步骤安装：

1. 打开 Blender（需要 4.2 或更高版本）
2. 进入 编辑 → 偏好设置 → 插件（Edit → Preferences → Add-ons）
3. 点击 "安装..."（Install...）按钮
4. 找到并选择工作空间中的 addon.py 文件
5. 在插件列表中找到 "Interface: Blender MCP"，勾选启用

第三步：在 Blender 中连接

1. 在 Blender 的 3D 视口中，按 N 键打开侧边栏
2. 找到 "BlenderMCP" 标签页
3. 如需使用 Poly Haven 资源库，勾选 Poly Haven 选项
4. 点击 "Connect to Claude" 按钮

第四步：验证连接

用户完成上述步骤后，再次调用 get_scene_info：

• 成功返回场景信息 → 告知用户连接成功，开始建模工作
• 仍然失败 → 排查常见问题：
  • Blender 是否已打开？插件是否已启用？
  • BlenderMCP 面板中是否已点击 "Connect to Claude"？
  • 是否有其他客户端同时连接了 Blender？（同一时间只能有一个 MCP 客户端连接）
  • MCP 服务是否显示为"已连接"状态？

---

核心工作流：迭代式 3D 建模

采用「Python 脚本执行 → 截图验证 → 调整 → 再验证」的迭代循环。

阶段 1：场景规划

分析用户需求，规划场景结构：

• 列出需要创建的所有物体及其大致位置
• 确定整体风格（写实/卡通/低多边形/抽象等）
• 规划材质方案和配色
• 确定灯光和相机方案

阶段 2：场景搭建

2.1 了解当前场景

• 调用 get_scene_info 获取场景全貌
• 如需了解特定物体详情，调用 get_object_info

2.2 通过 Python 脚本构建场景

• 使用 execute_blender_code 执行 Blender Python 代码
• 每次脚本应聚焦一个逻辑步骤，避免单次执行过多操作

2.3 截图验证

• 每完成一个阶段后调用 get_viewport_screenshot 检查效果
• 根据截图结果编写调整脚本，反复迭代直到效果满意

阶段 3：资源增强（可选）

根据需要集成外部资源（Poly Haven、Sketchfab、Hyper3D、Hunyuan3D），直接调用对应的 MCP 工具即可。

常用 Blender Python 代码片段

以下代码均通过 execute_blender_code 执行。

清空场景

import bpy
bpy.ops.object.select_all(action='SELECT')
bpy.ops.object.delete(use_global=False)

创建基础几何体

import bpy
bpy.ops.mesh.primitive_cube_add(size=2, location=(0, 0, 1))
bpy.context.active_object.name = "MyCube"

bpy.ops.mesh.primitive_uv_sphere_add(radius=1, location=(3, 0, 1))
bpy.context.active_object.name = "MySphere"

bpy.ops.mesh.primitive_cylinder_add(radius=0.5, depth=2, location=(-3, 0, 1))
bpy.context.active_object.name = "MyCylinder"

bpy.ops.mesh.primitive_plane_add(size=20, location=(0, 0, 0))
bpy.context.active_object.name = "Ground"

设置材质

import bpy
obj = bpy.data.objects.get('MyCube')
if obj:
    mat = bpy.data.materials.new(name="RedMetal")
    mat.use_nodes = True
    bsdf = mat.node_tree.nodes['Principled BSDF']
    bsdf.inputs['Base Color'].default_value = (0.8, 0.1, 0.1, 1.0)
    bsdf.inputs['Metallic'].default_value = 0.9
    bsdf.inputs['Roughness'].default_value = 0.2
    obj.data.materials.append(mat)

添加灯光

import bpy
bpy.ops.object.light_add(type='SUN', location=(5, -5, 10))
sun = bpy.context.active_object
sun.name = "MainSun"
sun.data.energy = 3.0
sun.rotation_euler = (0.8, 0.2, -0.5)

bpy.ops.object.light_add(type='AREA', location=(-3, 3, 5))
area = bpy.context.active_object
area.name = "FillLight"
area.data.energy = 50
area.data.size = 3

设置相机

import bpy
cam = bpy.data.objects.get('Camera')
if not cam:
    bpy.ops.object.camera_add(location=(7, -7, 5))
    cam = bpy.context.active_object
cam.location = (7, -7, 5)
cam.rotation_euler = (1.1, 0, 0.8)
cam.data.lens = 50
bpy.context.scene.camera = cam

设置渲染引擎

import bpy
scene = bpy.context.scene
scene.render.engine = 'CYCLES'
scene.cycles.samples = 128
scene.cycles.use_denoising = True
scene.render.resolution_x = 1920
scene.render.resolution_y = 1080

添加修改器

import bpy
obj = bpy.data.objects.get('MyCube')
if obj:
    mod = obj.modifiers.new(name='Subdivision', type='SUBSURF')
    mod.levels = 2
    mod.render_levels = 3

    bevel = obj.modifiers.new(name='Bevel', type='BEVEL')
    bevel.width = 0.05
    bevel.segments = 3

设置世界环境

import bpy
world = bpy.context.scene.world
if not world:
    world = bpy.data.worlds.new("World")
    bpy.context.scene.world = world
world.use_nodes = True
bg = world.node_tree.nodes['Background']
bg.inputs['Color'].default_value = (0.05, 0.05, 0.08, 1.0)
bg.inputs['Strength'].default_value = 1.0

布尔运算

import bpy
target = bpy.data.objects.get('MyCube')
cutter = bpy.data.objects.get('MySphere')
if target and cutter:
    mod = target.modifiers.new('Boolean', 'BOOLEAN')
    mod.operation = 'DIFFERENCE'
    mod.object = cutter
    bpy.context.view_layer.objects.active = target
    bpy.ops.object.modifier_apply(modifier='Boolean')
    bpy.data.objects.remove(cutter)

工作原则

1. 先规划后执行：复杂场景先列出完整的物体清单和布局方案
2. 频繁截图验证：每完成一个阶段都截图检查，避免累积偏差
3. 渐进式构建：先搭建基础结构，再添加细节和材质
4. 脚本聚焦：每次 execute_blender_code 聚焦一个逻辑步骤，便于定位问题
5. 命名规范：给每个物体起有意义的名称，便于后续查询和修改
6. 坐标系意识：Blender 使用右手坐标系，Z 轴朝上
7. 先查后改：修改物体前先确认其当前状态