# Unreal MCP — AI Game Developer Wiki

Unreal MCP는 Claude, Cursor, Copilot 및 기타 AI 에이전트를 Unreal Editor에 연결합니다. 플러그인, 브리지, CLI, 앱이 어떻게 맞물리는지 알아보세요.

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

Unreal MCP는 AI Game Developer의 Unreal Engine 플러그인입니다. Claude Code, Cursor, GitHub Copilot, Codex, Gemini 같은 AI 에이전트가 Unreal Editor 안에서 작업할 수 있게 해줍니다. 액터, 컴포넌트, 에셋, 레벨을 조회하고 변경하며, Blueprint를 작성하고 컴파일하고, C++를 편집하고 컴파일하고, 에디터 Python을 실행하고, 에이전트가 직접 볼 수 있는 스크린샷을 캡처합니다. 원하는 것을 자연어로 설명하면 에이전트가 Model Context Protocol(MCP)을 통해 에디터의 도구를 호출합니다.

이 위키는 플러그인을 설치하고, AI 클라이언트를 연결하고, Unreal Editor에서 AI로 유용한 결과를 얻는 방법을 설명합니다. 플러그인은 **베타** 상태이며, 현재 릴리스는 0.26.2입니다.

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

Unreal MCP 설정은 네 부분으로 이루어집니다. 이들을 이해하면 설정과 문제 해결이 훨씬 쉬워집니다.

- **Unreal MCP 플러그인**(`UnrealMCP`). 프로젝트의 `Plugins/` 폴더에 설치하는 C++ 에디터 플러그인입니다. AI 도구를 등록하고 에디터에 **AI Game Developer** 창을 추가합니다.
- **브리지**(`unreal-mcp-bridge`). Unreal 에디터는 C++이므로, .NET MCP 호스트가 에디터 옆에서 작은 헬퍼 프로세스로 실행됩니다. 플러그인이 이를 자동으로 시작하고, 토큰으로 보호되는 로컬 연결을 통해 통신합니다. 패키지된 릴리스에는 브리지가 포함되어 있으므로 .NET을 설치할 필요가 없습니다.
- **MCP 서버**. 기본적으로 브리지는 [ai-game.dev](https://ai-game.dev)의 호스팅 서버에 연결합니다(**Cloud** 모드). 대신 공유 로컬 서버 `gamedev-mcp-server`를 자신의 머신에서 실행할 수도 있습니다(**Custom** 모드).
- **AI 클라이언트**. 어떤 MCP 클라이언트든 같은 서버에 연결하고, 이를 통해 에디터에 접근합니다.

이를 설정하는 데 도움이 되는 두 가지 도구가 있습니다:

- **AI Game Dev** 데스크톱 앱은 Unreal 프로젝트에 플러그인을 대신 설치해 주고 에디터를 열 수도 있습니다. Node.js가 필요하지 않습니다. [앱 위키](https://ai-game.dev/ko/docs/wiki/app)를 참고하세요.
- **`unreal-mcp-cli`**, npm에서 제공되는 크로스 플랫폼 명령줄 도구입니다. 플러그인을 설치하고 업데이트하며, 로그인하고, MCP 클라이언트 구성을 작성하고, 에디터를 열고, 터미널이나 CI에서 도구를 실행합니다.

## AI 에이전트가 할 수 있는 일

플러그인은 7개 계열에 걸쳐 27개의 도구를 제공합니다. 대부분의 에디터 데이터는 작업별로 도구를 하나씩 두는 대신, 에디터 전체를 위한 하나의 쿼리 언어인 **RQL**을 통해 처리됩니다:

- **RQL**(`rql-query`, `rql-mutate`, `rql-schema`): 액터, 컴포넌트, 에셋, 레벨, DataTable, 게임플레이 태그, Project Settings, Blueprint 그래프, Widget Blueprint, Level Sequence를 찾고 변경합니다.
- **Blueprints**: Blueprint를 생성, 편집, 컴파일하며, 에이전트가 수정할 수 있는 구조화된 오류 목록을 제공합니다.
- **C++ 소스**: 프로젝트 C++를 읽고, 스캐폴딩하고, 편집하고, 컴파일합니다(Live Coding 또는 Unreal Build Tool).
- **Python**: 전체 `unreal` 에디터 API로 Python을 실행합니다.
- **스크린샷**: 뷰포트, 게임 뷰, 카메라, 격리된 액터 캡처.
- **콘솔** 및 **도구 목록** 헬퍼.

여섯 가지 선택적 확장은 Control Rig, Enhanced Input, Gameplay Ability System, Landscape 및 Water, Niagara, PCG 지원을 추가합니다. 어떤 Unreal 플러그인에서든 자체 도구를 등록할 수도 있습니다.

## 위키 페이지

| 페이지 | 확인할 수 있는 내용 |
| --- | --- |
| [설치](https://ai-game.dev/ko/docs/wiki/unreal/installation) | 요구 사항과 현재 존재하는 모든 설치 경로: 앱, CLI, 수동 설치 |
| [시작하기](https://ai-game.dev/ko/docs/wiki/unreal/getting-started) | 첫 연결, 첫 프롬프트, 모든 것이 제대로 작동하는지 확인하기 |
| [AI 클라이언트 연결](https://ai-game.dev/ko/docs/wiki/unreal/connecting-ai-clients) | Cloud와 Custom 모드, 디바이스 코드 로그인, 프로젝트 키, 에이전트별 `setup-mcp` |
| [구성](https://ai-game.dev/ko/docs/wiki/unreal/configuration) | AI Game Developer 창, MCP Tools 창, 설정 파일 및 `UNREAL_MCP_*` 변수 |
| [도구](https://ai-game.dev/ko/docs/wiki/unreal/tools) | 모든 내장 도구와 각 도구에 요청할 수 있는 작업 |
| [확장](https://ai-game.dev/ko/docs/wiki/unreal/extensions) | 여섯 가지 선택적 확장과 설치 방법 |
| [사용자 정의 도구](https://ai-game.dev/ko/docs/wiki/unreal/custom-tools) | C++에서 자체 도구, 프롬프트, 리소스를 추가하기, 게임 내(런타임) 도구 포함 |
| [CLI 레퍼런스](https://ai-game.dev/ko/docs/wiki/unreal/cli) | 모든 `unreal-mcp-cli` 명령과 플래그 |
| [문제 해결](https://ai-game.dev/ko/docs/wiki/unreal/troubleshooting) | 연결, 브리지, 빌드 및 도구 문제에 대한 해결책 |
| [FAQ](https://ai-game.dev/ko/docs/wiki/unreal/faq) | 자주 묻는 질문에 대한 짧은 답변 |

## 다음 단계

- 처음이신가요? [설치](https://ai-game.dev/ko/docs/wiki/unreal/installation)부터 시작한 뒤 [시작하기](https://ai-game.dev/ko/docs/wiki/unreal/getting-started)를 읽어 보세요.
- 짧은 버전을 원하시나요? [Unreal Engine 설치 페이지](https://ai-game.dev/ko/engines/unreal)와 [퀵스타트](https://ai-game.dev/ko/docs/quickstart)가 핵심을 다룹니다.
- 도구 세부 정보를 찾고 계신가요? [Unreal 도구 카탈로그](https://ai-game.dev/docs/tools/unreal)와 [Unreal 모범 사례](https://ai-game.dev/docs/best-practices/unreal)를 살펴보세요.
- 다른 엔진도 함께 사용하시나요? [Unity 위키](https://ai-game.dev/ko/docs/wiki/unity)와 [Godot 위키](https://ai-game.dev/ko/docs/wiki/godot)를 참고하세요. 세 플러그인 모두 동일한 서버, 계정, AI 클라이언트를 공유합니다.

- [**설치** AI Game Dev 앱 또는 unreal-mcp-cli로 Unreal Engine 5.5+용 Unreal MCP 플러그인을 설치합니다. 요구 사항, 업데이트, 제거 및 Fab 상태를 다룹니다.](https://ai-game.dev/ko/docs/wiki/unreal/installation)
- [**시작하기** Unreal MCP를 처음 연결하고, ai-game.dev에 로그인한 뒤, AI 클라이언트를 연결하고 Unreal Editor에서 첫 AI 프롬프트를 실행하세요.](https://ai-game.dev/ko/docs/wiki/unreal/getting-started)
- [**AI 클라이언트 연결** Claude Code, Cursor, Copilot, Codex, Gemini 및 기타 MCP 클라이언트를 ai-game.dev 클라우드 엔드포인트 또는 로컬 서버를 통해 Unreal MCP에 연결합니다.](https://ai-game.dev/ko/docs/wiki/unreal/connecting-ai-clients)
- [**설정** Unreal MCP 설정 - AI Game Developer 창, MCP Tools 표시 여부, 프로젝트 설정 파일, .env, 그리고 모든 UNREAL\_MCP\_\* 환경 변수를 다룹니다.](https://ai-game.dev/ko/docs/wiki/unreal/configuration)
- [**도구** Unreal MCP의 27가지 내장 도구 - RQL, Blueprint, C++ 소스, Python, 스크린샷, 콘솔 - 와 Unreal Editor에서 AI를 위한 예제 프롬프트.](https://ai-game.dev/ko/docs/wiki/unreal/tools)
- [**확장** Control Rig, Enhanced Input, GAS, Landscape와 Water, Niagara, PCG를 위한 선택적 Unreal MCP 확장입니다. 각 확장이 추가하는 기능과 설치 방법을 설명합니다.](https://ai-game.dev/ko/docs/wiki/unreal/extensions)
- [**사용자 정의 도구** C++ 플러그인에서 Unreal MCP에 자체 AI 도구, RQL 모듈, 프롬프트, 리소스를 추가하고 실행 중인 게임에서 게임플레이 도구를 노출하세요.](https://ai-game.dev/ko/docs/wiki/unreal/custom-tools)
- [**CLI 레퍼런스** unreal-mcp-cli 명령 전체 레퍼런스 - Unreal MCP 플러그인 설치, 로그인, AI 에이전트 구성, 에디터 실행, 도구와 Python 실행까지 다룹니다.](https://ai-game.dev/ko/docs/wiki/unreal/cli)
- [**문제 해결** 일반적인 Unreal MCP 문제 해결 - 플러그인 로드 실패, 브리지 누락, 연결 중단, Unreal 도구가 없는 AI 에이전트, 오래된 빌드, 도구 오류.](https://ai-game.dev/ko/docs/wiki/unreal/troubleshooting)
- [**FAQ** Unreal MCP에 관한 자주 묻는 질문의 답변 - 지원 엔진 버전, AI 클라이언트, 블루프린트 전용 프로젝트, Fab, 오프라인 사용, 비용, 패키징된 게임.](https://ai-game.dev/ko/docs/wiki/unreal/faq)

---

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

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