Blender 2D MCP

AI 驱动的 2D 绘制与动画，面向 Blender 5.x，通过 Model Context Protocol 实现。让 MCP 客户端（Claude Desktop、Cursor、VS Code Copilot agent 模式等）直接在运行中的 Blender 实例内创建 Grease Pencil 绘图、关键帧、材质和渲染。

基于 Blender 的 GPv3 API（bpy.ops.grease_pencil.*、GreasePencilDrawing）构建，参考了 ahujasid/blender-mcp。

flowchart LR
    A[MCP Client<br/>Claude / Cursor / VS Code] <-->|stdio / JSON-RPC| B[blender-2d-mcp<br/>FastMCP server]
    B <-->|TCP JSON<br/>localhost:9876| C[addon.py<br/>socket server in Blender]
    C -->|main thread| D[Grease Pencil API<br/>GPv3]

• addon.py — Blender 插件，内嵌一个 TCP JSON 命令服务器。命令会排队并通过 bpy.app.timers 在 Blender 主线程上执行。

• src/blender_2d_mcp/server.py — FastMCP stdio 服务器，将插件的命令暴露为 MCP 工具。

要求

• 仅限 Blender 5.2 LTS（插件在旧版本上会拒绝启用；其使用的 GPv3 API 是 5.2 特有的）

• Python ≥ 3.10，并安装 mcp[cli]（会自动安装）

Related MCP server: Blender MCP Bridge

安装

1. 将插件安装到 Blender

1. 在 Blender 中：编辑 > 偏好设置 > 插件 > 安装…

2. 从此仓库中选择 addon.py。

3. 启用 界面：Blender 2D MCP。

4. 打开侧边栏（视图 > 侧边栏，或按 N）→ Blender2DMCP 选项卡。

5. 点击 连接到 MCP 客户端（默认端口 9876）。保持 Blender 运行。

提示：blender-2d-mcp --install-addon 会将 addon.py 复制到你的下载文件夹，并打印这些步骤。

2. 连接 MCP 客户端

服务器仅绑定到 localhost——本地使用无需身份验证令牌。

选项 A — uvx（无需安装）：

uvx --from "g:\My Projects\blender-2d-mcp" blender-2d-mcp

选项 B — 可编辑安装：

cd "g:\My Projects\blender-2d-mcp"
pip install -e .
blender-2d-mcp            # runs the stdio MCP server

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "blender-2d-mcp": {
      "command": "uvx",
      "args": ["--from", "g:\\My Projects\\blender-2d-mcp", "blender-2d-mcp"]
    }
  }
}

Cursor（.cursor/mcp.json）或通用 stdio 客户端：

{
  "mcpServers": {
    "blender-2d-mcp": {
      "command": "C:\\Path\\To\\Python\\Scripts\\blender-2d-mcp.exe",
      "args": []
    }
  }
}

VS Code / GitHub Copilot Chat（.vscode/mcp.json——已包含在此仓库中）：

{
  "servers": {
    "blender-2d-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "g:\\My Projects\\blender-2d-mcp", "blender-2d-mcp"],
      "env": {}
    }
  }
}

或者，如果 blender_2d_mcp 已通过 pip 安装在某个环境中，请使用 该环境的 Python："command": "C:\\Path\\To\\Python\\python.exe", "args": ["-m", "blender_2d_mcp.server"]。

使用方法：打开 Copilot Chat，将模式下拉菜单切换到 Agent，Blender 工具即可用（#blender-2d-mcp）。可通过命令面板中的 MCP: List Servers 启动/停止/重启服务器。编辑 mcp.json 后重新加载 VS Code 窗口。

2D 画布

使用 setup_2d_scene 后，视口会设置为前视正交视图，因此绘制平面为世界 XZ 平面：

单位是米（Blender 默认）；在默认相机缩放下，1920×1080 高清帧横向大约跨越 ±5 个单位。

工具目录

典型工作流

1. get_gp_scene_info + get_viewport_screenshot — 查看当前内容。

2. 如果从零开始，setup_2d_scene → create_gp_object。

3. 使用 gp_draw_shape / gp_draw_stroke 绘制；传入 frame_number 可将笔画放在关键姿势上（帧会自动创建）。使用 gp_draw_strokes 批量绘制精细图形。

4. 填充形状：创建 fill_alpha > 0 的材质，然后设置 fill=True + fill_material。

5. 按“一拍二”的方式制作动画（24 fps 下每 2 帧一个关键姿势）：用 gp_copy_frame 复制姿势，用 gp_transform_stroke 微调，再用 gp_interpolate 生成中间帧。添加 NOISE 修改器模拟手绘抖动。

6. 使用 render_animation(use_video=True) 渲染，并轮询 get_render_status。

7. 每次修改后务必截图 以进行视觉验证。错误可通过 undo 撤销。

开发

pip install -e ".[dev]"
python -m pytest tests/ -v

测试套件通过 AST 提升服务器类并配合模拟的 bpy，在 Blender 外部运行插件的 TCP 传输——无需安装 Blender。涉及真实 Grease Pencil 数据的处理器逻辑必须在 Blender 内部验证。

故障排除

许可证

MIT