Unity MCP 완전 가이드: Claude Code·Codex·Gemini·Cursor를 Unity Editor와 연결하기 -

Unity AI 완전 정복 시리즈
1편 — Unity AI Assistant 완전 입문: Ask·Plan·Agent 모드 차이점과 언제 무엇을 쓸까
2편 — Unity MCP 완전 가이드: Claude Code·Codex·Gemini·Cursor를 Unity Editor와 연결하기 (현재 글)
3편 — Unity MCP 커스텀 도구 만들기: McpTool Deep Dive와 4가지 등록 방식
4편 — Unity Skills 시스템으로 AI 워크플로우 자동화하기: SKILL.md 완전 가이드
Appendix — Unity MCP 빌트인 도구 완전 레퍼런스 — 51개 도구 파라미터·활성화 가이드
5편 — Unity AI Assistant Project Overview 자동 생성 — AI가 내 프로젝트를 이해하게 만드는 방법
6편 — Unity AI Assistant × Profiler — 성능 병목을 자연어로 진단하는 완전 가이드

Claude Code나 Codex에서 Unity 프로젝트 폴더를 열어두면 “연결된 것”이라고 생각하기 쉽습니다. 실제로 그 상태에서도 C# 스크립트를 읽고 수정하는 건 가능합니다. 하지만 그건 파일 시스템에 접근하는 것이지 Unity Editor와 “대화”한다고 표현하기는 힘듭니다.

AI와 Unity Editor 사이의 진정한 “대화”는 Unity MCP(Model Context Protocol) Server를 통해서 이루어집니다. “지금 씬에 올라간 오브젝트들의 컴포넌트 목록을 알려줘”, “콘솔에 쌓인 오류 메시지의 원인을 찾아서 문제를 수정해줘” — 이런 요청은 단순히 디스크의 파일을 읽어서는 해결할 수 없습니다. 실행 중인 Unity Editor 자체를 조작해야 합니다. Unity MCP는 Unity Editor를 MCP 서버로 노출해서, Claude Code나 Codex 같은 외부 AI 클라이언트가 에디터 내부 상태를 직접 조회하고 조작할 수 있게 합니다. Unity AI Assistant 2.7(Unity 6.0.66f2 이상)에서 안전하게 사용할 수 있습니다. 다만 Unity AI Assistant는 현재 베타 상태입니다. 베타 특성상 아직 알려진 문제들이 있으며, 동작 방식이 업데이트마다 달라질 수 있습니다. 프로덕션 워크플로우에 바로 편입하기보다는, 가능성을 탐색하는 단계로 접근하는 것을 권장합니다.

TL;DR
– AI가 Unity 프로젝트 폴더를 읽는 것과 Unity Editor를 조작하는 것은 다릅니다. Unity MCP는 후자를 가능하게 합니다 — Unity Editor 자체를 MCP 서버로 노출해 실행 중인 에디터 상태를 AI가 직접 조회·조작합니다.
– 릴레이 바이너리(~/.unity/relay/)가 MCP 프로토콜 ↔ IPC 변환을 담당하며, 플랫폼별 경로가 다릅니다.
– Claude Code 연결: 릴레이 절대 경로를 MCP 설정 파일에 추가 → Unity에서 수동 승인.
– AI Gateway를 사용하면 Unity Editor 안에서 Claude Code를 직접 실행할 수 있고, 별도 연결 승인이 없습니다.
– Unity AI Assistant는 현재 베타입니다. 알려진 버그가 있고 업데이트마다 동작이 달라질 수 있으므로, 프로덕션보다는 탐색 단계로 활용하는 것을 권장합니다.

목차
– Unity MCP란 무엇인가
– 두 종류의 MCP: 방향이 정반대다
– 아키텍처: 브리지·릴레이·IPC 3계층
– Claude Code 연결 설정
– Cursor 연결 설정
– AI Gateway: Unity 창 안에서 Claude Code 실행하기
– 실전 트러블슈팅

Unity MCP란 무엇인가

Unity MCP는 Claude Code, Codex 같은 외부 AI 클라이언트가 Unity Editor의 씬·에셋·스크립트를 직접 조작할 수 있도록 Unity Editor 자체를 MCP 서버로 노출하는 시스템입니다. MCP(Model Context Protocol)는 AI 클라이언트와 서버 사이의 표준 통신 규약이고, Unity는 이 규약을 준수하는 서버 역할을 맡습니다.

“Unity AI Assistant 안에서 Git MCP 서버를 쓰는 것”과는 방향이 반대입니다. 혼동하기 쉬운 두 개념을 먼저 짚고 넘어갑니다.

두 종류의 MCP: 방향이 정반대다

Unity AI Assistant에는 이름이 비슷하지만 완전히 다른 두 가지 MCP 기능이 존재합니다.

구분	MCP Client (Assistant MCP Extentions)	Unity MCP Server
방향	Assistant → 외부 MCP 서버	외부 AI 클라이언트 → Unity Editor
Unity의 역할	MCP 클라이언트	MCP 서버
설정 위치	Edit > Project Settings > AI > Assistant MCP Extensions	Edit > Project Settings > AI > Unity MCP Server
대표 사용 사례	Assistant로 Blender 조작	Claude Code로 Unity 씬 오브젝트 조작

이 포스팅에서 다루는 것은 오른쪽, Unity MCP Server(이하 Unity MCP)입니다. Claude Code나 Codex가 Unity를 “Tools Server”로 바라보고 필요한 Tool을 호출해 Unity Editor에 명령을 내리는 구조입니다.

아키텍처: 브리지·릴레이·IPC 3계층

AI 클라이언트와 Unity MCP Server가 어떤 과정을 거쳐 연결되고 통신하는지 이해하면 활용도 뿐만 아니라 트러블슈팅 또한 훨씬 쉬워집니다.

릴레이 계층: stdio ↔ IPC 변환

AI 클라이언트는 MCP 표준에 따라 stdio(Standard Input/Output, 표준 입출력)로 도구 서버와 통신합니다. 그런데 Unity Editor 내부의 MCP 브리지가 사용하는 채널은 IPC((Inter-Process Communication, 프로세스 간 통신)입니다. 이 두 프로토콜은 직접 연결할 수 없기 때문에 중간에 변환자가 필요합니다.
Relay 바이너리(~/.unity/relay/)가 이 역할을 담당합니다. AI 클라이언트가 relay 프로세스를 자식 프로세스로 실행한 뒤 stdio로 MCP 메시지를 전달하면, relay는 이를 IPC 형식으로 변환해 Unity Editor의 MCP 브리지에 전달합니다. Unity 첫 실행 시 ServerInstaller가 플랫폼에 맞는 릴레이 바이너리를 ~/.unity/relay/ 경로에 자동으로 설치합니다.

IPC 계층: 플랫폼별 로컬 소켓

Unity Editor가 시작되면 MCP 브리지가 로컬 IPC 채널을 자동으로 열고 릴레이의 연결을 기다립니다. IPC 구현은 플랫폼마다 다릅니다.

플랫폼	IPC 방식
Windows	Named Pipe
macOS / Linux	Unix Domain Socket

IPC는 같은 머신의 프로세스 간 통신이므로 네트워크 설정이 필요하지 않습니다. 릴레이 바이너리와 Unity Editor는 반드시 같은 머신에서 실행 중이어야 합니다.

연결이 맺어지기까지의 흐름 (Windows 기준)

① Unity Editor 시작 — MCP 브리지가 Named Pipe를 열고, 연결 정보를 ~/.unity/mcp/connections/에 기록합니다.

# ~/.unity/mcp/connections/bridge-9beba166-74996.json
{
  "connection_type": "named_pipe",
  "connection_path": "\\\\.\\pipe\\unity-mcp-9beba166-74996",
  "project_path": "D:\\Unity\\Projects\\MyGame",
  "editor_pid": 74996
}

② AI 클라이언트가 relay를 자식 프로세스로 실행 — Claude Code가 MCP 설정 파일의 command 경로로 relay_win.exe를 띄우고 stdio 채널을 확보합니다.

③ relay가 bridge 파일을 읽고 Named Pipe에 연결 — relay는 ~/.unity/mcp/connections/bridge-*.json을 스캔해 connection_path(\\.\pipe\unity-mcp-9beba166-74996)로 Named Pipe 연결을 시도합니다. Unity Editor가 이 연결 요청을 수락하면 IPC 채널이 완성됩니다.

④ AI 클라이언트 ↔ Unity Editor 통신 개시 — Claude Code가 stdio로 tools/list를 relay에 전달하고, relay는 이를 IPC로 변환해 Unity MCP 브리지에 포워딩합니다. 브리지가 등록된 도구 목록을 반환하면 Claude Code는 Unity Editor와 완전히 연결된 상태가 됩니다.

브리지 계층: McpToolRegistry

Unity Editor 내부의 MCP 브리지는 McpToolRegistry를 중심으로 동작합니다. 패키지 설치 시 Unity_ReadConsole, get_components 등의 빌트인 도구가 자동으로 등록되며, [McpTool] 어트리뷰트로 선언한 커스텀 메서드도 동일한 레지스트리에 등록되어 AI 클라이언트에 노출됩니다. AI가 도구를 호출하면 브리지가 레지스트리에서 대상 도구를 찾아 Unity Editor API를 실행하고, 결과를 IPC → relay → MCP 경로로 되돌려 보냅니다.

연결 승인 방식
– 외부 MCP 클라이언트 직접 연결 — 최초 연결 시 Project Settings > AI > Unity MCP > Pending Connections에서 수동 승인이 필요합니다. 승인된 클라이언트는 이후 세션부터 자동으로 재연결됩니다.
– AI Gateway — 수동 승인 없이 자동으로 연결됩니다.

올바른 도구 탐색과 호출 흐름

AI 클라이언트가 relay에 연결되면 곧바로 tools/list 요청을 보냅니다. 이 요청은 relay → IPC → Unity MCP 브리지를 거쳐 McpToolRegistry에 도달하고, 레지스트리에 등록된 모든 도구의 이름·설명·입력 스키마를 목록으로 반환합니다. AI 클라이언트는 이 목록을 컨텍스트로 보유합니다.

이후 사용자의 요청이 들어오면 LLM이 각 도구의 description 필드를 읽고 의미적으로 매칭해 어떤 도구를 쓸지 결정합니다. 알고리즘이 아니라 LLM의 추론이 도구를 선택합니다. 선택이 끝나면 tools/call 요청을 relay에 전달하고, IPC → 브리지 → 해당 도구 메서드 실행 → 결과 반환 순서로 처리됩니다.

description이 곧 라우팅 키입니다. [McpTool] 어트리뷰트에 설명을 구체적으로 작성할수록 LLM이 올바른 상황에 해당 도구를 선택할 가능성이 높아집니다.

Claude Code 연결 설정

1단계: 패키지 설치 확인

Package Manager에서 com.unity.ai.assistant가 설치되어 있어야 합니다. Unity AI Assistant는 Unity 6.0.60f1 이상에서 동작하지만, 해당 버전에는 유효한 서명을 가진 패키지가 잘못된 서명으로 표시되는 버그가 있습니다. 실제로는 Unity 6.0.66f2 이상을 사용하는 것이 안전합니다. Generators(에셋 생성 도구)를 사용할 경우 Unity 6.3(6000.3) 이상이 필요하며, 동일한 이유로 6.3.5f2 이상을 권장합니다.

2단계: Unity MCP 서버 시작

Edit > Project Settings > AI > Unity MCP Server로 이동합니다. Status 항목이 Running이면 준비 완료입니다. Stopped라면 Start 버튼을 클릭합니다.

3단계: Claude Code 설정 파일 편집

MCP 서버 설정은 범위에 따라 두 파일 중 하나에 추가합니다. 파일이 없을 시 새 파일을 생성 후 설정하면 됩니다.

범위	파일 위치	특징
프로젝트	프로젝트 루트/`.mcp.json`	git 커밋 가능, 팀 전체 공유, 개인 사용시 .gitignore 등록
현재 사용자	`~/.claude.json`	현재 계정의 모든 프로젝트에 적용

~/.claude.json 경로는 OS마다 다릅니다.

OS	경로
Windows	`C:\Users\YourName\.claude.json`
macOS	`/Users/YourName/.claude.json`
Linux	`/home/YourName/.claude.json`

relay 경로는 머신마다 절대 경로가 다르므로 .mcp.json을 git에 올릴 경우 팀원 각자가 자신의 경로로 수정해야 합니다. 개인용으로 Unity MCP Server를 사용할 목적이라면 .mcp.json을 .gitignore에 추가하여 다른 팀원의 설정이 망가지는 것을 방지할 필요가 있습니다. 혹은 Claude Code의 글로벌 설정 파일인 ~/.claude.json을 수정하면 됩니다. 선택한 파일에 아래 내용을 추가합니다.

Windows:

{
  "mcpServers": {
    "unity-mcp": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp"]
    }
  }
}

macOS (Apple Silicon):

{
  "mcpServers": {
    "unity-mcp": {
      "command": "/Users/YourName/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64",
      "args": ["--mcp"]
    }
  }
}

~ 틸드 표기를 클라이언트가 확장하지 않을 수 있으므로 반드시 절대 경로를 사용합니다. 설정 실패의 가장 흔한 원인이므로 설정을 마친 후에도 Unity MCP Server가 정상동작하지 않는다면 가장 먼저 절대경로로 작성 되었는지 확인합니다.

플랫폼별 릴레이 경로

플랫폼	릴레이 실행 파일 경로
Windows	`%USERPROFILE%\.unity\relay\relay_win.exe`
macOS (Apple Silicon)	`~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64`
macOS (Intel)	`~/.unity/relay/relay_mac_x64.app/Contents/MacOS/relay_mac_x64`
Linux	`~/.unity/relay/relay_linux`

4단계: 연결 승인

Claude Code를 시작하면 Unity Editor에 New MCP Connection 승인을 위한 창이 뜨고, Project Settings > AI > Unity MCP Server > Pending Connections 섹션에 연결 요청이 나타납니다. Accept를 클릭합니다. 승인된 클라이언트는 이후 세션부터 자동으로 재연결됩니다.

5단계: 연결 테스트

Claude Code에서 아래 프롬프트를 입력해 도구 호출이 정상 작동하는지 확인합니다.

Read the Unity console messages and summarize any warnings or errors.

Claude Code와 Unity MCP Server가 성공적으로 연결되었다면, Unity_ReadConsole 도구가 호출되어 Unity 콘솔 출력을 Claude Code가 실행중인 CLI로 가져옵니다.

Cursor 연결 설정

Cursor는 Claude Code와 MCP 설정 구조가 동일합니다. Cursor의 MCP 설정 파일에 같은 형식으로 릴레이 바이너리 경로를 지정합니다.

{
  "mcpServers": {
    "unity-mcp": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp"]
    }
  }
}

Cursor CLI 2026.02.13 이상이 필요합니다.

특정 Unity 인스턴스 지정

Unity 프로젝트를 여러 개 동시에 열어 놓은 경우, --project-path 인자로 대상 인스턴스를 지정할 수 있습니다.

{
  "mcpServers": {
    "unity-mcp": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp", "--project-path", "D:\\MyUnityProject"]
    }
  }
}

지정 방법	인자	환경 변수
프로젝트 경로	`--project-path <path>`	`UNITY_PROJECT_PATH`
에디터 PID	`--instance-id <pid>`	`UNITY_INSTANCE_ID`

AI Gateway: Unity AI Assistant에서 Claude Code 실행하기

별도의 AI 클라이언트를 사용하지 않고 Unity Assistant 창 안에서 Claude Code나 Codex를 바로 사용하고 싶다면 AI Gateway를 사용합니다. AI Gateway는 에이전트 선택기(K 컴포넌트)에서 전환하며, Unity 에디터 안에서 제3자 코딩 에이전트를 실행하는 기능입니다.

AI Gateway로 연결하면 MCP 직접 연결과 달리 자동으로 승인됩니다. 별도 Pending Connections 승인 절차가 없습니다.

에이전트	환경 변수	버전
Claude Code	`ANTHROPIC_API_KEY`	2.1.45 이상, 별도 설치 필요
Cursor CLI	—	2026.02.13 이상, 별도 설치 필요
Gemini CLI	`GEMINI_API_KEY`	Unity 번들 (별도 설치 불필요)
Codex CLI	`OPENAI_API_KEY`	Unity 번들 (별도 설치 불필요)

에이전트 공통 설정 절차

Unity > Settings > Preferences > AI > Gateway 이동
Agent Type 목록에서 사용할 에이전트 선택
미설치 에이전트는 배너의 링크로 설치 (Gemini CLI · Codex CLI는 Unity 번들 제공으로 이 단계 생략)
Environment Variables 확장 후 Add Variable 클릭 → 위 표의 환경 변수명과 API 키 입력
Cursor는 환경 변수 없이 설치만으로 동작

AI Gateway는 Unity Editor 창 안에서 에이전트를 통합하는 빠른 진입점입니다. MCP 직접 연결은 기존 Claude Code·Cursor 환경을 그대로 유지하면서 Unity 도구만 추가하는 방식입니다.

실전 트러블슈팅

브리지가 시작되지 않음 (Stopped 상태)

증상: Project Settings > AI > Unity MCP Server 페이지에 Stopped 표시, 클라이언트가 연결되지 않음.

확인 순서:
1. Unity Console에 컴파일 오류가 있는지 확인합니다. 컴파일 오류가 있으면 브리지가 시작되지 않습니다.
2. com.unity.ai.assistant 패키지가 Package Manager에 설치되어 있는지 확인합니다.
3. Project Settings > AI > Unity MCP Server에서 Start 버튼을 직접 클릭합니다.
4. 위 세 가지를 확인했음에도 해결되지 않으면 Unity Editor를 재시작합니다.

릴레이 바이너리가 없음

증상: 클라이언트 설정 파일의 command 경로에 파일이 존재하지 않음.

원인: Unity Editor 시작 시 ServerInstaller가 바이너리 설치를 완료하지 못한 경우입니다.

해결 순서:
1. Unity Editor를 재시작합니다(설치 프로그램이 재실행됩니다).
2. Packages/com.unity.ai.assistant/RelayApp~/ 폴더에서 바이너리를 직접 확인합니다.
3. Unity Console에 설치 관련 경고가 있는지 확인합니다.
4. Project Settings > AI > Unity MCP의 Locate Server 버튼으로 수동 경로를 지정합니다.

도구가 발견되지 않음

커스텀 도구를 [McpTool] 어트리뷰트로 등록했는데 클라이언트에서 보이지 않는 경우입니다.

체크리스트:
– Unity Console에 컴파일 오류 없음을 확인합니다.
– 도구 메서드가 public static인지, [McpTool] 어트리뷰트가 있는지 확인합니다.
– Project Settings > AI > Unity MCP > Tools 섹션에서 해당 도구가 활성화되어 있는지 확인합니다.
– Show Debug Logs 옵션을 켜면 도구 발견 과정을 콘솔에서 추적할 수 있습니다.

여러 Unity Editor 인스턴스가 실행 중일 때

증상: 명령을 실행했는데 다른 프로젝트의 Unity Editor에서 반응이 나타남.

원인 — 릴레이의 에디터 탐색 방식: Unity Editor가 시작되면 ~/.unity/mcp/connections/ 폴더에 연결 파일을 생성합니다.

~/.unity/mcp/connections/
  bridge-7ba777b2-65156.json   ← 프로젝트 A (pid 65156)
  bridge-9beba166-74996.json   ← 프로젝트 B (pid 74996)
  bridge-cf5129b7-83800.json   ← 프로젝트 C (pid 83800)

각 파일 안에는 named pipe 경로, 프로젝트 경로, 에디터 PID가 담겨 있습니다.

{
  "connection_type": "named_pipe",
  "connection_path": "\\\\.\\pipe\\unity-mcp-9beba166-74996",
  "project_path": "D:\\Unity\\Projects\\MyGame",
  "editor_pid": 74996
}

릴레이는 이 폴더의 bridge-*.json 파일을 파일명 알파벳 순으로 스캔해서 첫 번째 파일의 named pipe에 연결합니다. 즉, 실행 순서가 아니라 파일명에 포함된 UUID의 알파벳 순서가 기본 연결 대상을 결정합니다. UUID는 프로젝트마다 고정값이므로 어떤 프로젝트가 먼저 연결될지 예측하기 어렵습니다.

해결 방법: 릴레이 바이너리 인자 또는 환경 변수로 연결 대상 에디터를 명시합니다.

지정 방법	커맨드 라인 인자	환경 변수
프로젝트 경로 지정	`--project-path <path>`	`UNITY_PROJECT_PATH`
에디터 PID 지정	`--instance-id <pid>`	`UNITY_INSTANCE_ID`

PID는 ~/.unity/mcp/connections/bridge-*.json 파일의 editor_pid 필드 또는 파일명 끝 숫자에서 확인할 수 있습니다. 커맨드 라인 인자가 환경 변수보다 우선합니다. 다중 에디터 환경에서는 프로젝트마다 별도의 MCP 설정 파일을 두고 --project-path로 각 프로젝트를 명시하는 것을 권장합니다.

.mcp.json 설정 예시 (--project-path 사용):

{
  "mcpServers": {
    "unity": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp", "--project-path", "D:\\MyUnityProject"]
    }
  }
}

디버그 로그 활성화

트러블슈팅 중에는 Project Settings > AI > Unity MCP Server에서 Show Debug Logs를 체크합니다. 연결 시도, 도구 발견, 명령 실행 추적, 오류 정보가 Unity Console에 출력됩니다.

마무리

이 포스팅은 Unity AI 완전 정복 시리즈의 2편입니다. 1편에서는 Unity AI Assistant를 에디터 안에서 사용하는 방법(Ask·Plan·Agent 모드)을 다뤘고, 이번 2편에서는 같은 패키지가 제공하는 Unity MCP를 통해 Claude Code·Codex 같은 외부 AI 클라이언트를 연결하는 방법을 다뤘습니다.

Claude Code가 Unity 씬을 직접 읽고, 콘솔 오류를 실시간으로 확인하고, 에셋을 조작하는 워크플로우 — Unity AI가 없었다면 별도 플러그인을 서너 개 연결하고도 이 수준의 통합은 불가능했을 겁니다.

설정 자체는 릴레이 바이너리 경로 하나만 잡으면 끝입니다. 베타 기간인 만큼 버전 업데이트마다 동작이 달라질 수 있으니, 공식 릴리즈 노트를 주기적으로 확인하는 것을 권장합니다.

커스텀 MCP 도구 작성([McpTool] 어트리뷰트 활용)이나 Skills 시스템을 통한 워크플로우 자동화에 관심이 있다면, 다음 포스팅에서 이어서 다루겠습니다.

더 깊이 공부하려면

이 글을 쓰면서 직접 확인한 공식 문서들입니다.

Unity MCP Overview — Unity Docs
브리지·릴레이·IPC 3계층 아키텍처의 공식 설명. 이 포스팅의 구조 설명 근거.
Unity MCP Get Started — Unity Docs
Claude Code·Cursor 연결 설정 절차 원문. 플랫폼별 릴레이 경로 목록 포함.
Unity MCP Troubleshooting — Unity Docs
Unity MCP 브리지 7가지 문제 해결 원문.
AI Gateway Overview — Unity Docs
AI Gateway 지원 에이전트 목록과 최소 버전 요건.
Unity MCP Tool Registration — Unity Docs
[McpTool] 어트리뷰트로 커스텀 도구를 등록하는 4가지 방식.

Unity MCP 완전 가이드: Claude Code·Codex·Gemini·Cursor를 Unity Editor와 연결하기