Blender 2D MCP

Model Context Protocol을 통해 Blender 5.x에서 AI 기반 2D 드로잉 및 애니메이션을 지원합니다. MCP 클라이언트(Claude Desktop, Cursor, VS Code Copilot agent mode 등)가 실행 중인 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 — TCP JSON 명령 서버를 내장한 Blender 애드온. 명령은 큐에 들어가며 bpy.app.timers를 통해 Blender 메인 스레드에서 실행됩니다.

• src/blender_2d_mcp/server.py — 애드온의 명령을 MCP 도구로 노출하는 FastMCP stdio 서버.

요구 사항

• Blender 5.2 LTS만 지원 (애드온은 이전 빌드에서 활성화를 거부합니다. 사용하는 GPv3 API 표면은 5.2 전용입니다)

• Python ≥ 3.10 및 mcp[cli] (자동 설치됨)

Related MCP server: Blender MCP Bridge

설치

1. Blender에 애드온 설치

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

2. 이 저장소에서 addon.py를 선택합니다.

3. Interface: Blender 2D MCP를 활성화합니다.

4. 사이드바(View > Sidebar 또는 N 키)를 열고 → Blender2DMCP 탭으로 이동합니다.

5. Connect to MCP Client를 클릭합니다(기본 포트 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 HD 프레임은 가로로 약 ±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. '온 투스' 애니메이션(24fps에서 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

테스트 스위트는 가짜 bpy에 대해 서버 클래스를 AST 리프팅하여 Blender 외부에서 애드온의 TCP 전송을 실행합니다. Blender 설치가 필요 없습니다. 실제 Grease Pencil 데이터를 다루는 핸들러 로직은 Blender 내부에서 검증해야 합니다.

문제 해결

라이선스

MIT