# 설치 — Unreal Engine · AI Game Developer Wiki

AI Game Dev 앱 또는 unreal-mcp-cli로 Unreal Engine 5.5+용 Unreal MCP 플러그인을 설치합니다. 요구 사항, 업데이트, 제거 및 Fab 상태를 다룹니다.

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

이 페이지에서는 Unreal Engine용 AI Game Developer 플러그인인 Unreal MCP를 프로젝트에 설치하는 방법을 설명합니다. 설치 경로를 하나 선택해 단계를 따른 뒤 [시작하기](https://ai-game.dev/ko/docs/wiki/unreal/getting-started)를 계속 진행하세요.

## 요구 사항

| 요구 사항 | 세부 정보 |
| --- | --- |
| Unreal Engine | 5.5 이상. 릴리스 빌드는 5.5, 5.6, 5.7, 5.8에서 검증되었습니다. |
| 프로젝트 유형 | **C++ Unreal 프로젝트**. 플러그인에는 프로젝트용으로 컴파일되는 에디터 모듈이 포함되므로, 프로젝트가 C++를 빌드할 수 있어야 합니다. |
| C++ 툴체인 | 사용 중인 Unreal Engine 버전이 해당 플랫폼에서 요구하는 컴파일러 툴체인(예: Windows의 Visual Studio, macOS의 Xcode)입니다. |
| 운영 체제 | Windows(x64), macOS(Apple silicon 및 Intel), Linux(x64). 릴리스에는 각 플랫폼용 브리지 빌드가 포함됩니다. |
| Node.js | `unreal-mcp-cli` 전용: `^20.19.0` 또는 `>=22.12.0`. 데스크톱 앱에는 필요하지 않습니다. |
| .NET 9 SDK | 브리지를 소스에서 빌드하는 경우에만 필요합니다. 패키지 설치에는 브리지가 포함되어 있습니다. |

플러그인은 디스크립터에 정확한 엔진 버전을 고정하지 않으므로, 같은 플러그인이 최신 엔진 릴리스에서도 로드됩니다.

**참고:** 블루프린트 전용 프로젝트는 플러그인을 빌드하려면 C++ 모듈이 필요합니다. Unreal Editor에서 아무 C++ 클래스나 추가하거나(Tools, New C++ Class) `unreal-mcp-cli create-project`로 새 C++ 프로젝트를 생성하세요.

## 옵션 1: AI Game Dev 데스크톱 앱

데스크톱 앱이 가장 간단한 경로입니다. 설치 로직이 포함되어 있어 Node.js, npm 또는 터미널이 필요하지 않습니다.

1. [다운로드 페이지](https://ai-game.dev/ko/download)에서 AI Game Dev를 설치하세요. [앱 설치 가이드](https://ai-game.dev/ko/docs/wiki/app/installation)에서 자세히 안내합니다.
2. ai-game.dev 계정으로 로그인하세요.
3. \*\*Open folder…\*\*를 선택하고 Unreal 프로젝트 폴더(`.uproject` 파일이 있는 폴더)를 고르세요. 앱이 이를 Unreal 프로젝트로 감지합니다. 또는 **Create new project**로 새 프로젝트를 만들 수도 있으며, 이 경우 플러그인이 자동으로 설치됩니다.
4. 사이드바에서 **Install Package**를 클릭하세요. 앱이 최신 릴리스된 Unreal MCP 버전을 설치하며, 먼저 다운로드를 검증합니다. 이미 설치된 플러그인이 더 최신이라면 앱은 그대로 유지합니다.
5. **Open Editor**를 클릭해 로그인된 세션으로 Unreal Editor를 실행하면, 플러그인이 수동 토큰 없이 ai-game.dev를 통해 연결됩니다.

앱의 CLI에서는 같은 작업이 `/install-plugin` 및 `/open` 명령입니다. 앱은 선택적 [확장 기능](https://ai-game.dev/ko/docs/wiki/unreal/extensions)도 설치할 수 있습니다. 자세한 내용은 [프로젝트와 엔진](https://ai-game.dev/ko/docs/wiki/app/projects-and-engines)을 참고하세요.

## 옵션 2: unreal-mcp-cli

`unreal-mcp-cli`는 npm에 게시되어 있으며 Windows, macOS, Linux에서 작동합니다. 저장소를 복제하거나 자체 빌드 단계를 거칠 필요가 없습니다.

CLI를 전역으로 설치하세요:

```bash
npm install -g unreal-mcp-cli
```

또는 설치 없이 한 번만 명령을 실행하세요:

```bash
npx unreal-mcp-cli@latest status
```

그런 다음 플러그인을 설치하고 로그인한 뒤 에디터를 여세요:

```bash
# 1. Install the UnrealMCP plugin into <project>/Plugins/UnrealMCP
unreal-mcp-cli install-plugin ./YourProject

# 2. Sign in to ai-game.dev once per machine (device-code flow in your browser)
unreal-mcp-cli login

# 3. Open the Unreal Editor for the project
unreal-mcp-cli open ./YourProject
```

이 명령들이 하는 일:

- `install-plugin`은 CLI 버전에 맞는 플러그인 소스(GitHub 릴리스의 `unreal-mcp-plugin-source-<version>.zip`)를 다운로드하고, 압축을 풀기 전에 서명을 확인합니다. 변조되었거나 서명되지 않은 다운로드는 거부됩니다. 사용 중인 플랫폼용 브리지는 해당 패키지에 포함되어 있습니다.
- `login`은 자격 증명을 머신 전체 저장소(`~/.ai-game-dev/credentials.json`)에 저장하며, 앱 및 다른 엔진 CLI와 공유됩니다.
- `open`은 프로젝트의 `EngineAssociation`에서 올바른 엔진을 찾고, 네이티브 에디터 모듈을 컴파일해야 하면 먼저 빌드한 뒤, 여전히 나타나는 알려진 Unreal 시작 프롬프트(예: "Missing Modules")를 닫습니다.

**팁:** 플러그인을 설치하거나 업데이트하기 전에 Unreal Editor를 닫으세요. Unreal은 실행 중인 에디터가 로드한 플러그인을 교체할 수 없습니다.

## 옵션 3: 소스에서 수동 설치

수동 설치는 기여자와 플러그인 개발자를 위한 방법입니다.

1. [Unreal-MCP 저장소](https://github.com/IvanMurzak/Unreal-MCP)의 `UnrealMCP/` 폴더를 `<YourProject>/Plugins/UnrealMCP/`에 복사하세요.
2. 소스 체크아웃에는 브리지가 포함되어 있지 않습니다. `unreal-mcp-cli bootstrap-local ./YourProject`로 브리지를 빌드하거나(.NET 9 SDK 필요), 직접 빌드한 브리지를 `UNREAL_MCP_BRIDGE_PATH`로 지정하세요.
3. 프로젝트를 여세요. Unreal이 첫 실행 시 플러그인의 모듈을 컴파일합니다.

실시간 개발을 위해서는 `unreal-mcp-cli install-plugin --junction`으로 플러그인 폴더를 복사하는 대신 연결할 수 있습니다(Windows).

## Fab / Epic Marketplace

Fab 등록이 계획되어 있지만 **아직 게시되지 않았습니다**. 게시되기 전까지는 Fab에서 설치할 것이 없으므로 앱이나 CLI를 사용하세요.

## 설치 확인

에디터가 시작되면 Output Log에 다음이 출력됩니다:

```text
[Unreal-MCP] plugin loaded
```

`unreal-mcp-cli status --path ./YourProject`를 실행하면 패키지, 프로젝트, 플러그인 및 연결 상태를 확인할 수도 있습니다.

그러면 플러그인이 에디터의 **Tools** 메뉴 아래에 **AI Game Developer**로 나타납니다. [시작하기](https://ai-game.dev/ko/docs/wiki/unreal/getting-started)를 이어서 진행하세요.

## 플러그인 업데이트

- **App:** 더 새로운 플러그인 릴리스가 있으면 사이드바에 **Update Package**가 표시됩니다.
- **CLI:** `unreal-mcp-cli update ./YourProject`를 실행하세요. 버전이 변경되면 설치된 플러그인의 `Intermediate/` 폴더와 컴파일된 C++ `Binaries/`를 삭제하여 Unreal이 깨끗하게 재빌드하도록 하며, 번들된 브리지는 유지합니다. 동일한 버전을 다시 설치하려면 `--force`를, 빌드 캐시를 유지하려면 `--no-clean`을 추가하세요.
- **수동 복사:** 에디터를 닫고 `Plugins/UnrealMCP/Intermediate/`와 C++ `Binaries/`를 삭제한 다음(`Binaries/ThirdParty/`는 유지), 프로젝트를 다시 여세요.

오래된 빌드 캐시는 업데이트가 아무 효과도 없는 것처럼 보이는 가장 흔한 원인입니다. [문제 해결](https://ai-game.dev/ko/docs/wiki/unreal/troubleshooting#stale-build)을 참고하세요.

## 플러그인 제거

```bash
unreal-mcp-cli remove-plugin ./YourProject
```

또는 에디터를 닫은 상태에서 `<YourProject>/Plugins/UnrealMCP/`를 삭제하세요.

## 패키징된 게임에서 플러그인 제외하기

에디터에서의 AI 지원 용도로만 Unreal MCP를 사용한다면, **프로젝트의** `.uproject` 플러그인 항목에서 패키징된 빌드에서 제외하세요:

```json
{
  "Name": "UnrealMCP",
  "Enabled": true,
  "TargetDenyList": ["Game", "Client", "Server"]
}
```

그러면 플러그인은 에디터에서 계속 활성 상태로 유지되지만, 브리지를 포함한 어떤 부분도 패키징된 게임에 컴파일되거나 스테이징되지 않습니다. 게임 모듈의 `Build.cs` 의존성에 `UnrealMcp*` 모듈을 추가하지 마세요. 직접 의존성은 차단 목록을 무시합니다. 대신 실행 중인 게임 안에서 AI 도구를 사용하려면 [인게임 도구](https://ai-game.dev/ko/docs/wiki/unreal/custom-tools#runtime)를 참고하세요.

---

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

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