Blender Animation MCP

Blender를 위한 애니메이션 특화 MCP 서버입니다. 정밀한 타임라인/키프레임 도구와 렌더링된 시각적 피드백을 결합하여, 멀티모달 모델이 트랜스폼 수치만으로 추론하는 대신 실제로 애니메이션한 결과를 직접 확인할 수 있게 합니다.

import_glb_asset은 텍스처 또는 리깅이 적용된 GLB/glTF 에셋을 계층 구조를 평평하게 만들지 않고 로드하며, inspect_rig는 골격과 바인딩을 노출합니다. 또 key_pose_bone은 원시 RNA 경로보다 안전한 포즈 인터페이스를 제공합니다. 기존의 임베디드 애니메이션 클립은 Blender의 glTF 임포터가 가져오며 시각적 검토에 포함됩니다.

볼 수 있고 제어할 수 있는 것

• 정확한 프레임 하나를 렌더링하여 MCP 이미지 콘텐츠로 반환합니다.

• 빠른 시각 검토를 위해 샷 전체에서 샘플링한 콘택트 시트를 렌더링합니다.

• 시간에 따라 평가된 월드 트랜스폼과 바운딩 박스를 샘플링합니다.

• 액션, F-커브, 핸들, 보간, NLA 스트립, 제약, 카메라, 마커를 검사합니다.

• 키를 삽입/삭제하고, 보간을 변경하고, 타임라인을 제어하고, 파일을 저장합니다.

• 임의의 .glb 및 .gltf 에셋을 계층, 재질, 리그, 애니메이션 클립과 함께 가져옵니다.

• 생성된 골격과 주요 뼈를 로컬 좌표계 쿼터니언으로 직접 검사합니다.

• 가중치가 적용된 팔다리 체인 후보를 찾아내 각각의 실제 로컬 축을 검사합니다.

• 포즈를 작성하기 전에 뼈 변형을 비파괴적으로 프로브합니다.

• 발바닥 IK 컨트롤을 만들고, 월드 공간에 키를 넣으며, 지면에 고정된 발의 미끄러짐을 검증합니다.

콘택트 시트는 실제 장면 렌더링으로 만들어집니다. 의도적으로 25프레임으로 제한되며, 자세한 검토가 필요하면 의심스러운 프레임에서 render_frame을 호출하세요. 애니메이션은 시간에 따라 진행되므로 어떤 유한한 샘플도 모든 중간 프레임이 올바르다는 것을 증명할 수는 없습니다. 의도된 작업 흐름은 콘택트 시트 → 대상 프레임 → 수치 평가 → (마지막은 시각 패스)입니다.

Related MCP server: Blender MCP

Install

1. blender_addon 디렉터리를 zip으로 압축하고(zip 안에 blender_addon/__init__.py가 포함되어 있어야 함) Edit > Preferences > Add-ons > Install from Disk에서 설치합니다. 그리고 Animation MCP Bridge를 활성화합니다.

2. 브리지는 Blender와 함께 자동으로 시작됩니다. Scene Properties > Animation MCP에서 상태를 확인하거나 중지/다시 시작할 수 있습니다.

3. 이 MCP 패키지를 설치합니다:

   pip install -e .

4. MCP 클라이언트 설정에 추가합니다:

   {
     "mcpServers": {
       "blender-animation": {
         "command": "blender-animation-mcp",
         "env": {
           "BLENDER_MCP_HOST": "127.0.0.1",
           "BLENDER_MCP_PORT": "9876",
           "BLENDER_MCP_TOKEN": ""
         }
       }
     }
   }

보안을 위해 브리지는 기본적으로 localhost에 바인딩됩니다. Blender에서 토큰을 구성한 경우 MCP 프로세스에도 동일한 BLENDER_MCP_TOKEN을 설정하세요. 포트를 신뢰할 수 없는 네트워크에 노출하지 마십시오.

권장 모델 루프

1. 편집 전에 inspect_scene과 inspect_object_animation을 호출하십시오. 새 GLB/glTF 에셋이라면 먼저 import_glb_asset을 호출하고, 리깅이 되어 있다면 inspect_rig를 호출합니다.

2. 키와 보간을 설정합니다.

3. 전체 샷에 걸쳐 inspect_animation_visual을 호출합니다.

비디오 기반 포즈 매칭에는 setup_video_reference를 소스 MP4와 함께 호출하고, 정확한 키 포즈에는 render_video_overlay를, 콘택트 시트에는 inspect_video_overlay를 사용합니다. 리깅에 키를 넣기 전에 Blender 타임라인을 참조 영상의 유용한 구간과 정렬하도록 video_frame_offset을 조정하세요.

낯선 생성 리그라면 discover_limb_chains를 실행하고 inspect_bone_axes로 후보를 검사한 뒤, probe_bone_deformation으로 힌지 동작을 확인하세요. 그러한 이후에만 create_limb_ik로 발바닥 컨트롤을 만들고, key_paw_pose로 애니메이션하며, validate_walk_cycle로 접촉을 검증합니다. 4. 접촉 지점, 극단 지점, 눈에 보이는 불연속 지점 주변에서 render_frame을 사용합니다. 5. 정확한 간격이나 월드 트랜스폼이 중요할 때 evaluate_animation을 사용합니다. 6. 반복하면서 다듬은 다음 save_blend를 호출합니다.

환경 변수

BLENDER_MCP_HOST, BLENDER_MCP_PORT, BLENDER_MCP_TOKEN, 그리고 BLENDER_MCP_TIMEOUT는 MCP-to-Blender 연결을 설정합니다.

애드온을 활성화한 뒤, 창 없이 Blender를 실행하려면:

blender --background --python blender_addon/headless.py

포함된 systemd/blender-animation-mcp.service는 이 워커를 포트 9877에서 계속 실행시킵니다.