UnrealMCP — Unreal Engine 5.7용 네이티브 MCP

English | 简体中文

UnrealMCP는 자체 포함된 Unreal Engine 5.7 에디터 코드 플러그인입니다. Codex 및 기타 로컬 MCP 클라이언트가 열려 있는 Unreal Editor를 검사하고 제어할 수 있게 하며, 정확히 하나의 MCP 도구인 unreal을 노출합니다.

배포되는 플러그인은 Node.js, npm, Python 패키지 또는 별도로 설치된 게이트웨이 서비스가 필요하지 않습니다. 여기에는 두 가지 런타임 구성 요소가 포함되어 있습니다:

• Binaries/Win64/UnrealMCPGateway.exe — MCP 클라이언트가 시작하는 네이티브 C++ stdio MCP 서버.

• Binaries/Win64/UnrealEditor-UnrealMCP.dll — 루프백 워커를 보유하고 Unreal 작업을 게임 스레드로 디스패치하는 에디터 모듈.

주요 특징

• 단일 도구 표면: 검색, 상태 확인, 실행, 비동기 작업 제어가 모두 unreal 뒤에 있습니다.

• 자체 포함: 배포 가능한 플러그인에는 네이티브 stdio 게이트웨이와 Unreal Editor 워커가 포함됩니다.

• 에이전트 친화적: 순서가 지정된 Python/콘솔 배치는 리플렉션된 UE API와 UnLua 같은 프로젝트별 시스템에 대한 유연한 경로를 제공합니다.

• 게임 스레드 안전: UObject 및 에디터 작업은 Unreal 게임 스레드로 디스패치됩니다.

• Fab 지향 패키징: 릴리스 자동화는 외부 런타임 없이 깔끔한 단일 플러그인 ZIP을 생성합니다.

flowchart LR
    C["Codex / MCP client"] -->|"stdio JSON-RPC"| G["Native gateway EXE"]
    G -->|"127.0.0.1 HTTP + optional bearer token"| P["UnrealMCP Editor plugin"]
    P -->|"Game Thread"| U["UE Python / console / UObject APIs"]

상태 및 호환성

기능 카탈로그는 UE 5.8 공식 AllToolsets 집계에 포함된 모든 플러그인 그룹을 UE 5.7 Python/리플렉션 및 콘솔 메커니즘을 통해 다룹니다. UE 5.8에만 존재하는 하위 시스템은 기본 UE 5.7에서 만들 수 없습니다. 필요한 5.7 하위 시스템 또는 선택적 플러그인이 있으면 동등한 워크플로가 작동합니다. 기능 적용 범위를 참조하세요.

목차

• 빠른 시작

• 설치

• Codex 연결

• 첫 연결 확인

• 단일 도구 API

• 기능 모델

• 소스에서 빌드

• 테스트

• 문제 해결

• 보안 및 운영 제한

• 저장소 맵

• 배포 참고 사항

빠른 시작

1. 플러그인을 추출하여 설명자가 <Project>/Plugins/UnrealMCP/UnrealMCP.uplugin에 추가 중첩 디렉터리 없이 위치하도록 합니다.

2. Minimal MCP for Unreal Editor 및 Python Editor Script Plugin을 활성화한 후 Unreal Editor를 다시 시작합니다.

3. 아래 구성을 사용자 수준 ~/.codex/config.toml 또는 신뢰할 수 있는 프로젝트의 .codex/config.toml에 저장합니다. 명령을 절대 게이트웨이 경로로 바꿉니다.

4. Codex를 다시 시작하고 /mcp로 unreal이 연결되었는지 확인한 다음 에이전트에게 health 작업을 호출하도록 요청합니다.

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

정상 결과에는 ok: true, 실제 엔진 버전, is_game_thread: true, python_loaded: true가 포함됩니다. Unreal Editor는 대상 프로젝트가 로드된 채 열려 있어야 합니다.

설치

프로젝트 설치

바이너리를 복사하거나 교체하기 전에 Unreal Editor를 닫으세요. 패키지된 UnrealMCP 디렉터리를 다음 위치에 추출하거나 복사합니다:

<Project>/Plugins/UnrealMCP

설명자는 다음 위치에 있어야 합니다:

<Project>/Plugins/UnrealMCP/UnrealMCP.uplugin

프로젝트를 열고 Edit → Plugins에서 Minimal MCP for Unreal Editor 및 Python Editor Script Plugin을 활성화한 후 에디터를 다시 시작합니다.

엔진 설치

동일한 엔진 빌드를 사용하는 여러 프로젝트에서 플러그인을 사용할 수 있게 하려면 다음 위치에 설치합니다:

C:/Program Files/Epic Games/UE_5.7/Engine/Plugins/Marketplace/UnrealMCP

관리자 권한이 필요할 수 있습니다. 프로젝트 로컬 설치는 일반적으로 프로젝트와 함께 버전을 관리하기 더 쉬우며 개발 시 우선 적용됩니다.

Codex 연결

Codex 데스크톱, Codex CLI, IDE 확장 프로그램은 MCP 구성을 공유합니다. 로컬 stdio 서버는 구성된 command에서 시작됩니다. 구성은 전역적으로 ~/.codex/config.toml 또는 신뢰할 수 있는 프로젝트 내 .codex/config.toml에 저장할 수 있습니다. 공식 Codex MCP 문서를 참조하세요.

Windows TOML 경로에서는 슬래시를 사용하세요:

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

또한 Codex 데스크톱의 Settings → MCP servers → Add → STDIO에서 서버를 추가할 수 있습니다. 구성을 저장한 후 Codex를 다시 시작하고 /mcp를 사용하여 서버가 연결되었는지 확인하세요.

MCP 클라이언트는 네이티브 게이트웨이만 시작합니다. Unreal Editor를 실행하지는 않습니다. 도구 호출 전에 Unreal Editor에서 대상 프로젝트를 엽니다.

포트 및 인증

워커는 127.0.0.1에만 바인딩됩니다. 다음 환경 변수는 에디터와 게이트웨이가 각각 읽습니다.

인증을 위해 Unreal Editor와 Codex를 실행하기 전에 동일한 토큰을 설정하세요. 토큰을 커밋하지 마세요:

$env:UE_MCP_WORKER_TOKEN = '<a-long-random-token>'
$env:UE_MCP_WORKER_PORT = '18777'
& 'C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor.exe' 'C:\path\Project.uproject'

Codex가 해당 셸에서 시작되지 않은 경우 동일한 값을 MCP 서버 구성에 제공하세요:

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

[mcp_servers.unreal.env]
UE_MCP_WORKER_PORT = "18777"
UE_MCP_WORKER_TOKEN = "replace-with-the-same-token-used-by-the-editor"
UE_MCP_TIMEOUT_MS = "30000"

첫 연결 확인

MCP 클라이언트에게 다음으로 unreal을 호출하도록 요청하세요:

{
  "action": "health"
}

정상 응답의 형태는 다음과 같습니다:

{
  "ok": true,
  "data": {
    "ok": true,
    "engine_version": "5.7.x-...",
    "is_game_thread": true,
    "python_loaded": true,
    "transport": "loopback-http"
  }
}

그런 다음 엔진 읽기를 확인하세요:

{
  "action": "execute",
  "transaction": false,
  "commands": [
    {
      "kind": "python",
      "mode": "eval",
      "label": "engine-version",
      "code": "unreal.SystemLibrary.get_engine_version()"
    }
  ]
}

eval은 하나의 Python 표현식을 평가하고 값을 반환합니다. exec는 문 또는 여러 줄 스크립트를 실행합니다. unreal 모듈은 플러그인의 Python 실행 환경에서 사용할 수 있습니다.

단일 도구 API

unreal은 작업(action)으로 구분되는 스키마를 사용하므로 MCP 클라이언트는 검색, 실행, 상태 확인, 장기 실행 작업 제어를 유지하면서 단 하나의 도구 정의만 받습니다.

기능 검색

UE API를 선택하기 전에 독립적인 기능 카탈로그를 검색하세요:

{
  "action": "discover",
  "query": "create and compile a blueprint",
  "limit": 5
}

domain을 사용하여 blueprint, asset, niagara, pcg, slate, umg, unlua와 같은 정확한 도메인을 지정하세요. 쿼리 없이 discover를 호출하면 요청된 한도까지 카탈로그 항목이 반환됩니다.

순서가 지정된 배치 실행

execute 배치는 최대 100개의 Python 또는 콘솔 명령을 허용합니다. 명령은 게임 스레드에서 순서대로 실행됩니다.

{
  "action": "execute",
  "run": "sync",
  "transaction": true,
  "continue_on_error": false,
  "timeout_ms": 120000,
  "commands": [
    {
      "kind": "python",
      "mode": "exec",
      "label": "select-all-static-mesh-actors",
      "code": "subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\nactors = subsystem.get_all_level_actors()\nsubsystem.set_selected_level_actors([a for a in actors if isinstance(a, unreal.StaticMeshActor)])"
    },
    {
      "kind": "console",
      "label": "show-fps",
      "command": "stat fps"
    }
  ]
}

• transaction은 기본적으로 true이며 전체 배치가 성공하면 하나의 에디터 실행 취소 기록을 만듭니다.

• continue_on_error는 기본적으로 false입니다. 활성화하면 이후 명령도 계속 실행되며, 명령이 하나라도 실패하면 전체 결과는 실패로 유지됩니다.

• timeout_ms는 100~3600000 밀리초를 허용하며 해당 호출에 대해 UE_MCP_TIMEOUT_MS를 재정의합니다.

• Python 결과 및 캡처된 Python 로그, 또는 콘솔 출력은 명령별로 반환됩니다.

읽기 전용 쿼리와 Unreal 트랜잭션에 참여하지 않는 API에는 transaction: false를 사용하세요. Unreal 트랜잭션은 실행 취소 기록이지 파일 시스템 또는 소스 제어 롤백이 아닙니다.

비동기 작업 실행 및 검사

긴 배치의 경우 비동기로 제출하세요:

{
  "action": "execute",
  "run": "async",
  "timeout_ms": 3600000,
  "commands": [
    {
      "kind": "console",
      "command": "Automation RunTests Project"
    }
  ]
}

응답에는 task_id가 포함됩니다. 다음으로 작업을 폴링하거나 나열하세요:

{ "action": "task", "command": "get", "task_id": "<uuid>" }

{ "action": "task", "command": "list" }

다음으로 작업을 취소 표시하세요:

{ "action": "task", "command": "cancel", "task_id": "<uuid>" }

작업 상태는 게이트웨이 프로세스에 유지되며 Codex가 해당 프로세스를 중지하면 손실됩니다. 취소는 최선형(best-effort)입니다. 추적을 취소된 것으로 표시하지만 이미 Unreal 게임 스레드로 디스패치된 작업은 계속 완료될 수 있으며 롤백되지 않습니다.

기능 모델

이 플러그인은 의도적으로 수백 개의 좁은 래퍼 도구를 피합니다. discover는 레시피와 권장 API를 제공하고, execute는 UE 5.7의 리플렉션된 Python 표면, 콘솔 명령, 선택적 엔진 플러그인, UnLua와 같은 프로젝트별 API에 도달합니다.

카탈로그는 편집기/에셋/Blueprint 작업, AI 및 내비게이션, 애니메이션, 자동화, 구성, 대화, Data Registry, Dataflow, Game Features, Gameplay Tags 및 GAS, Niagara, PCG, 물리, 플러그인, 시맨틱 검색, Slate, StateTree, UMG, World Conditions를 포함한 UE 5.8 AllToolsets 그룹 21개 전체를 매핑합니다.

적용 범위는 라우팅 및 메커니즘 적용 범위이며, UE 5.8 전용 클래스가 UE 5.7에 존재한다는 주장이 아닙니다. 선택적 워크플로는 해당 엔진 또는 프로젝트 플러그인이 활성화되어 있어야 합니다. 근거와 5단계 최소화 과정은 도구 최소화에 문서화되어 있습니다.

소스에서 빌드

요구 사항:

• Unreal Engine 5.7 소스/빌드 설치. 스크립트는 기본적으로 C:\Program Files\Epic Games\UE_5.7을 사용합니다.

• UE 5.7이 지원하는 Visual Studio C++ 툴체인.

• PowerShell.

• Node.js 20+는 선택적 MCP 프로토콜 테스트에만 필요합니다. Node는 제품 런타임 종속성이 아닙니다.

네이티브 게이트웨이를 제자리에서 컴파일하세요:

.\scripts\build-native-gateway.ps1

새 디렉터리에 전체 플러그인 패키지를 빌드하세요:

.\scripts\build-plugin.ps1 -OutputDirectory 'C:\Temp\UnrealMCP-Package'

단일 최상위 Fab ZIP을 만드세요:

.\scripts\build-fab-package.ps1 -OutputFile '.\artifacts\UnrealMCP-0.2.0-UE5.7-Win64.zip'

패키지된 플러그인에는 설명자, 소스, 구성, 리소스, 네이티브 DLL 및 EXE, 라이선스 고지, 영어 및 중국어 간체 README, 설계 문서가 포함됩니다. Fab ZIP에는 정확히 하나의 최상위 UnrealMCP/ 디렉터리가 포함되며 Intermediate, PDB 파일, Node 패키지, 개발 테스트 프로젝트는 제외됩니다.

각 엔진 버전과 플랫폼은 자체적으로 컴파일되고 테스트된 바이너리 패키지가 필요합니다. 현재 설명자는 Win64만 대상으로 합니다.

테스트

메타데이터 및 네이티브 최신/레거시 MCP 통합 테스트를 실행하세요:

npm install
npm test

전체 네이티브 stdio 게이트웨이 → 루프백 워커 → 게임 스레드 → UE Python 경로를 실행하세요:

.\scripts\build-native-gateway.ps1
.\scripts\test-worker-e2e.ps1

엔드투엔드 테스트는 포함된 UE57MCPTest.uproject를 격리된 포트에서 헤드리스로 시작하고 검증 후 종료합니다. 선택한 포트가 사용 중이면 관련 없는 자동화 테스트 인스턴스를 닫으세요.

문제 해결

게이트웨이는 MCP 프로토콜 메시지를 표준 출력에만 쓰고 진단 정보는 표준 오류에 씁니다. 플러그인 시작, 바인딩, 권한 부여 및 실행 오류는 Unreal Output Log의 LogUnrealMCP 아래에 나타납니다.

보안 및 운영 제한

execute는 의도적으로 임의의 Unreal Python 및 콘솔 명령을 허용합니다. 이 도구에 대한 액세스는 에이전트가 열린 에디터 프로젝트를 조작하도록 허용하는 것과 동일하게 취급하세요.

• 워커는 루프백에만 바인딩되며 원격 네트워크 서비스가 아닙니다.

• Bearer 인증은 선택 사항이지만 공유 머신에서는 권장됩니다.

• 요청 본문은 4 MiB로, 배치는 100개 명령으로 제한됩니다.

• UObject 및 에디터 접근은 Game Thread에서 실행됩니다.

• 비밀을 도구 인수, 프로젝트 파일, 로그 또는 커밋된 Codex 구성에 넣지 마세요.

• 파괴적인 에셋, 구성, 플러그인 및 파일시스템 작업에는 소스 제어를 사용하세요.

저장소 구조

배포 관련 참고 사항

생성된 ZIP은 Fab 기술 검토에 적합한 단일 설치 가능한 UE Code Plugin으로 구성됩니다. 마켓플레이스 게시에는 여전히 판매자/등록 메타데이터와 플러그인 아이콘 및 스크린샷과 같은 시각적 자산, 그리고 광고된 모든 엔진 버전과 플랫폼에서 테스트된 패키지가 필요합니다.

라이선스 세부 정보는 LICENSE에, 타사 고지 사항은 THIRD_PARTY_NOTICES.md에 있습니다. 추가 설계 노트: 아키텍처, 기능 범위, 도구 최소화.

이 프로젝트가 도움이 되었다면, Star ⭐를 눌러 주세요.