설치

이 페이지에서는 Unreal Engine용 AI Game Developer 플러그인인 Unreal MCP를 프로젝트에 설치하는 방법을 설명합니다. 설치 경로를 하나 선택해 단계를 따른 뒤 시작하기를 계속 진행하세요.

요구 사항#

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

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

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

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

1. 다운로드 페이지에서 AI Game Dev를 설치하세요. 앱 설치 가이드에서 자세히 안내합니다.
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 명령입니다. 앱은 선택적 확장 기능도 설치할 수 있습니다. 자세한 내용은 프로젝트와 엔진을 참고하세요.

옵션 2: unreal-mcp-cli#

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

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

npm install -g unreal-mcp-cli

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

npx unreal-mcp-cli@latest status

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

# 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 저장소의 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에 다음이 출력됩니다:

[Unreal-MCP] plugin loaded

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

그러면 플러그인이 에디터의 Tools 메뉴 아래에 AI Game Developer로 나타납니다. 시작하기를 이어서 진행하세요.

플러그인 업데이트#

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

오래된 빌드 캐시는 업데이트가 아무 효과도 없는 것처럼 보이는 가장 흔한 원인입니다. 문제 해결을 참고하세요.

플러그인 제거#

unreal-mcp-cli remove-plugin ./YourProject

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

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

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

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

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