Unreal Engine MCP

Codex CLI에 Unreal Engine MCP 적용하기

---

Unreal MCP : https://github.com/ChiR24/Unreal_mcp
Codex를 사용.

공통 작업

Unreal_mcp 설치

git clone https://github.com/ChiR24/Unreal_mcp.git
cd Unreal_mcp
npm install
npm run build

node dist/cli.js로 수동 실행 테스트

node dist/cli.js

.codex/config.toml 수정

Windows 경로는 TOML 이스케이프 문제를 피하기 위해 /를 쓰는 편이 안전하다.

[mcp_servers.unreal-engine]
command = "node"
args = [ "D:/Unreal_mcp/dist/cli.js" ]

---

Blueprint 프로젝트인 경우 (UE 5.6.1)

Blueprint 프로젝트는 프로젝트 로컬 플러그인으로만 적용

Unreal_mcp 플러그인을 UE 5.6.1 엔진으로 패키징

플러그인을 원본 그대로 Plugins에 복사하지 않고, UE 5.6.1 엔진의 RunUAT BuildPlugin 흐름으로 먼저 패키징

D:\unreal_mcp\Unreal_mcp\scripts\package-plugin.bat "D:\Epic Library\UE_5.6" "D:\unreal_mcp\build"

패키징된 결과물의 descriptor는 아래와 같은 형태
EngineVersion은 5.6.0으로 표시되지만 실제 패키징/사용 엔진은 UE 5.6.1

{
  "FileVersion": 3,
  "Version": 3,
  "VersionName": "0.1.4",
  "FriendlyName": "MCP Automation Bridge",
  "EngineVersion": "5.6.0",
  "CanContainContent": false,
  "IsBetaVersion": true,
  "IsExperimentalVersion": true,
  "Modules": [
    {
      "Name": "McpAutomationBridge",
      "Type": "Editor",
      "LoadingPhase": "Default",
      "PlatformAllowList": [
        "Win64",
        "Mac",
        "Linux"
      ]
    }
  ],
  "Installed": true
}

패키징 결과물 McpAutomationBridge를 프로젝트에 복사

패키징 결과물:

..\unreal_mcp\build\McpAutomationBridge

프로젝트 설치 위치:

UnrealProject\Plugins\McpAutomationBridge

참고용 패키징 결과물:
패키징한 결과물

.uproject에서 McpAutomationBridge 플러그인을 Editor 전용으로 활성화

{
  "FileVersion": 3,
  "EngineAssociation": "5.6",
  "Category": "",
  "Description": "",
  "Plugins": [
    {
      "Name": "ModelingToolsEditorMode",
      "Enabled": true,
      "TargetAllowList": [
        "Editor"
      ]
    },
    {
      "Name": "McpAutomationBridge",
      "Enabled": true,
      "TargetAllowList": [
        "Editor"
      ]
    }
  ]
}

DefaultGame.ini에서 Native MCP 활성화

추가한 설정:

[/Script/McpAutomationBridge.McpAutomationBridgeSettings]
bEnableNativeMCP=True

현재 프로젝트의 관련 내용:

[/Script/CommonUI.CommonUISettings]
CommonButtonAcceptKeyHandling=TriggerClick

[/Script/EngineSettings.GeneralProjectSettings]
ProjectID=397FFA41432F1E395F7D339B622127AB

[/Script/McpAutomationBridge.McpAutomationBridgeSettings]
bEnableNativeMCP=True

엔진 코드 수정(UE 5.6.1 기준)

플러그인 패키징 중 UE 5.6.1의 UBT에서 moduleType == null 상황으로 패키징이 실패해서, 아래 파일에 null guard를 추가

Epic Library\UE_5.6\Engine\Source\Programs\UnrealBuildTool\Configuration\ModuleRules.cs

수정된 부분:

internal static bool IsValidForTarget(Type moduleType, ReadOnlyTargetRules targetRules, [NotNullWhen(false)] out string? invalidReason)
{
    if (moduleType == null)
    {
        invalidReason = "ModuleRules type is null";
        return false;
    }

    IEnumerable<TargetType> supportedTargetTypes = moduleType.GetCustomAttributes<SupportedTargetTypesAttribute>().SelectMany(x => x.TargetTypes).Distinct();
    ...
}

수정된 UBT를 반영하기 위해 UnrealBuildTool.dll도 다시 빌드해서 교체

백업 파일:

D:\Epic Library\UE_5.6\Engine\Source\Programs\UnrealBuildTool\Configuration\ModuleRules.cs.codex-backup-20260421
D:\Epic Library\UE_5.6\Engine\Binaries\DotNET\UnrealBuildTool\codex-backup-20260421\UnrealBuildTool.dll

---

C++ 프로젝트인 경우 (5.7.1)

C++ 프로젝트는 프로젝트 빌드 체인에서 플러그인 모듈을 직접 컴파일할 수 있으므로, Blueprint 프로젝트처럼 패키징된 플러그인을 쓰기보다 원본 플러그인을 프로젝트 로컬 Plugins에 복사해서 빌드

적용 전 정리

Unreal Editor를 닫고 Live Coding을 끈다. Editor가 열려 있거나 Live Coding mutex가 남아 있으면 아래 빌드에서 실패한다.

Unreal_mcp plugins\내용을 프로젝트 Plugins에 복사

프로젝트 설치 위치의 Plugins\에 복사

.uproject에서 플러그인 활성화

.uproject

{
  "FileVersion": 3,
  "EngineAssociation": "5.7",
  "Category": "",
  "Description": "",
  "Modules": [
    {
      "Name": "ProjectName",
      "Type": "Runtime",
      "LoadingPhase": "Default"
    }
  ],
  "Plugins": [
    {
      "Name": "ModelingToolsEditorMode",
      "Enabled": true,
      "TargetAllowList": [
        "Editor"
      ]
    },
    {
      "Name": "McpAutomationBridge",
      "Enabled": true,
      "TargetAllowList": [
        "Editor"
      ]
    }
  ]
}

DefaultGame.ini에서 브리지 포트와 Native MCP 활성화

Config\DefaultGame.ini 설정

[/Script/McpAutomationBridge.McpAutomationBridgeSettings]
bAllowNonLoopback=False
ListenHost=127.0.0.1
ListenPorts=8091
bEnableNativeMCP=True

Editor 로그에서 정상적으로 로드되면 Log로 아래내용이 뜬다.

LogPluginManager: Mounting Project plugin McpAutomationBridge
LogMcpAutomationBridge: MCP Automation Bridge module initialized.
LogMcpAutomationBridgeSubsystem: AttemptConnection: creating server listener on 127.0.0.1:8091
LogMcpAutomationBridgeSubsystem: Automation bridge listening on port=8091

이 로그는 Editor 쪽 브리지가 8091에서 대기 중이라는 뜻.
Codex MCP 서버가 실제로 붙었는지는 별도로 ue://health에서 connected를 확인.

Codex config.toml 설정

.codex\config.toml에는 MCP 서버와 환경변수를 아래처럼 설정.

[mcp_servers.unreal-engine]
command = "node"
args = [ "D:/Unreal_mcp/dist/cli.js" ]

[mcp_servers.unreal-engine.env]
UE_PROJECT_PATH = "G:/UnrealProject/unrealproject.uproject"
MCP_AUTOMATION_HOST = "127.0.0.1"
MCP_AUTOMATION_PORT = "8091"
MCP_AUTOMATION_WS_PORT = "8091"
MCP_AUTOMATION_CLIENT_PORT = "8091"

MCP_AUTOMATION_PORT만으로는 부족할 수 있다.

실제로 확인한 Unreal_mcp 런타임에서
실제 연결 포트에 MCP_AUTOMATION_WS_PORT와
MCP_AUTOMATION_CLIENT_PORT를 사용했다.

그래서 세 값을 모두 8091로 맞췄다.

node dist/cli.js는 Codex가 MCP 서버로 자동 실행.
수동으로 켜둘 필요는 없고, 수동 실행은 단독 테스트용이다.

프로젝트 빌드

플러그인을 프로젝트 로컬로 복사하고 .uproject를 수정한 뒤 UnrealEditor를 빌드
성공 시 아래 파일이 생성된다.

G:\UnrealProject\Plugins\McpAutomationBridge\Binaries\Win64\UnrealEditor-McpAutomationBridge.dll
G:\UnrealProject\Plugins\McpAutomationBridge\Binaries\Win64\UnrealEditor-McpAutomationBridge.pdb
G:\UnrealProject\Plugins\McpAutomationBridge\Binaries\Win64\UnrealEditor.modules

최종 실행 순서

1. Codex 다시 실행
2. Unreal Editor 실행
3. Codex에서 Unreal MCP tool 또는 ue://actors 같은 리소스를 호출해서 실제 연결 유도

ue://health만 먼저 보면 연결 전 상태라 disconnected로 보일 수 있다.
ue://actors처럼 Editor 요청을 실제로 보내면 handshake가 일어나고, 이후 ue://health에서 연결 상태가 갱신된다.

연결 확인 결과

ue://actors 호출이 성공했고 현재 레벨 Actor 목록을 읽었다.

{
  "success": true,
  "count": 8
}

이후 ue://health에서 아래 상태를 확인

{
  "status": "connected",
  "automationBridge": {
    "connected": true,
    "activePort": 8091
  },
  "unrealConnection": {
    "features": {
      "automationBridgeConnected": true
    }
  }
}

---

내용에 대한 질의나, 수정 요청은 저에게 큰 도움이 됩니다.