Blockbench MCP Overview

Blockbench MCP 概述

Complete guide to the Blockbench MCP server for AI-assisted 3D modeling.

面向AI辅助3D建模的Blockbench MCP服务器完整指南。

What is Blockbench MCP?

什么是Blockbench MCP？

An MCP server that exposes Blockbench functionality to AI agents through:

Tools: Actions that create, modify, or query the 3D model
Resources: Read-only data endpoints for model information
Prompts: Reusable guidance for specific workflows

一款将Blockbench功能开放给AI Agent的MCP服务器，通过以下方式实现：

工具：用于创建、修改或查询3D模型的操作
资源：用于获取模型信息的只读数据端点
提示词：针对特定工作流的可复用指导内容

Tool Categories

工具分类

Domain	Tools	Purpose
Animation	7	Keyframes, rigs, curves, timeline
Camera	3	Screenshots, camera control
Cubes	2	Cube creation and modification
Elements	5	Groups, outliner, duplication
Import	1	GeoJSON import
Mesh	11	Spheres, cylinders, extrusion, vertices
Paint	12	Brushes, fill, shapes, layers
Texture	13	Textures, PBR materials
UI	4	Actions, evaluation, dialogs
UV	3	UV mapping
Hytale	12	Hytale-specific (requires plugin)

领域	工具数量	用途
动画	7	关键帧、绑定、曲线、时间轴
相机	3	截图、相机控制
立方体	2	立方体创建与修改
元素	5	组、大纲视图、复制
导入	1	GeoJSON导入
网格	11	球体、圆柱体、挤出、顶点
绘制	12	画笔、填充、形状、图层
纹理	13	纹理、PBR材质
UI	4	操作、评估、对话框
UV	3	UV映射
Hytale	12	Hytale专属功能（需插件）

Resources

资源

Resource	URI Pattern	Data
projects	`projects://{id}`	Project info, formats
textures	`textures://{id}`	Texture metadata
nodes	`nodes://{id}`	3D node data
hytale-format	`hytale://format`	Hytale format info
hytale-attachments	`hytale://attachments/{id}`	Attachment collections
hytale-pieces	`hytale://pieces/{id}`	Attachment pieces
hytale-cubes	`hytale://cubes/{id}`	Hytale cube properties

资源	URI 格式	数据内容
projects	`projects://{id}`	项目信息、格式
textures	`textures://{id}`	纹理元数据
nodes	`nodes://{id}`	3D节点数据
hytale-format	`hytale://format`	Hytale格式信息
hytale-attachments	`hytale://attachments/{id}`	附件集合
hytale-pieces	`hytale://pieces/{id}`	附件部件
hytale-cubes	`hytale://cubes/{id}`	Hytale立方体属性

Prompts

提示词

Prompt	Purpose
`blockbench_native_apis`	Blockbench v5.0 API security guide
`blockbench_code_eval_safety`	Safe code evaluation patterns
`model_creation_strategy`	Model creation guidance
`hytale_model_creation`	Hytale modeling guide
`hytale_animation_workflow`	Hytale animation guide
`hytale_attachments`	Hytale attachments guide

提示词	用途
`blockbench_native_apis`	Blockbench v5.0 API安全指南
`blockbench_code_eval_safety`	安全代码评估模式
`model_creation_strategy`	模型创建指导
`hytale_model_creation`	Hytale建模指南
`hytale_animation_workflow`	Hytale动画指南
`hytale_attachments`	Hytale附件指南

Quick Start Workflows

快速入门工作流

Create a Simple Model

创建简单模型

undefined

undefined

1. Create project

1. 创建项目

create_project: name="my_model", format="bedrock"

2. Create texture

2. 创建纹理

create_texture: name="skin", width=64, height=64

3. Add bone structure

3. 添加骨骼结构

add_group: name="root", origin=[0, 0, 0] add_group: name="body", parent="root", origin=[0, 12, 0]

4. Add geometry

4. 添加几何体

place_cube: elements=[{name: "torso", from: [-4, 12, -2], to: [4, 24, 2]}], group="body"

5. Apply texture

5. 应用纹理

apply_texture: id="torso", texture="skin"

6. View result

6. 查看结果

capture_screenshot

undefined

capture_screenshot

undefined

Create and Animate

创建并制作动画

undefined

undefined

1. Build model (see above)

1. 构建模型（见上文）

2. Create animation

2. 创建动画

create_animation: name="idle", animation_length=2.0, loop=true

3. Add keyframes

3. 添加关键帧

manage_keyframes: bone_name="body", channel="rotation", keyframes=[ {time: 0, values: [0, 0, 0]}, {time: 1.0, values: [0, 5, 0]}, {time: 2.0, values: [0, 0, 0]} ]

4. Play animation

4. 播放动画

animation_timeline: action="play"

undefined

animation_timeline: action="play"

undefined

Paint a Texture

绘制纹理

undefined

undefined

1. Create texture

1. 创建纹理

create_texture: name="block", width=16, height=16, fill_color="#8B4513"

2. Add details

2. 添加细节

draw_shape_tool: shape="rectangle", start={x: 2, y: 2}, end={x: 14, y: 14}, color="#A0522D" paint_with_brush: coordinates=[{x: 8, y: 8}], brush_settings={color: "#654321", size: 2}

3. View texture

3. 查看纹理

get_texture: texture="block"

undefined

get_texture: texture="block"

undefined

Tool Patterns

工具使用模式

Information Gathering

信息收集

list_outline            # View model hierarchy
list_textures           # View textures
list_materials          # View PBR materials
hytale_get_format_info  # View Hytale format (if active)

list_outline            # 查看模型层级
list_textures           # 查看纹理
list_materials          # 查看PBR材料
hytale_get_format_info  # 查看Hytale格式（若已激活）

Modification Pattern

修改模式

Most modification tools follow:

Identify target by ID or name
Specify changes
Changes are recorded for undo

大多数修改工具遵循以下流程：

通过ID或名称识别目标
指定修改内容
修改操作会被记录以支持撤销

Screenshot Workflow

截图工作流

set_camera_angle: position=[0, 20, 50], rotation=[0, 0, 0], projection="perspective"
capture_screenshot      # 3D view only
capture_app_screenshot  # Entire Blockbench window

set_camera_angle: position=[0, 20, 50], rotation=[0, 0, 0], projection="perspective"
capture_screenshot      # 仅3D视图
capture_app_screenshot  # 整个Blockbench窗口

Evaluation (Advanced)

评估（高级功能）

risky_eval: code="Cube.all.length"  # Query Blockbench directly
trigger_action: action="undo"       # Trigger Blockbench actions

risky_eval: code="Cube.all.length"  # 直接查询Blockbench
trigger_action: action="undo"       # 触发Blockbench操作

Domain Integration

领域集成

Model + Texture

模型 + 纹理

undefined

undefined

Create model

创建模型

place_cube: elements=[{name: "block", from: [0,0,0], to: [16,16,16]}]

Create texture

创建纹理

create_texture: name="block_tex", width=16, height=16

Paint texture

绘制纹理

paint_fill_tool: texture_id="block_tex", x=0, y=0, color="#00FF00", fill_mode="element"

Apply

应用纹理

apply_texture: id="block", texture="block_tex"

undefined

apply_texture: id="block", texture="block_tex"

undefined

Model + Animation

模型 + 动画

undefined

undefined

Create bone hierarchy (important for animation)

创建骨骼层级（对动画至关重要）

add_group: name="root", origin=[0, 0, 0] add_group: name="arm", parent="root", origin=[4, 12, 0]

Add geometry to bones

为骨骼添加几何体

place_cube: elements=[{name: "arm_geo", from: [0, 0, -1], to: [2, 10, 1]}], group="arm"

Animate the bone

为骨骼制作动画

create_animation: name="wave", animation_length=1.0 manage_keyframes: bone_name="arm", channel="rotation", keyframes=[{time: 0, values: [0, 0, 0]}, {time: 0.5, values: [0, 0, 90]}]

undefined

create_animation: name="wave", animation_length=1.0 manage_keyframes: bone_name="arm", channel="rotation", keyframes=[{time: 0, values: [0, 0, 0]}, {time: 0.5, values: [0, 0, 90]}]

undefined

PBR Material Workflow

PBR材质工作流

undefined

undefined

Create textures for each channel

为每个通道创建纹理

create_texture: name="stone_color", width=16, height=16 create_texture: name="stone_normal", width=16, height=16, fill_color="#8080FF" create_texture: name="stone_mer", width=16, height=16, fill_color=[0, 0, 200, 255]

Create material

创建材质

create_pbr_material: name="stone", textures={ color: "stone_color", normal: "stone_normal", mer: "stone_mer" }

Configure

配置材质

configure_material: material_id="stone", config={ metalness_emissive_roughness: {metalness: 0, emissive: 0, roughness: 0.9} }

undefined

configure_material: material_id="stone", config={ metalness_emissive_roughness: {metalness: 0, emissive: 0, roughness: 0.9} }

undefined

Error Handling

错误处理

Tools throw descriptive errors with suggestions:

Element not found: "Use list_outline tool to see available elements"
Texture not found: "Use list_textures tool to see available textures"
Invalid format: "Current project is not using a Hytale format"

工具会抛出带有建议的描述性错误：

元素未找到：“使用list_outline工具查看可用元素”
纹理未找到：“使用list_textures工具查看可用纹理”
格式无效：“当前项目未使用Hytale格式”

Best Practices

最佳实践

Query first: Use
```
list_*
```
tools to understand current state
Build hierarchy: Create bone structure before geometry
Set origins: Place group origins at pivot points for animation
Name elements: Use descriptive names for easy reference
Validate: Use
```
hytale_validate_model
```
for Hytale projects
Screenshot: Capture progress with
```
capture_screenshot
```

先查询：使用
```
list_*
```
工具了解当前状态
构建层级：先创建骨骼结构再添加几何体
设置原点：将组原点放置在动画枢轴点
命名元素：使用描述性名称以便后续引用
验证模型：针对Hytale项目使用
```
hytale_validate_model
```
工具
截图记录：使用
```
capture_screenshot
```
记录制作进度

Tool Status

工具状态

stable: Production-ready
experimental: Working but may change

Most tools are experimental but functional. Check tool annotations for current status.

stable：可用于生产环境
experimental：可用但可能会变更

大多数工具处于实验阶段但功能可用。请查看工具注释了解当前状态。

blockbench-mcp-overview

Original

Translation

Blockbench MCP Overview

Blockbench MCP 概述

What is Blockbench MCP?

什么是Blockbench MCP？

Tool Categories

工具分类

Resources

资源

Prompts

提示词

Quick Start Workflows

快速入门工作流

Create a Simple Model

创建简单模型

1. Create project

1. 创建项目

2. Create texture

2. 创建纹理

3. Add bone structure

3. 添加骨骼结构

4. Add geometry

4. 添加几何体

5. Apply texture

5. 应用纹理

6. View result

6. 查看结果

Create and Animate

创建并制作动画

1. Build model (see above)

1. 构建模型（见上文）

2. Create animation

2. 创建动画

3. Add keyframes

3. 添加关键帧

4. Play animation

4. 播放动画

Paint a Texture

绘制纹理

1. Create texture

1. 创建纹理

2. Add details

2. 添加细节

3. View texture

3. 查看纹理

Tool Patterns

工具使用模式

Information Gathering

信息收集

Modification Pattern

修改模式

Screenshot Workflow

截图工作流

Evaluation (Advanced)

评估（高级功能）

Domain Integration

领域集成

Model + Texture

模型 + 纹理

Create model

创建模型

Create texture

创建纹理

Paint texture

绘制纹理

Apply

应用纹理

Model + Animation

模型 + 动画

Create bone hierarchy (important for animation)

创建骨骼层级（对动画至关重要）

Add geometry to bones

为骨骼添加几何体

Animate the bone

为骨骼制作动画

PBR Material Workflow

PBR材质工作流

Create textures for each channel