Unity Engine에서 Claude Code 사용하는 방법

Claude Code는 Opus 4.5 같은 모델로 구동되는, 사용 가능한 최고의 AI 에이전트 중 하나입니다. 이 튜토리얼에서는 Claude Code를 Unity Engine에 직접 연결해 터미널에서 씬을 읽고, Unity API를 호출하고, 프로젝트를 수정할 수 있게 합니다.

필요한 것

• Unity 2021.3 이상
• Node.js ^20.19.0 또는 >=22.12.0 (CLI용)
• Claude Code 설치됨 (터미널 기반 AI 에이전트)
• AI Game Developer — AI 에이전트와 Unity 사이의 다리: github.com/IvanMurzak/Unity-MCP

AI Game Developer 설치하기

AI Game Developer는 고급 AI 에이전트 및 모델과 Unity Engine 사이의 다리 역할을 합니다. Unity 에디터에서 수동으로 설치하거나, CLI를 사용해 완전 자동으로 설정할 수 있습니다.

옵션 A: 수동 설치 (Unity 에디터)

1. AI Game Developer GitHub 페이지에서 설치 파일 다운로드
2. 설치 파일을 더블 클릭해 Unity에서 열기
3. Unity 가져오기 창에서 "Import" 클릭
4. Unity 컴파일이 끝날 때까지 대기

옵션 B: CLI 설치 (권장)

unity-mcp-cli 도구는 명령줄에서 전체 설정을 자동화합니다 — 수동 클릭이 필요 없습니다. 전역으로 설치한 뒤 어떤 Unity 프로젝트에도 플러그인을 추가할 수 있습니다.

# Install the CLI globally
npm install -g unity-mcp-cli

# Install the AI Game Developer plugin into your Unity project
unity-mcp-cli install-plugin ./MyUnityProject

install-plugin 명령은 프로젝트의 Packages/manifest.json 파일을 직접 수정합니다 — OpenUPM 스코프 레지스트리와 플러그인 의존성을 추가합니다. 기존 설치를 다운그레이드하지는 않습니다. 실행한 뒤 Unity에서 프로젝트를 열면 패키지 설치가 완료됩니다.

연결 구성하기

패키지를 가져오면 AI Game Developer 창이 나타납니다. 아래로 스크롤해 Claude Code 섹션을 찾고 "Configure"를 클릭하면 구성은 끝입니다. 그다음 "Connect"를 클릭해 연결을 시작하세요. Claude Code가 아직 실행 중이 아니므로 처음에는 오류가 표시되는데, 이는 정상입니다.

CLI: Claude Code용 MCP 설정

CLI는 Claude Code용 MCP 통합을 자동으로 구성할 수 있습니다 — Unity 에디터 UI가 필요 없습니다. 올바른 구성 파일을 작성해 Claude Code가 실행 시 AI Game Developer 서버를 찾을 수 있게 합니다.

# Configure Claude Code MCP integration
unity-mcp-cli setup-mcp claude-code ./MyUnityProject

# Generate skill files so Claude Code knows about available tools
unity-mcp-cli setup-skills claude-code ./MyUnityProject

Claude Code 실행하기

Claude Code는 Visual Studio Code에서 또는 터미널에서 직접 실행할 수 있습니다. 이 튜토리얼에서는 터미널 방식을 사용합니다. Unity 프로젝트 폴더에서 터미널을 여세요 — Unity의 Assets 폴더에서 마우스 오른쪽 버튼을 클릭해 "Show in Explorer"를 선택한 다음, 다시 마우스 오른쪽 버튼을 클릭해 "Open in Terminal"을 선택하면 됩니다.

# Navigate to your Unity project folder and start Claude Code
cd /path/to/your/unity/project
claude

Claude Code가 시작되면 AI Game Developer 창의 상태가 "Connected"로 바뀝니다. 모든 것이 제대로 동작하는지 확인하려면 Claude Code에서 /mcp 를 입력하세요 — "AI Game Developer"가 연결된 상태로 목록에 표시되어야 합니다.

Unity 씬에서 AI 테스트하기

연결이 되었으면 AI에게 "Unity 프로젝트의 이 씬에서 무엇이 보이나요?" 같은 질문을 해보세요. AI는 AI Game Developer가 제공하는 MCP 도구를 사용해 씬 계층 구조를 읽고, GameObjects를 검사하고, 찾은 내용을 보고합니다. 씬 데이터를 읽고, 중첩된 오브젝트를 살펴보고, 프로젝트의 전체 그림을 만들어가는 식으로 단계별로 진행합니다.

Claude Code가 도구 사용 권한을 요청하면 옵션 2를 선택해 허용하고 같은 도구에 대한 이후 프롬프트를 건너뛸 수 있습니다. 그러면 AI가 씬을 읽고 메시, 라이트, 중첩 계층 같은 오브젝트를 식별해 찾은 모든 것에 대한 자세한 설명을 제공합니다.

컨텍스트 최적화

AI Game Developer는 AI에게 많은 MCP 도구를 노출합니다. 핵심 팁: 필요 없는 도구는 비활성화하세요. 활성화된 모든 도구는 AI 컨텍스트를 소모하며, 컨텍스트를 깔끔하게 유지하면 AI가 더 효율적으로 작업하고 더 나은 결과를 냅니다. AI Game Developer 창에서 도구를 켜고 끌 수 있고, CLI를 사용해도 됩니다.

# List current tool/prompt/resource configuration
unity-mcp-cli configure ./MyUnityProject --list

# Enable only the tools you need
unity-mcp-cli configure ./MyUnityProject \
  --enable-tools rql-query,rql-mutate,rql-schema,script-update-or-create \
  --disable-all-prompts

# Or enable everything at once
unity-mcp-cli configure ./MyUnityProject \
  --enable-all-tools \
  --enable-all-prompts

• 사용하지 않는 도구는 비활성화해 AI 컨텍스트를 가볍게 유지하세요
• Resources가 필요 없다면 비활성화하는 것을 고려하세요
• 프롬프트는 슬래시 명령입니다 — Claude Code에서 / 를 입력하면 "set up an animation"이나 "add a component" 같은 사용 가능한 명령을 볼 수 있습니다
• Connected 상태 표시를 확인해 연결이 활성 상태인지 확인하세요

여기서부터 할 수 있는 일

Claude Code가 Unity에 연결되면 MCP 도구가 지원하는 모든 작업을 AI에게 요청할 수 있습니다 — 씬 검사, GameObjects 생성, 컴포넌트 수정, 애니메이션 생성, UI 제작 등등. AI는 포괄적인 도구 세트에 접근할 수 있으며 자연어 프롬프트에 따라 어떤 도구든 호출할 수 있습니다.

AI를 거치지 않고 명령줄에서 직접 MCP 도구를 실행할 수도 있으며, 이는 스크립팅과 CI 파이프라인에 유용합니다.

# Check connection status at a glance
unity-mcp-cli status ./MyUnityProject

# Run an MCP tool directly from the CLI
unity-mcp-cli run-tool rql-query ./MyUnityProject --input '{"query":"objects | where name == \"Player\" | select $ref name transform.position"}'

# Run Unity tests via MCP
unity-mcp-cli run-tool tests-run ./MyUnityProject --input '{"testMode":"EditMode"}'

완전 자동화: 처음부터 연결까지

CLI는 전체 워크플로를 자동화할 수 있습니다 — 프로젝트 생성, 플러그인 설치, Claude Code 구성, Unity 실행, 연결 대기, 도구 실행까지. 다음은 모든 것을 처음부터 설정하는 완전한 스크립트입니다.

# 1. Create a new Unity project
unity-mcp-cli create-project ./MyAIGame --unity 6000.3.1f1

# 2. Install the AI Game Developer plugin
unity-mcp-cli install-plugin ./MyAIGame

# 3. Enable all MCP tools
unity-mcp-cli configure ./MyAIGame --enable-all-tools

# 4. Configure Claude Code MCP integration
unity-mcp-cli setup-mcp claude-code ./MyAIGame

# 5. Open the project with MCP connection
unity-mcp-cli open ./MyAIGame --keep-connected

# 6. Wait for Unity and MCP server to be ready
unity-mcp-cli wait-for-ready ./MyAIGame

# 7. Generate Claude Code skills
unity-mcp-cli setup-skills claude-code ./MyAIGame

# 8. Verify by running a tool
unity-mcp-cli run-tool tests-run ./MyAIGame --input '{"testMode":"EditMode"}'

시작하기

AI Game Developer는 오픈 소스입니다. Unity 패키지를 설치하고, Claude Code를 구성한 뒤 프롬프트를 시작하세요. CLI 도구는 자동화된 워크플로를 위해 npm에서 사용할 수 있습니다. 자세한 설정 방법은 ai-game.dev/docs/quickstart 의 빠른 시작 가이드를 확인하세요.

• AI Game Developer (Unity-MCP): github.com/IvanMurzak/Unity-MCP
• AI 애니메이션 확장: github.com/IvanMurzak/Unity-MCP/blob/main/extensions/Animation/README.md
• CLI 도구: npmjs.com/package/unity-mcp-cli
• 다운로드: ai-game.dev/download
• 다음: AI로 애니메이션 생성하기 — ai-game.dev/blog/generating-unity-animations-with-ai