가이드사용법5분 읽기

Claude Code로 3D 모델 리깅과 애니메이션: Blender 스크립트 대신 에이전트에게 리거를 주세요

afk-rig MCP 서버를 추가하면 Claude Code가 도구 호출 한 번으로 캐릭터, 동물, 소품을 리깅하고, 모든 애니메이션을 검사해 잘못된 곳을 고칩니다.

API 키 받기설정하기 ↓
localhost:5173
claude · ~/game

> models/fox.glb를 네발 동물로 리깅하고 씬에서 달리게 해 줘

● rig_model (path: "models/fox.glb", type: "fox", animations: ["Idle", "Walk", "Run"])

⎿
models/fox.rigged.glb · type fox · 3 animations · charge free

● Update (src/scene.js)

⎿
Updated src/scene.js with 9 additions

● 여우를 리깅했고 달리고 있습니다. Idle과 Walk도 파일에 들어 있어 바로 블렌딩할 수 있습니다.

afk-rig를 추가한 Claude Code. 여우는 afk.ai로 리깅한 모델로, three.js에서 Run을 재생하고 있습니다.

AI 코딩 에이전트에게 "이 모델을 리깅해서 걷게 해 줘"라고 하면 보통 모든 걸 직접 하려고 합니다. 본을 배치하는 Blender Python 스크립트, 자동 웨이트, 키프레임으로 찍은 걷기, 테스트 렌더링, 그리고 무릎이 반대로 꺾이면 다시 처음부터. 세션 하나를 통째로 쓰고도 제대로 보이지 않을 수 있습니다.

afk-rig MCP 서버는 그 대신 도구 하나를 줍니다. rig_model은 모델을 afk.ai/rig와 같은 AI 리거로 보내고, 스켈레톤, 스킨 웨이트, 체형에 맞는 모든 애니메이션이 담긴 GLB를 보통 1분 안에 받아 저장합니다. 에이전트는 자신이 잘하는 일, 즉 그 애니메이션을 게임에서 재생하는 코드에 힘을 쏟을 수 있습니다.

에이전트에게 수동 리깅이 어려운 이유

리깅은 코딩 작업처럼 보이지만, 대부분은 에이전트가 볼 수 없는 형태에 대한 판단입니다. 에이전트는 버텍스 좌표와 바운딩 박스로 작업하고, 모든 실수는 무언가가 움직여야 비로소 드러납니다.

조인트
어깨, 엉덩이, 무릎이 어디인지 추측합니다. 스타일라이즈드 캐릭터, 개, 드래곤에서는 이런 추측이 빗나가는 경우가 많고, 관절 하나가 잘못된 위치에 있으면 그 뒤의 모든 애니메이션이 망가집니다.
스킨 웨이트
Blender의 자동 웨이트는 실제 작업에서 흔한 메시, 즉 부품이 분리되어 있거나 구멍이 있거나 조각이 겹치는 메시에서 "Bone Heat Weighting: failed to find solution for one or more bones" 오류와 함께 실패하는 경우가 많습니다. 그러면 에이전트는 눈으로 확인할 수 없는 메시 수정을 끝없이 되풀이합니다.
애니메이션
그럴듯한 걷기, 달리기, 대기 동작을 직접 보지 않고 맞추기에는 키프레임이 너무 많고, 새로운 체형마다 처음부터 다시 시작해야 합니다.
비용
시도할 때마다 시간과 토큰이 들고, 같은 모델로 두 번 돌려도 같은 결과가 나오는 일은 드뭅니다.

대신 도구 호출 한 번

rig_model은 모델을 afk.ai의 리거에 넘깁니다. 신체 부위를 찾도록 학습된 AI가 그 체형에 맞게 만든 스켈레톤을 배치하고, 스킨 웨이트는 실제 작업 메시로 조정된 프로세스에서 나오며, 애니메이션은 바로 그 스켈레톤에 맞춰 만들어졌기 때문에 리타기팅 없이 맞습니다.

돌아오는 것은 three.js, Godot, Unreal, Unity(glTFast 사용), Blender에서 불러올 수 있는 표준 GLB입니다. 사람은 손가락까지 모두 갖춘 본 66개와 애니메이션 594개를 받고, 나머지 14개 체형은 각각 12~128개를 받습니다. 같은 체형의 모델은 모두 본과 애니메이션 이름이 같으므로 컨트롤러 하나로 전부 움직일 수 있습니다.

에이전트가 직접 리깅에이전트가 afk-rig 호출
작업스크립트, 테스트 렌더, 수정을 여러 번 반복하는 경우가 많음도구 호출 한 번
시간몇 분에서 긴 세션까지보통 30초~1분
스켈레톤좌표로 추측신체 부위를 찾도록 학습된 AI가 배치
애니메이션하나씩 직접 키프레임 작업모두 그 체형용으로 제작
  • 메시: afk-rig로 렌더링한 리깅된 기사

    메시

    버텍스 23,293개, 머티리얼 6개, 텍스처 14개, 업로드한 그대로

  • 스켈레톤: afk-rig로 렌더링한 리깅된 기사

    스켈레톤

    본 66개, 손가락까지 모두 포함, 모든 휴머노이드에서 같은 이름

  • 스킨 웨이트: afk-rig로 렌더링한 리깅된 기사

    스킨 웨이트

    버텍스당 최대 4개 본, 여기서는 본마다 색 하나

  • 애니메이션 593개: afk-rig로 렌더링한 리깅된 기사

    애니메이션 593개

    체형에 맞는 모든 애니메이션. 이것은 0.7초 시점의 Sword_Attack

afk-rig render로 그린 knight.rigged.glb의 내부: AI 에이전트가 render_rig에서 받는 것과 같은 그림입니다.

설정하기

개발자 대시보드에서 API 키를 만드세요. Google로 로그인한 뒤 Create key를 누르면 됩니다. 그런 다음 Claude Code에 서버를 추가합니다.

claude mcp add afk-rig \
  --env AFK_API_KEY=afk_... \
  -- npx -y afk-rig mcp

Cursor, Windsurf, Claude Desktop 등 다른 MCP 클라이언트에서는 mcp.json에 추가합니다.

{
  "mcpServers": {
    "afk-rig": {
      "command": "npx",
      "args": ["-y", "afk-rig", "mcp"],
      "env": { "AFK_API_KEY": "afk_..." }
    }
  }
}

키는 서버의 환경 변수에 들어 있으므로 대화에 노출되지 않습니다. 에이전트는 도구 10개를 받습니다. afk.ai 클라우드에서 리깅하는 도구 5개, 그리고 리깅된 모델을 내 컴퓨터에서 검사하고 고치는 도구 5개입니다.

afk-rig · 10 toolsconnected

afk.ai 클라우드에서내 키 사용

  • rig_model.glb, .gltf, .fbx를 리깅해 리깅된 .glb를 저장
  • image_to_character그림을 넣으면 리깅된 캐릭터가 나옴
  • list_body_types체형 15가지와 각 체형의 애니메이션
  • get_account이번 달 남은 리깅
  • rig_status다른 곳에서 시작한 리깅의 상태

내 컴퓨터에서무료, 키 불필요

  • inspect_rig각 애니메이션의 문제점, 심한 것부터
  • render_rig원하는 순간의 그림, 스켈레톤을 겹쳐서
  • adjust_animationafk.ai/rig의 애니메이션 컨트롤, 팔이 몸에 파고들지 않게 유지
  • fix_stretching움직일 때 찢어지는 스킨을 고침
  • fix_spot한 부위의 스킨 웨이트를 다시 칠함
npx afk-rig mcp가 에이전트에게 주는 것. 수정할 때마다 새 파일을 쓰므로 원래 파일은 바뀌지 않습니다.

이렇게 요청해 보세요

추가하고 나면 평소 말하듯 요청하면 됩니다. 도구, 체형, 애니메이션은 에이전트가 알아서 고릅니다.

  • "models/knight.glb를 사람으로 리깅하고 three.js 씬에서 검 콤보를 재생해 줘."
  • "models/fox.glb를 Idle, Walk, Run만 넣어서 네발 동물로 리깅하고, 이 셋을 전환하는 Godot 씬을 만들어 줘."
  • "assets/props에 있는 .glb를 전부 Bounce와 Spin이 들어간 오브젝트로 리깅해서 동전과 보석 픽업에 써 줘."
  • "드래곤 타입에는 어떤 애니메이션이 있어? dragon.glb를 비행 애니메이션으로 리깅하고 그걸로 AnimationPlayer를 설정해 줘."
  • "horse.glb를 리깅한 다음 Unity에 Generic 리그로 임포트하고, Walk, Trot, Run으로 Animator Controller를 만들어 줘."
  • "concept/hero.png로 리깅된 캐릭터를 만들어 줘." 아직 모델이 없나요? image_to_character가 그림 한 장으로 모델을 만들어 리깅까지 해 줍니다. 2~3분 정도 걸립니다.
  • humanSword combo
  • foxRun
  • objectBounce
  • dragonFly
afk.ai로 리깅한 모델에서 처음 네 가지 요청이 돌려준 결과: 체형마다 고유한 애니메이션이 있습니다.

만든 결과를 검사하고 고치기

나머지 도구 5개는 afk.ai/rig의 Adjust 코드 그대로 내 컴퓨터에서 실행됩니다. 키도 필요 없고, 요금도 없고, 아무것도 업로드되지 않습니다. inspect_rig는 바닥에 파묻힌 발, 찢어진 스킨, 몸을 뚫고 들어간 팔을 가장 심한 것부터 찾아냅니다. render_rig는 어떤 애니메이션의 어떤 순간이든 그려 주므로 에이전트가 직접 볼 수 있습니다. adjust_animation, fix_stretching, fix_spot은 고친 결과를 새 파일 -v2.glb로 저장하므로 처음 파일은 절대 바뀌지 않습니다.

이렇게 에이전트는 스스로 돌릴 수 있는 루프를 갖게 됩니다. 검사하고, 가장 심한 순간을 렌더링하고, 한 가지를 바꾸고, 다시 확인합니다.

claude · ~/game

> 기사의 Walk를 확인하고 잘못된 곳을 고쳐 줘

● inspect_rig (file: "knight.rigged.glb", animations: ["Walk"])

⎿
Walk: arms or hands through the body in 18 of 51 frames (deepest: hand_l into calf_l, 4.6% of its height, at 1.633 s)

● adjust_animation (animations: ["Walk"], keep_arms_out: 1)

⎿
knight.rigged-v2.glb · arms_through_body_frames [18, 0]

● render_rig (animation: "Walk", time: 1.633) × 2

⎿
전과 후, 오른쪽에

● 걷는 동작의 3분의 1 동안 방패를 든 팔이 왼쪽 다리를 파고들었습니다. knight.rigged-v2.glb에서 고쳤습니다.

수정 전: 1.633초 시점의 기사 Walk, afk-rig로 렌더링

수정 전: 무릎이 방패를 뚫고 나옴

수정 후: 1.633초 시점의 기사 Walk, afk-rig로 렌더링

수정 후: 방패가 다리에 닿지 않고 떨어져 있음

위의 기사로 실제로 실행한 결과입니다. 이 도구들은 내 컴퓨터에서 API 키 없이 무료로 실행되며, 읽는 파일은 절대 바꾸지 않습니다.

나머지는 에이전트에게 맡기세요

리깅은 에이전트가 가장 많은 노력을 들이고도 가장 적은 결과를 얻는 작업입니다. 반대로 연결 작업에서는 에이전트가 진가를 발휘합니다. three.js AnimationMixer, Godot AnimationPlayer, Unity Animator Controller, 클립 간 블렌딩, 레벨에 필요한 모든 모델을 리깅하는 스크립트 같은 것들입니다. 리깅된 파일은 몇 줄이면 움직입니다.

const gltf = await new GLTFLoader().loadAsync('fox.rigged.glb')
scene.add(gltf.scene)
const mixer = new THREE.AnimationMixer(gltf.scene)
const run = THREE.AnimationClip.findByName(gltf.animations, 'Run')
mixer.clipAction(run).play() // then mixer.update(delta) every frame

오브젝트를 포함해 API로 무엇을 리깅할 수 있는지는 afk.ai 리깅 API로 만들 수 있는 것을 참고하세요.

자주 묻는 질문

Claude Code 말고 다른 클라이언트에서도 MCP 서버가 작동하나요?

네. stdio로 동작하는 표준 MCP 서버(npx afk-rig mcp)이므로 Cursor, Windsurf, Claude Desktop 등 다른 MCP 클라이언트도 같은 명령과 환경 변수에 넣은 AFK_API_KEY로 실행할 수 있습니다.

리깅은 어디서 이루어지나요?

rig_model과 image_to_character는 afk.ai 서버에서 실행됩니다. 도구가 파일을 업로드하고, 기다린 뒤, 결과를 프로젝트에 저장합니다. 모든 모델은 먼저 성인 콘텐츠 검사를 거치며, 검사에서 거부된 모델은 실패 처리되고 비용이 들지 않습니다. 검사하고 고치는 도구는 내 컴퓨터에서 실행됩니다.

어떤 모델을 리깅할 수 있나요?

GLB, 모든 리소스가 내장된 glTF, 또는 FBX를 최대 200 MB까지 리깅할 수 있으며, Draco나 meshopt로 압축된 파일도 됩니다. 모델에 맞는 체형을 고르세요: human, fox(네발 동물), horse(발굽 동물), bird, dragon, kaiju(공룡), spider, insect, snake, fish, turtle, kangaroo, frog, ghost, object.

비용은 얼마인가요?

매월 처음 3회 리깅은 무료이며, afk.ai/rig와 같은 무료 횟수입니다. 그 뒤에는 API 크레딧에서 차감됩니다. API 요금을 참고하세요. 실패한 리깅은 비용이 들지 않으며, 검사하고 고치는 도구는 언제나 무료입니다.

리깅한 모델을 상업적으로 써도 되나요?

네. 스켈레톤과 애니메이션은 CC0이며, 모델은 계속 사용자 소유입니다.

에이전트에게 리거를 주세요

체형에 맞는 모든 애니메이션을 GLB 하나에 담아, Claude Code, Cursor, 터미널이나 코드에서 받아 보세요.

API 키 받기

다른 가이드

API

afk.ai 리깅 API로 만들 수 있는 것

3D 모델을 보내면 체형에 맞는 모든 애니메이션이 담긴 리깅된 GLB가 돌아옵니다. 터미널, 코드, AI 에이전트에서 쓸 수 있습니다.

사용법

VRM을 FBX로, GLB를 FBX로, 그리고 반대로: 애니메이션을 지키는 3D 변환기

어떤 3D 모델이든 브라우저에서 GLB, FBX, USDZ, OBJ, STL로. 스켈레톤, 스킨 웨이트, 모든 키프레임, 페이스 셰이프가 유지됩니다.

가이드

애니메이션 리타기팅: 이미 리깅된 모델에 애니메이션 추가하기

리깅된 모델의 스켈레톤, 스킨 웨이트, 물리, 기존 애니메이션은 그대로 두고 애니메이션을 추가하세요.