Unity MCP Server 설정 방법 (2026)

Unity MCP Server는 Unity 게임 엔진을 Claude, Cursor 및 기타 MCP 호환 도구와 같은 AI 어시스턴트에 연결합니다. 즉, AI 어시스턴트가 자연어를 통해 직접 Unity 씬 계층 구조(Hierarchy)를 검사하고, 컴포넌트 속성을 읽고, GameObject를 생성 및 수정하고, 에셋을 관리하며, 플레이 모드를 실행하고, C# 스크립트까지 실행할 수 있게 됩니다. 이 가이드에서는 전체 설정 과정과 실제 활용 방법을 안내합니다.

Unity MCP Server란 무엇인가요?

MCP(Model Context Protocol)는 Anthropic에서 개발한 오픈 표준으로, AI 어시스턴트를 외부 도구 및 데이터 소스에 연결하기 위해 만들어졌습니다. Unity MCP Server는 이 프로토콜을 Unity Editor 전용으로 구현하여 Unity의 기능을 AI 모델이 호출할 수 있는 도구로 노출합니다.

주요 기능

기능	설명
씬 검사 (Scene Inspection)	전체 씬 계층 구조, GameObject 및 컴포넌트 정보 읽기
오브젝트 조작	GameObject 생성, 이동, 회전, 크기 조절 및 삭제
컴포넌트 관리	컴포넌트 및 속성 추가, 제거, 수정
에셋 작업	프로젝트 에셋 임포트, 검색 및 정리
스크립트 생성	C# 스크립트 생성 및 GameObject에 부착
플레이 모드 제어	플레이 모드 시작, 정지 및 일시정지
콘솔 읽기	Unity 콘솔 로그 및 오류 읽기
빌드 관리	대상 플랫폼에 대한 빌드 트리거
프리팹 작업	프리팹 생성 및 인스턴스화
머티리얼 편집	머티리얼, 셰이더 및 텍스처 수정

사전 요구 사항

Unity MCP Server를 설정하기 전에 다음 항목이 필요합니다:

Unity Editor 2022.3 LTS 이상 (2023.x 또는 6000.x 버전도 지원)
Node.js 18 이상
Claude Desktop, Claude Code, 또는 Cursor (모든 MCP 호환 AI 클라이언트)
에디터에서 열려 있는 Unity 프로젝트

Node.js 버전 확인:

node --version
# v18.x.x 이상

1단계: Unity MCP 패키지 설치

옵션 A: Unity Package Manager를 통한 설치 (권장)

Unity 프로젝트를 엽니다.
Window > Package Manager로 이동합니다.
왼쪽 상단의 + 버튼을 클릭합니다.
Add package from git URL을 선택합니다.
다음 패키지 URL을 입력합니다:

https://github.com/anthropics/unity-mcp-server.git

Add를 클릭하고 설치가 완료될 때까지 기다립니다.

옵션 B: manifest.json을 통한 설치

프로젝트의 Packages/manifest.json 파일을 열고 다음 의존성을 추가합니다:

{
  "dependencies": {
    "com.anthropic.mcp-server": "https://github.com/anthropics/unity-mcp-server.git",
    ...
  }
}

파일을 저장하면 Unity가 자동으로 패키지를 다운로드하고 설치합니다.

옵션 C: 수동 설치

# 리포지토리 클론
git clone https://github.com/anthropics/unity-mcp-server.git

# 패키지를 프로젝트의 Packages 폴더로 복사
cp -r unity-mcp-server/package ~/your-unity-project/Packages/com.anthropic.mcp-server

2단계: Unity에서 MCP 서버 활성화

설치 후 Unity Editor에서 서버를 활성화해야 합니다:

Edit > Preferences (macOS: Unity > Preferences)로 이동합니다.
왼쪽 패널에서 MCP Server를 선택합니다.
Enable MCP Server를 On으로 전환합니다.
Port 번호를 확인합니다 (기본값: 6400).
보안을 위해 필요한 경우 Authentication Token을 설정합니다.

Unity Console에서 다음과 같은 확인 메시지가 표시되어야 합니다:

[MCP Server] Started on port 6400
[MCP Server] Waiting for connections...

구성 옵션

설정 항목	기본값	설명
Enable MCP Server	Off	서버 켜기/끄기 토글
Port	6400	MCP 연결을 위한 TCP 포트
Auth Token	(비어 있음)	선택 사항인 인증 토큰
Allow Script Execution	Off	AI가 임의의 C# 코드를 실행하도록 허용
Allow File Operations	On	AI가 프로젝트 파일을 생성/수정하도록 허용
Allow Build Triggers	Off	AI가 빌드를 시작하도록 허용
Verbose Logging	Off	모든 MCP 요청을 Unity Console에 기록

보안 주의: "Allow Script Execution" 옵션은 주의해서 사용하십시오. 이 옵션을 켜면 AI가 Unity 에디터 내에서 임의의 C# 코드를 실행할 수 있습니다. 신뢰할 수 있는 로컬 개발 환경에서만 활성화하십시오.

3단계: AI 클라이언트 구성

Claude Desktop 구성

Claude Desktop 설정 파일을 편집합니다:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/unity-mcp-bridge",
        "--port",
        "6400"
      ]
    }
  }
}

저장 후 Claude Desktop을 재시작합니다.

Claude Code 구성

프로젝트 또는 글로벌 MCP 설정에 서버를 추가합니다:

claude mcp add unity \
  --command "npx" \
  --args "-y" "@anthropic-ai/unity-mcp-bridge" "--port" "6400"

또는 프로젝트 루트의 .mcp.json에 추가합니다:

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/unity-mcp-bridge", "--port", "6400"]
    }
  }
}

Cursor 구성

프로젝트의 .cursor/mcp.json에 추가합니다:

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/unity-mcp-bridge", "--port", "6400"]
    }
  }
}

4단계: 연결 확인

AI 어시스턴트와 대화를 시작하여 연결을 테스트합니다:

내 Unity 프로젝트가 보이나요? 현재 씬에 있는 GameObject 목록을 보여주세요.

모든 설정이 올바르다면, AI가 Unity에 쿼리를 보내고 씬 계층 구조를 반환할 것입니다.

실용적인 활용 사례

1. 씬 설정 및 프로토타이핑

AI에게 씬 레이아웃 구축을 요청할 수 있습니다:

간단한 플랫포머 레벨 레이아웃을 만들어줘:
- (0, 0, 0) 위치에 크기 (20, 1, 5)인 바닥(Ground) 평면 생성
- y=2에서 y=8 사이의 다양한 높이에 5개의 공중 발판 생성
- (0, 2, 0) 위치에 빨간색 구체를 플레이어 스폰 지점으로 배치
- (18, 3, 0) 위치에 초록색 큐브와 회전 애니메이션이 있는 목표 지점 생성
Directional Light를 추가하고 카메라를 orthographic 뷰로 설정해줘.

2. 컴포넌트 디버깅

게임이 제대로 작동하지 않을 때:

씬에 "Player" GameObject가 있어. CharacterController 컴포넌트가
"Enemy" 태그가 붙은 오브젝트와의 충돌을 감지하지 못하는 것 같아.
Player의 컴포넌트와 Enemy 오브젝트를 검사해서 설정이 잘못된 부분이 있는지 확인해줘.

3. 자동 C# 스크립트 생성

다음 기능을 가진 "CoinCollector" C# 스크립트를 생성해줘:
- "Coin" 태그가 붙은 오브젝트와의 트리거 충돌 감지
- 수집 사운드 이펙트 재생
- 정적(static) 점수 카운터 증가
- 코인 오브젝트 파괴
- 새로운 점수로 UI Text 요소 업데이트
이 스크립트를 Player GameObject에 부착해줘.

AI가 스크립트를 생성하고, Assets 폴더에 저장한 뒤, 지정된 GameObject에 부착합니다.

4. 에셋 정리

내 Assets 폴더를 정리해줘:
- 모든 .png 및 .jpg 파일을 Assets/Art/Textures 폴더로 이동
- 모든 .fbx 및 .obj 파일을 Assets/Art/Models 폴더로 이동
- 모든 .cs 스크립트를 네임스페이스별로 그룹화하여 Assets/Scripts 폴더로 이동
- 모든 .wav 및 .mp3 파일을 Assets/Audio 폴더로 이동
폴더가 없다면 새로 생성해줘.

5. 성능 분석

플레이 모드로 진입해서 10초 동안 씬을 모니터링해줘.
콘솔 경고나 오류, 대략적인 프레임 레이트를 보고하고,
메쉬 렌더러의 버텍스 수가 10,000개 이상인 GameObject가 있다면 알려줘.

6. 일괄 작업

"Default-Material"을 사용하는 MeshRenderer 컴포넌트를 가진 씬 내 모든
GameObject를 찾아줘. 해당 머티리얼을 Assets/Materials/ 폴더에 있는
"StandardPBR" 머티리얼로 교체해줘.

사용 가능한 MCP 도구 참조

Unity MCP Server에서 제공하는 주요 도구는 다음과 같습니다:

unity_get_scene_hierarchy    - 전체 씬 트리 가져오기
unity_get_gameobject         - 특정 GameObject의 상세 정보 가져오기
unity_create_gameobject      - 새로운 GameObject 생성
unity_delete_gameobject      - GameObject 삭제
unity_set_transform          - 위치(Position), 회전(Rotation), 크기(Scale) 설정
unity_add_component          - GameObject에 컴포넌트 추가
unity_remove_component       - 컴포넌트 제거
unity_set_component_property - 컴포넌트 속성 수정
unity_find_assets            - 프로젝트 에셋 검색
unity_create_script          - 새로운 C# 스크립트 파일 생성
unity_attach_script          - GameObject에 스크립트 부착
unity_enter_play_mode        - 플레이 모드 시작
unity_exit_play_mode         - 플레이 모드 정지
unity_read_console           - 콘솔 로그 항목 읽기
unity_execute_code           - 에디터에서 임의의 C# 코드 실행
unity_create_prefab          - GameObject로부터 프리팹 생성
unity_instantiate_prefab     - 씬에 프리팹 인스턴스화
unity_set_material           - 렌더러에 머티리얼 할당
unity_trigger_build          - 대상 플랫폼 빌드 시작

문제 해결 (Troubleshooting)

문제	해결 방법
"Cannot connect to Unity"	Unity Preferences에서 MCP Server가 활성화되어 있는지, 포트 번호가 클라이언트 설정과 일치하는지 확인하십시오.
"Port 6400 already in use"	Unity Preferences와 AI 클라이언트 설정 모두에서 포트 번호를 변경하십시오.
AI가 씬 변경 사항을 보지 못함	Unity 에디터가 활성 상태(Foreground)인지 확인하십시오. 일부 작업은 포커스가 필요할 수 있습니다.
스크립트 컴파일 실패	스크립트 생성 후 Unity Console에서 C# 컴파일 오류가 있는지 확인하십시오.
"Permission denied" 오류	Unity MCP 설정에서 관련 권한(File Operations, Script Execution 등)을 활성화하십시오.
응답 속도 느림	수천 개의 오브젝트가 있는 대규모 씬은 직렬화에 시간이 걸릴 수 있습니다. 전체 계층 구조 대신 특정 오브젝트를 쿼리해 보십시오.

보안 권장 사항

상용 환경에서는 인증 토큰을 사용하십시오. Unity MCP Preferences에서 인증 토큰을 설정하고 클라이언트 구성에 포함하십시오.
기본적으로 스크립트 실행 기능을 비활성화하십시오. AI가 C# 코드를 직접 작성하고 실행해야 하는 구체적인 상황에서만 활성화하십시오.
네트워크에 포트를 노출하지 마십시오. 보안이 보장된 팀 환경이 아니라면 MCP 서버는 localhost의 연결만 수락해야 합니다.
AI가 생성한 스크립트를 실행 전 검토하십시오. 최고의 AI라도 프로젝트에 부착하기 전에 생성된 C# 코드를 항상 읽고 확인해야 합니다.

결론

Unity MCP Server는 AI 어시스턴트에게 Unity 에디터에 대한 직접적인 접근 권한을 부여함으로써 게임 개발 워크플로우를 혁신합니다. 텍스트로 씬을 설명하고 코드를 복사해서 붙여넣는 대신, Claude나 Cursor가 프로젝트 내에서 직접 오브젝트를 검사하고, 스크립트를 생성하며, 변경 사항을 실시간으로 검증하도록 할 수 있습니다.

캐릭터 애니메이션, 컷신 비디오, 성우 연기 또는 홍보용 콘텐츠와 같이 AI 생성 시각적 에셋이 필요한 게임 개발자의 경우, Hypereal AI를 통해 AI 비디오 생성, 말하는 아바타, 이미지 생성 및 음성 복제 기능을 합리적인 가격의 API로 이용할 수 있어 게임 개발 파이프라인을 더욱 가속화할 수 있습니다.