# Unity 플러그인 설정 — AI Game Developer

Unity용 AI Game Developer 플러그인을 단계별로 설정합니다. 설치하고, 로그인하고, AI 클라이언트를 연결하고, 확장을 추가하세요. 자주 발생하는 문제의 해결 방법도 함께 안내합니다.

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

Unity · 수동 설정

빈 Unity 프로젝트에서 에디터 안에서 작업하는 AI 에이전트까지, 필요한 모든 과정을 담았습니다. 플러그인을 설치하고, 로그인하고, AI 클라이언트를 연결하고, 필요한 확장을 추가하세요. 간단한 버전은 [Unity 설치 페이지](https://ai-game.dev/ko/engines/unity)에서 확인할 수 있습니다.

01

## 시작하기 전에

Unity 2022.3 이상, ai-game.dev 계정, AI 클라이언트가 필요합니다.

- **Unity 2022.3 이상** — Unity 6도 지원합니다.
- 기본 Cloud 연결에 필요한 **ai-game.dev 계정** — 없다면 [계정을 만드세요](https://ai-game.dev/create-account).
- **AI 클라이언트** — AI Game Dev 앱, Claude Code, Cursor, Copilot, Gemini, Codex 또는 [지원되는 MCP 클라이언트 14개](https://ai-game.dev/ko/mcp-endpoint-info) 중 아무거나 사용할 수 있습니다.
- **처음 열 때 인터넷 연결** — 플러그인이 NuGet에서 .NET 패키지를 내려받습니다.

02

## 플러그인 설치

앱, CLI, OpenUPM, 설치 패키지 중 하나를 선택하세요.

쉬운 방법부터 네 가지로 플러그인을 추가할 수 있습니다:

**데스크톱 앱**

[AI Game Dev 앱](https://ai-game.dev/ko/download)에서 Unity 프로젝트를 열고 **Install Package**를 클릭합니다. 앱이 OpenUPM에서 최신 플러그인을 설치하고 로그인까지 처리하며 에이전트를 설정합니다.

**unity-mcp-cli**

npm에서 CLI를 설치한 다음 프로젝트에 플러그인을 추가합니다(`Packages/manifest.json`은 자동으로 수정됩니다):

```bash
npm install -g unity-mcp-cli
unity-mcp-cli install-plugin ./MyUnityProject
```

**OpenUPM 설치**

OpenUPM CLI가 있다면 프로젝트 폴더에서 다음을 실행합니다:

```bash
openupm add com.ivanmurzak.unity.mcp
```

OpenUPM CLI가 없나요? `Packages/manifest.json`에 스코프 레지스트리를 추가한 다음 **Window → Package Manager**에서 패키지를 추가합니다:

```json
{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.ivanmurzak", "extensions.unity"]
    }
  ]
}
```

**.unitypackage 파일**

설치 파일을 내려받아 **Assets → Import Package → Custom Package…**로 가져옵니다. 프로젝트에 OpenUPM 레지스트리와 패키지가 추가되므로 이후 업데이트는 Package Manager에서 받습니다.

[⬇ AI-Game-Dev-Installer.unitypackage 내려받기](https://github.com/IvanMurzak/Unity-MCP/releases/latest/download/AI-Game-Dev-Installer.unitypackage)

03

## 창을 열고 로그인

AI Game Developer 창을 열고 계정으로 한 번 로그인합니다.

1. Unity에서 **Window → AI Game Developer — MCP**를 선택합니다(`Ctrl+Alt+A`, macOS에서는 `Cmd+Option+A`).
2. **Connection** 스위치를 **Cloud**에 둔 채 **Authorize**를 클릭합니다.
3. 브라우저에 짧은 코드와 함께 ai-game.dev 로그인 페이지가 열립니다. 코드가 일치하는지 확인하고 승인합니다.
4. Unity 상태가 **Connected**로 바뀝니다.

로그인 정보는 컴퓨터 전체에 저장됩니다. 앱이나 `unity-mcp-cli login`으로 이미 로그인했다면 에디터가 그 정보를 그대로 사용하므로 이 단계는 건너뛸 수 있습니다.

04

## AI 클라이언트 연결

명령 한 번, 또는 창에서 클릭 한 번이면 클라이언트 설정이 기록됩니다.

창에서 AI 에이전트 옆의 **Configure**를 클릭하거나 터미널에서 `setup-mcp`를 실행합니다. 둘 다 프로젝트에 고정된 URL과 프로젝트 키를 클라이언트 설정에 기록하므로 곧바로 연결됩니다:

```bash
# Claude Code — use your agent's id (cursor, codex, gemini, vscode-copilot, …)
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
```

설정이 바뀐 뒤에는 AI 클라이언트를 다시 시작합니다. 다른 클라이언트와 수동 설정은 [AI 클라이언트 연결](https://ai-game.dev/ko/docs/wiki/unity/connecting-ai-clients)과 [MCP 엔드포인트 페이지](https://ai-game.dev/ko/mcp-endpoint-info)를 참고하세요.

05

## 확장 추가(선택 사항)

Animation, Cinemachine, Terrain, Timeline 등 — 필요한 것만 설치합니다.

각 확장은 독립적인 Unity 패키지입니다. 설치되는 즉시 RQL을 통해 에이전트가 Unity의 한 영역을 익히도록 합니다. 인기 있는 확장 몇 가지는 다음과 같습니다:

- [AI Animation](https://ai-game.dev/docs/extensions/unity/animation) 기능 3개
  ```bash
  openupm add com.ivanmurzak.unity.mcp.animation
  ```
- [AI Cinemachine](https://ai-game.dev/docs/extensions/unity/cinemachine) 기능 4개
  ```bash
  openupm add com.ivanmurzak.unity.mcp.cinemachine
  ```
- [AI Terrain](https://ai-game.dev/docs/extensions/unity/terrain) 기능 4개
  ```bash
  openupm add com.ivanmurzak.unity.mcp.terrain
  ```
- [AI Timeline](https://ai-game.dev/docs/extensions/unity/timeline) 기능 5개
  ```bash
  openupm add com.ivanmurzak.unity.mcp.timeline
  ```

[Unity 확장 10개 모두 →](https://ai-game.dev/docs/extensions/unity)

?

## 문제 해결

자주 겪는 문제에 대한 해결 방법입니다. 더 많은 내용은 [Unity 문제 해결 가이드](https://ai-game.dev/ko/docs/wiki/unity/troubleshooting)에서 확인하세요.

**AI 클라이언트가 연결되지만 도구가 표시되지 않습니다**

Unity 상태가 **연결됨**인지 확인한 다음 클라이언트를 다시 연결하거나(Claude Code에서는 `/mcp`) 재시작하세요. 그래도 목록이 비어 있으면 에이전트에 대해 **구성**을 다시 클릭한 뒤 클라이언트를 재시작하세요.

**AI Game Developer 창이 나타나지 않습니다**

플러그인은 프로젝트가 컴파일된 후에만 로드됩니다. 프로젝트 어디에서든 컴파일 오류가 있는지 콘솔을 확인한 다음 에디터를 다시 여세요. McpPlugin 또는 ReflectorNet의 누락된 타입은 보통 첫 임포트가 아직 끝나지 않았음을 의미합니다. 기다리거나 **도구 → AI Game Developer → 종속성 → NuGet DLL 강제 확인**을 사용하세요.

**사용자 지정 모드: 로컬 MCP 서버가 시작되지 않습니다**

사용자 지정 모드에서 플러그인은 `gamedev-mcp-server`를 `Library/mcp-server/<platform>/`에 다운로드합니다. 방화벽이나 프록시가 이를 차단한 경우 창에 **다운로드 / 재시도** 버튼이 있는 서버 오류가 표시됩니다. 클라우드 모드에서는 로컬 서버가 필요하지 않습니다.

**사용자 지정 모드에서 포트 충돌**

각 프로젝트에는 경로에서 파생된 20000~29999 사이의 고정 로컬 포트가 지정됩니다. 다른 프로세스가 이미 해당 포트를 사용 중이면 서버가 **외부**로 표시됩니다. 해당 프로세스를 중지하거나 **서버 URL**에 다른 포트를 입력하고 **구성**을 다시 클릭하세요.

**패키지 관리자에서 패키지에 더 새로운 Unity가 필요하다고 보고합니다**

플러그인에는 Unity 2022.3 이상이 필요합니다. 프로젝트를 업그레이드하거나 `unity-mcp-cli install-unity`로 더 새로운 에디터를 설치하세요.

### 다음 단계

[**Unity 위키 →** 구성, 도구와 RQL, 사용자 지정 도구, CLI 참조 등이 있습니다.](https://ai-game.dev/ko/docs/wiki/unity) [**Unity 도구 →** 에이전트가 Unity에서 할 수 있는 모든 작업과 예제를 확인하세요.](https://ai-game.dev/docs/tools/unity) [**모범 사례 →** 에이전트가 잘하는 작업을 요청하는 방법입니다.](https://ai-game.dev/docs/best-practices/unity)

---

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

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