Blender 2D MCP

AI-driven 2D drawing and animation for Blender 5.x via the Model Context Protocol. Lets MCP clients (Claude Desktop, Cursor, VS Code Copilot agent mode, …) create Grease Pencil drawings, keyframes, materials, and renders directly inside a running Blender instance.

Built on Blender's GPv3 API (bpy.ops.grease_pencil.*, GreasePencilDrawing).

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[blender_2d_addon.py<br/>socket server in Blender]
    C -->|main thread| D[Grease Pencil API<br/>GPv3]

• blender_2d_addon.py — Blender addon embedding a TCP JSON command server. Commands are queued and executed on Blender's main thread via bpy.app.timers.

• src/blender_2d_mcp/server.py — FastMCP stdio server exposing the addon's commands as MCP tools.

Requirements

• Blender 5.2 LTS only (the addon refuses to enable on older builds; the GPv3 API surface it uses is 5.2-specific)

• Python ≥ 3.10 with mcp[cli] (installed automatically)

Related MCP server: Blender MCP Bridge

Installation

1. Install the addon into Blender

1. In Blender: Edit > Preferences > Add-ons > Install…

2. Select blender_2d_addon.py from this repository.

3. Enable Interface: Blender 2D MCP.

4. Open the sidebar (View > Sidebar, or press N) → Blender2DMCP tab.

5. Click Connect to MCP Client (default port 9876). Keep Blender running.

Tip: blender-2d-mcp --install-addon copies blender_2d_addon.py to your Downloads folder and prints these steps.

2. Connect an MCP client

The server binds to localhost only — no auth token is needed for local use.

Option A — uvx (no install):

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

Option B — editable install:

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) or generic stdio clients:

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

VS Code / GitHub Copilot Chat (.vscode/mcp.json — already included in this repo):

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

Alternatively, if blender_2d_mcp is pip-installed in some environment, use that environment's Python: "command": "C:\\Path\\To\\Python\\python.exe", "args": ["-m", "blender_2d_mcp.server"].

To use it: open Copilot Chat, switch the mode dropdown to Agent, and the Blender tools become available (#blender-2d-mcp). Start/stop/restart the server from the Command Palette with MCP: List Servers. Reload the VS Code window after editing mcp.json.

The 2D canvas

With setup_2d_scene the viewport is set to a front orthographic view, so the drawing plane is world XZ:

Units are meters (Blender default); a 1920×1080 HD frame at default camera zoom spans roughly ±5 units horizontally.

Tool catalog

Typical workflow

1. Ask first: when a user requests an animation, the AI confirms target platform/aspect (YouTube 16:9, Shorts/Reels 9:16, square), duration, fps, and audio/text needs before drawing anything. The MCP itself stays orientation-neutral — every tool accepts explicit parameters.

2. get_gp_scene_info + get_viewport_screenshot — see what exists.

3. setup_platform_scene("reels") (or any custom setup_2d_scene(resolution=[w,h])) → create_gp_object if starting fresh.

4. Style first: gp_apply_style_preset per layer and gp_create_palette for named colors (gp_apply_palette_color applies them; layer_name='*' restyles everything).

5. Draw with gp_draw_shape / gp_draw_stroke; pass frame_number to place strokes on key poses (frames are created automatically). Use gp_draw_strokes to batch detailed drawings.

6. Filled shapes: create a material with fill_alpha > 0, then fill=True + fill_material.

7. Characters: one GP object per body part → create_armature (parented bone chains on the XZ plane) → parent_gp_to_bone each part → animate with pose_bone or one-call apply_motion_preset (bounce/float/blink/wave/swing).

8. Animate 'on twos' (key poses every 2 frames at 24 fps): copy poses with gp_copy_frame, tweak with gp_transform_stroke, then gp_interpolate for in-betweens. Add a NOISE modifier for hand-drawn wobble. Check timing with get_animation_summary.

9. Social polish: hook text in the first second (add_text_object + animate_text_in), keep action inside the central ~80% (platform UI covers edges), add music (add_audio_strip).

10. Render with render_animation(use_video=True) and poll get_render_status — output is H264 mp4 with AAC audio, ready to upload.

11. Always screenshot after changes to verify visually. Mistakes are undoable via undo.

Skill for AI agents

This repository ships an agent skill at .github/skills/blender-2d-animation/SKILL.md that teaches AI agents how to combine the tools: workflow ordering, step-by-step recipes (loop animation, cut-out character rig, explainer video with audio), batching rules, common pitfalls, and the screenshot-verify loop.

• VS Code / GitHub Copilot agent mode: picked up automatically from .github/skills/ in the workspace.

• Claude Code / other clients: copy or symlink the folder to their skills location, e.g.

# Claude Code (project scope)
mkdir -p .claude/skills
cp -r .github/skills/blender-2d-animation .claude/skills/

The skill is documentation only — it doesn't change server behavior. Clients without skill support still get the essential guidance via the MCP server's built-in instructions field.

Development

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

The test suite runs the addon's TCP transport outside Blender by AST-lifting the server class against a fake bpy — no Blender install needed. Handler logic that touches real Grease Pencil data must be verified inside Blender.

Troubleshooting

License

MIT