# 설치 — Unity · AI Game Developer Wiki

데스크톱 앱, unity-mcp-cli, OpenUPM 또는 .unitypackage 설치 프로그램으로 Unity 프로젝트에 Unity MCP(AI Game Developer)를 설치하세요.

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

이 페이지는 Unity 프로젝트에 Unity MCP 플러그인을 추가하는 모든 방법과 각 방법이 프로젝트에 미치는 영향, 그리고 플러그인을 다시 제거하는 방법을 보여줍니다. 모든 경로가 OpenUPM 레지스트리에서 동일한 패키지 `com.ivanmurzak.unity.mcp`를 설치하므로, 워크플로에 맞는 방법을 선택하면 됩니다.

## 요구 사항

- **Unity 2022.3 이상.** 패키지는 최소 버전으로 `2022.3`을 선언하며, Unity 6 릴리스도 지원합니다.
- **공백이 없는 프로젝트 경로.** `C:/Projects/MyGame`은 괜찮지만 `C:/My Projects/My Game`은 안 됩니다. 경로에 공백이 있으면 플러그인이 시작 시 오류를 기록합니다.
- **Windows에서 짧은 프로젝트 경로.** 플러그인은 NuGet DLL을 `Assets/Plugins/NuGet`에 복사합니다. 결과 경로가 Windows의 260자 제한을 넘으면 설치가 중단되고 프로젝트를 더 짧은 폴더로 옮기라는 안내가 표시됩니다.
- **처음 열 때 인터넷 접속.** 플러그인은 NuGet에서 .NET 의존성을, Custom 모드에서는 GitHub에서 MCP 서버 바이너리를 다운로드합니다.
- `unity-mcp-cli` 전용: **Node.js** `^20.19.0` 또는 `>=22.12.0`.

## 옵션 1: AI Game Dev 데스크톱 앱 (권장)

[AI Game Dev 앱](https://ai-game.dev/docs/app)은 터미널이나 머신의 Node.js 없이 플러그인을 설치하고 연결해 줍니다.

1. [앱을 다운로드](https://ai-game.dev/ko/download)하고 ai-game.dev 계정으로 로그인하세요.
2. 앱에서 Unity 프로젝트 폴더를 여세요. 앱이 Unity 프로젝트임을 감지합니다.
3. **Install Package**를 클릭하세요. 앱은 OpenUPM의 최신 릴리스 버전으로 `Packages/manifest.json`에 플러그인을 추가하며, 이미 설치된 더 새로운 버전을 다운그레이드하지 않습니다. 앱에서 생성한 프로젝트에는 플러그인이 자동으로 포함됩니다.
4. 앱에서 에디터를 여세요. 앱이 세션을 전달하므로 플러그인이 별도 로그인 없이 ai-game.dev를 통해 연결됩니다.

앱은 확장 기능도 설치하고 AI 에이전트 자체를 실행하므로 별도의 MCP 클라이언트가 필요 없습니다. 자세한 내용은 앱 위키의 [설치](https://ai-game.dev/ko/docs/wiki/app/installation) 및 [프로젝트와 엔진](https://ai-game.dev/ko/docs/wiki/app/projects-and-engines)을 참고하세요.

## 옵션 2: unity-mcp-cli

`unity-mcp-cli`는 `Packages/manifest.json`을 직접 편집하므로 Unity를 열어 둘 필요가 없습니다:

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

전역 설치 없이 실행할 수도 있습니다:

```bash
npx unity-mcp-cli install-plugin ./MyUnityProject
```

`install-plugin`은 스코프 `com.ivanmurzak` 및 `extensions.unity`로 OpenUPM 스코프 레지스트리를 추가하고, 최신 OpenUPM 버전으로 `com.ivanmurzak.unity.mcp`를 `dependencies`에 추가하며, 이미 설치된 더 높은 버전을 다운그레이드하지 않습니다. 버전을 고정하려면 `--plugin-version <version>`을 전달하세요. 프로젝트 폴더에서 명령을 실행하는 경우 경로는 선택 사항입니다.

CLI로 Unity를 설치하고 프로젝트를 먼저 생성할 수도 있습니다:

```bash
unity-mcp-cli install-unity
unity-mcp-cli create-project ./MyUnityProject
```

Unity Hub가 없으면 CLI가 설치합니다. 이후 패키지 관리자가 패키지를 해석할 수 있도록 Unity에서 프로젝트를 여세요. 모든 명령은 [CLI 레퍼런스](https://ai-game.dev/ko/docs/wiki/unity/cli)에 있습니다.

## 옵션 3: OpenUPM

[OpenUPM CLI](https://openupm.com/)가 설치되어 있다면 프로젝트 폴더에서 다음을 실행하세요:

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

OpenUPM CLI 없이 `Packages/manifest.json`에 레지스트리와 의존성을 직접 추가하세요. [OpenUPM 패키지 페이지](https://openupm.com/packages/com.ivanmurzak.unity.mcp/)에 표시된 버전을 사용하세요:

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

이 항목들을 기존 파일에 병합하고, 다른 의존성을 대체하지 마세요.

## 옵션 4: .unitypackage 설치 프로그램

1. [AI-Game-Dev-Installer.unitypackage](https://github.com/IvanMurzak/Unity-MCP/releases/latest/download/AI-Game-Dev-Installer.unitypackage)를 다운로드하세요.
2. Unity에서 프로젝트를 여세요.
3. 파일을 두 번 클릭하거나 **Assets > Import Package > Custom Package**를 사용해 파일을 선택하세요.
4. **Import**를 클릭하세요.

설치 프로그램은 작은 에디터 스크립트입니다. OpenUPM 스코프 레지스트리와 플러그인 의존성을 `Packages/manifest.json`에 추가한 뒤 `Assets`에서 자신을 삭제합니다. 그런 다음 패키지 관리자가 실제 패키지를 다운로드합니다.

## 처음 열 때 일어나는 일

패키지가 도착하면 플러그인이 스스로를 준비합니다:

- 필요한 .NET 라이브러리(MCP 플러그인 라이브러리, ReflectorNet, RQL, SignalR, System.Text.Json 등)를 NuGet에서 `Assets/Plugins/NuGet`으로 다운로드하고, `Library/NuGetCache`에 캐시하며, Unity가 한 번 재컴파일합니다. 이 DLL들이 동기화되지 않는 경우 **Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs**를 사용하세요.
- GitHub에서 해당 플랫폼용 `gamedev-mcp-server` 바이너리를 `Library/mcp-server/<platform>/`(예: `win-x64`, `osx-arm64`, `linux-x64`)로 다운로드합니다. 서버는 HTTP 전송을 쓰는 Custom 모드에서만 시작되며, 기본값인 Cloud 모드에서는 로컬 서버를 시작하지 않습니다.
- **AI Game Developer** 창은 **Window > AI Game Developer — MCP**에서 사용할 수 있게 됩니다(단축키 Ctrl+Alt+A, macOS에서는 Cmd+Option+A). Scene View 툴바에도 이 창을 여는 **AI** 오버레이 버튼이 추가됩니다.

`Library/`는 기본적으로 버전 관리에서 제외되므로 서버 바이너리는 절대 커밋되지 않습니다. CI 환경에서는 플러그인이 서버 다운로드와 시작을 건너뜁니다.

## 플러그인 업데이트

OpenUPM에 더 새로운 버전이 있으면 플러그인이 에디터 시작 시 업데이트 팝업을 표시합니다. **Tools > AI Game Developer > Updates > Check for Updates**로 직접 확인할 수도 있습니다. 업데이트하려면 패키지 관리자에서 버전을 변경하거나, `unity-mcp-cli install-plugin`을 다시 실행하거나(최신 버전을 설치합니다), 데스크톱 앱에서 업데이트하도록 하세요.

한 사람이 플러그인 버전을 관리하는 팀이라면 **Edit > Project Settings > AI Game Developer**를 열고 **Disable update notifications for the entire team**을 활성화하세요. 이 설정은 `ProjectSettings/AI-Game-Developer-UpdateSettings.asset`에 저장되며, 해당 파일을 커밋하세요. 동일한 토글이 \*\*Tools > AI Game Developer > Updates > Disable Update Notifications (Team)\*\*에도 있습니다.

## 제거

1. **Window > Package Manager**를 열고 **AI Game Developer — MCP**를 선택한 뒤 **Remove**를 클릭하거나, `unity-mcp-cli remove-plugin ./MyUnityProject`를 실행하세요. 다른 패키지가 사용할 수 있으므로 CLI는 스코프 레지스트리를 유지합니다.
2. Unity를 종료하고 `Assets/Plugins/NuGet` 폴더와 그 `Assets/Plugins/NuGet.meta` 파일을 삭제하세요.

## 다음 단계

- [시작하기](https://ai-game.dev/ko/docs/wiki/unity/getting-started): AI 클라이언트를 연결하고 첫 프롬프트를 실행하세요.
- [확장 기능](https://ai-game.dev/ko/docs/wiki/unity/extensions): Cinemachine, ProBuilder, Tilemap 등을 위한 툴 팩을 추가하세요.
- 설치 중 문제가 발생하면 [문제 해결](https://ai-game.dev/ko/docs/wiki/unity/troubleshooting)을 참고하세요.

---

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

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