# Unity MCP — AI Game Developer Wiki

Unity MCP는 Claude Code, Cursor, Copilot 및 기타 AI 에이전트를 Unity 에디터에 연결합니다. 설치, 설정, 도구, 확장 및 CLI는 여기서 시작하세요.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/unity).

Unity MCP는 AI Game Developer의 Unity 플러그인입니다. AI를 Unity 에디터 안에 넣어주는 것으로, Claude Code, Cursor, GitHub Copilot, Codex, Gemini 같은 에이전트가 씬, GameObject, 컴포넌트, 프리팹, 에셋을 읽고 변경하며, C# 스크립트를 작성하고, C# 스니펫을 실행하고, EditMode 및 PlayMode 테스트를 실행하고, Console을 읽고, 직접 볼 수 있는 스크린샷을 찍을 수 있습니다. 이 위키에서는 플러그인을 설치하고, AI 클라이언트를 연결하고, 일상적으로 사용하는 방법을 설명합니다.

## Unity MCP란 무엇인가

Unity MCP는 Unity 패키지 `com.ivanmurzak.unity.mcp`이며, Package Manager에 **AI Game Developer — MCP**로 표시됩니다. 이 패키지는 Unity 에디터 안에서(그리고 원한다면 빌드된 게임 안에서도) 실행됩니다. AI 클라이언트가 외부 도구를 호출할 때 쓰는 공개 표준인 MCP(Model Context Protocol)를 통해 일련의 도구를 노출합니다. 대화하는 에이전트는 그 도구들을 보고, 요청한 작업을 수행하기 위해 호출합니다.

이 플러그인은 Apache-2.0 라이선스의 오픈 소스이며 [Unity-MCP 저장소](https://github.com/IvanMurzak/Unity-MCP)에 있습니다. MCP 및 리플렉션 라이브러리를 Unreal MCP, Godot MCP와 공유하므로, 세 엔진 플러그인은 동일한 방식으로 동작하고 같은 ai-game.dev 계정을 사용합니다.

버전 1.0.0부터 대부분의 에디터 작업은 에디터 데이터에 대한 쿼리 언어인 **RQL**을 통해 이루어집니다. `rql-query` 도구 하나가 읽고, `rql-mutate` 도구 하나가 변경하며, `rql-schema`가 사용 가능한 항목을 설명합니다. 스크린샷, 스크립트, 테스트, 패키지를 다루는 소수의 목적별 도구도 있습니다. [도구 및 RQL](https://ai-game.dev/ko/docs/wiki/unity/tools-and-rql)을 참고하세요.

## 구성 요소들이 맞물리는 방식

| 구성 요소 | 하는 일 |
| --- | --- |
| Unity MCP 플러그인 | Unity 에디터에서 실행되며 AI 도구를 노출하고 MCP 서버에 연결합니다. |
| MCP 서버 | ai-game.dev의 호스팅 서버(기본값인 Cloud 모드) 또는 플러그인이 다운로드해 시작하는 로컬 `gamedev-mcp-server`(Custom 모드)입니다. |
| AI 클라이언트 | Claude Code, Claude Desktop, Cursor, VS Code Copilot, Codex, Gemini, Rider 등입니다. 같은 서버에 연결합니다. |
| `unity-mcp-cli` | 플러그인을 설치하고, 로그인하고, AI 클라이언트 설정을 작성하고, Unity를 열고, 터미널에서 도구를 호출하는 npm 명령줄 도구입니다. |
| AI Game Dev 앱 | 플러그인을 설치하고 에디터를 열며 AI 에이전트를 대신 실행해 주는 데스크톱 앱입니다. |

**Cloud** 모드에서는 에디터와 AI 클라이언트 모두 `https://ai-game.dev/mcp`에 연결하며, ai-game.dev 계정으로 한 번 로그인합니다. **Custom** 모드에서는 플러그인이 사용자 컴퓨터에서 로컬 MCP 서버를 실행하므로 모든 것이 컴퓨터 안에 머뭅니다. [구성](https://ai-game.dev/ko/docs/wiki/unity/configuration)에서 두 가지를 모두 설명합니다.

## 요구 사항 한눈에 보기

- Unity **2022.3** 이상, Unity 6 포함.
- **공백이 없는** 프로젝트 경로(경로에 공백이 있으면 플러그인이 시작 시 오류를 기록합니다).
- 첫 사용 시 인터넷 접속: 플러그인은 NuGet에서 .NET 종속성을, Custom 모드에서는 MCP 서버 바이너리를 다운로드합니다.
- MCP를 지원하는 AI 클라이언트 또는 [AI Game Dev 앱](https://ai-game.dev/docs/app).

## 빠른 시작

가장 쉬운 방법은 데스크톱 앱입니다. [다운로드](https://ai-game.dev/ko/download)하고 로그인한 뒤 Unity 프로젝트를 여세요. 플러그인을 설치하고 연결까지 해 줍니다. [앱 위키](https://ai-game.dev/ko/docs/wiki/app)에서 그 흐름을 다룹니다.

터미널과 직접 고른 AI 클라이언트를 선호한다면, 다음 명령으로 Unity 프로젝트를 연결된 에이전트 상태로 만들 수 있습니다:

```bash
npm install -g unity-mcp-cli
unity-mcp-cli install-plugin ./MyUnityProject
unity-mcp-cli login
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli open ./MyUnityProject
```

그런 다음 에이전트에게 "반지름 2인 원 모양으로 큐브 3개를 만들어 줘"처럼 요청하세요. [시작하기](https://ai-game.dev/ko/docs/wiki/unity/getting-started)에서 같은 단계를 설명과 함께 안내합니다.

## 이 섹션의 페이지

- [설치](https://ai-game.dev/ko/docs/wiki/unity/installation): 플러그인을 설치하는 모든 방법(앱, `unity-mcp-cli`, OpenUPM, `.unitypackage` 설치 프로그램)과 제거 방법.
- [시작하기](https://ai-game.dev/ko/docs/wiki/unity/getting-started): 첫 연결과 첫 프롬프트.
- [AI 클라이언트 연결](https://ai-game.dev/ko/docs/wiki/unity/connecting-ai-clients): Cloud와 로컬 엔드포인트, 로그인, 고정 URL, 각 에이전트용 구성 도구.
- [구성](https://ai-game.dev/ko/docs/wiki/unity/configuration): AI Game Developer 창, 연결 모드, 포트, 설정 파일, 환경 변수 재정의 및 빌드.
- [도구 및 RQL](https://ai-game.dev/ko/docs/wiki/unity/tools-and-rql): 에이전트가 에디터에서 할 수 있는 일.
- [사용자 지정 도구](https://ai-game.dev/ko/docs/wiki/unity/custom-tools): 직접 작성한 C# 메서드를 AI 도구, 프롬프트, 스킬로 만들기, 실행 중인 게임에서도 가능.
- [확장](https://ai-game.dev/ko/docs/wiki/unity/extensions): Animation, Cinemachine, Input System, Navigation, ProBuilder, Terrain, Tilemap, Timeline 등을 위한 선택적 패키지.
- [unity-mcp-cli 참조](https://ai-game.dev/ko/docs/wiki/unity/cli): 모든 명령과 플래그.
- [문제 해결](https://ai-game.dev/ko/docs/wiki/unity/troubleshooting): 흔한 문제의 해결 방법.
- [FAQ](https://ai-game.dev/ko/docs/wiki/unity/faq): 흔한 질문에 대한 짧은 답변.

## 사이트의 다른 자료

- [Unity 도구 카탈로그](https://ai-game.dev/docs/tools/unity) 및 [RQL 참조](https://ai-game.dev/docs/rql).
- [Unity 확장 카탈로그](https://ai-game.dev/docs/extensions/unity).
- 프롬프팅과 프로젝트 설정을 위한 [Unity 모범 사례](https://ai-game.dev/docs/best-practices/unity).
- 지원되는 모든 클라이언트용 구성 스니펫이 있는 [MCP 엔드포인트](https://ai-game.dev/ko/mcp-endpoint-info).
- [인증](https://ai-game.dev/docs/auth), [빠른 시작](https://ai-game.dev/ko/docs/quickstart) 및 [Unity 엔진 페이지](https://ai-game.dev/ko/engines/unity).
- 다른 엔진: [Unreal MCP](https://ai-game.dev/ko/docs/wiki/unreal) 및 [Godot MCP](https://ai-game.dev/ko/docs/wiki/godot).

- [**설치** 데스크톱 앱, unity-mcp-cli, OpenUPM 또는 .unitypackage 설치 프로그램으로 Unity 프로젝트에 Unity MCP(AI Game Developer)를 설치하세요.](https://ai-game.dev/ko/docs/wiki/unity/installation)
- [**시작하기** Unity MCP로 첫 AI 에이전트를 Unity 에디터에 연결하고, 연결을 확인한 뒤 Claude Code, Cursor, Copilot에서 첫 프롬프트를 시험해 보세요.](https://ai-game.dev/ko/docs/wiki/unity/getting-started)
- [**AI 클라이언트 연결하기** Claude Code, Cursor, Copilot, Codex, Gemini 및 기타 MCP 클라이언트를 ai-game.dev 클라우드 엔드포인트나 로컬 서버를 통해 Unity MCP에 연결하세요.](https://ai-game.dev/ko/docs/wiki/unity/connecting-ai-clients)
- [**구성** AI Game Developer 창에서 Unity MCP 구성하기 - Cloud 및 Custom 모드, 로컬 서버, 포트, 전송 방식, 인증, 도구, 재정의, CI.](https://ai-game.dev/ko/docs/wiki/unity/configuration)
- [**도구와 RQL** Unity MCP를 통해 AI 에이전트가 Unity 에디터에서 할 수 있는 일 - RQL 쿼리와 변경, 스크린샷, C# 스크립트, 테스트, 패키지, 프로파일링.](https://ai-game.dev/ko/docs/wiki/unity/tools-and-rql)
- [**사용자 정의 도구** AiTool 특성을 사용해 C#으로 나만의 Unity MCP 도구, 프롬프트, 리소스, 스킬을 작성하고, 메인 스레드에서 실행하며 빌드된 게임에서도 사용하세요.](https://ai-game.dev/ko/docs/wiki/unity/custom-tools)
- [**확장** Unity MCP 확장은 Animation, Cinemachine, Input System, Navigation, ProBuilder, Splines, Terrain, Tilemap, Timeline 및 파티클에 AI 지원을 추가합니다.](https://ai-game.dev/ko/docs/wiki/unity/extensions)
- [**unity-mcp-cli 레퍼런스** unity-mcp-cli 명령 레퍼런스 - Unity MCP 설치, 로그인, AI 에이전트 설정 작성, Unity 헤드리스 실행, 터미널에서 도구와 C# 실행까지.](https://ai-game.dev/ko/docs/wiki/unity/cli)
- [**문제 해결** Unity MCP의 흔한 문제 해결 - AI 클라이언트에 도구가 표시되지 않음, 로그인 및 연결 오류, 서버 다운로드 실패, NuGet DLL 오류, 포트 충돌.](https://ai-game.dev/ko/docs/wiki/unity/troubleshooting)
- [**자주 묻는 질문** Unity MCP에 관한 자주 묻는 질문의 답변 - 지원되는 Unity 버전과 AI 클라이언트, Cloud와 로컬 모드, 비용, 개인정보 보호, 빌드, CI, RQL.](https://ai-game.dev/ko/docs/wiki/unity/faq)

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/unity

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/unity