네이티브 C++ Automation Bridge 플러그인을 통해 AI 어시스턴트가 Unreal Engine을 제어할 수 있도록 지원하는 포괄적인 Model Context Protocol (MCP) 서버입니다. TypeScript와 C++로 구축되었습니다.

• 주요 기능 (Features)
• 시작하기 (Getting Started)
• 설정 (Configuration)
• 사용 가능한 도구 (Available Tools)
• Docker
• 문서 (Documentation)
• 커뮤니티 (Community)
• 개발 (Development)
• 기여하기 (Contributing)

카테고리 (Category)	기능 (Capabilities)
에셋 관리 (Asset Management)	에셋 탐색, 가져오기, 복제, 이름 변경, 삭제; 머티리얼 (Material) 생성
액터 제어 (Actor Control)	스폰 (Spawn), 삭제, 트랜스폼 (Transform), 물리 (Physics), 태그 (Tags), 컴포넌트 (Components)
에디터 제어 (Editor Control)	PIE 세션, 카메라, 뷰포트 (Viewport), 스크린샷, 북마크
레벨 관리 (Level Management)	레벨 로드/저장, 스트리밍 (Streaming), 라이팅 (Lighting)
애니메이션 및 물리 (Animation & Physics)	애니메이션 블루프린트 (Animation BPs), 스테이트 머신 (State Machines), 래그돌 (Ragdolls), 차량 (Vehicles), 컨스트레인트 (Constraints)
시각 효과 (Visual Effects)	Niagara 파티클, GPU 시뮬레이션, 절차적 효과 (Procedural effects), 디버그 셰이프 (Debug shapes)
시퀀서 (Sequencer)	시네마틱 (Cinematics), 타임라인 제어, 카메라 애니메이션, 키프레임 (Keyframes)
그래프 편집 (Graph Editing)	블루프린트 (Blueprint), Niagara, 머티리얼 (Material), 비헤이비어 트리 (Behavior Tree) 그래프 조작
오디오 (Audio)	사운드 큐 (Sound cues), 오디오 컴포넌트, 사운드 믹스 (Sound mixes), 환경음 (Ambient sounds)
시스템 (System)	콘솔 명령 (Console commands), UBT, 테스트, 로그, 프로젝트 설정, CVars

네이티브 C++ 자동화 (Native C++ Automation)— 모든 작업은 MCP Automation Bridge 플러그인을 통해 전달됩니다. 이중 전송 (Dual Transport)— 네이티브 HTTP/SSE (브릿지 불필요) 또는 TypeScript 브릿지를 통한 WebSocket을 지원합니다. 동적 타입 발견 (Dynamic Type Discovery)— 라이트, 디버그 셰이프 및 시퀀서 트랙에 대한 런타임 인트로스펙션 (Introspection)을 지원합니다. 우아한 성능 저하 (Graceful Degradation)— 활성화된 Unreal 연결이 없어도 서버가 시작됩니다. 온디맨드 연결 (On-Demand Connection)— 지수 백오프 (Exponential backoff)를 사용하여 자동화 핸드셰이크를 재시도합니다. 명령 안전성 (Command Safety)— 패턴 기반 검증을 통해 위험한 콘솔 명령을 차단합니다. 기능 토큰 인증 (Capability Token Auth)— WS 및 HTTP 전송 모두에 대해 선택적인 토큰 기반 인증을 제공합니다. 에셋 캐싱 (Asset Caching)— 성능 향상을 위해 10초의 TTL을 적용합니다. 메트릭 속도 제한 (Metrics Rate Limiting)— Prometheus 엔드포인트에 대해 IP당 속도 제한(분당 60회 요청)을 적용합니다. 중앙 집중식 설정 (Centralized Configuration)— 통합된 클래스 별칭 및 타입 정의를 제공합니다.

Unreal Engine 5.0–5.8 (5.8 프리뷰 검증 완료)

전송 방식(Transport)을 선택하세요:

옵션 A: Native MCP(권장) — 추가 종속성 없음
옵션 B: TypeScript Bridge — Node.js 18 이상 필요

아래의 Option A: Native MCP Transport(단계 4A)를 사용하는 경우 이 단계를 건너뛰세요.

NPX (권장):

npx unreal-engine-mcp-server

복제 및 빌드 (Clone & Build):

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

MCP Automation Bridge 플러그인은 Unreal_mcp/plugins/McpAutomationBridge에 포함되어 있습니다.

프로젝트에는 반드시 코드 타겟(.sln 또는 .xcworkspace)이 있어야 합니다.
Blueprint 전용 프로젝트는 네이티브 플러그인(Native Plugin)을 컴파일할 수 없습니다. 변환하려면 에디터의 Tools > New C++ Class를 통해 임의의 클래스를 추가하세요.

방법 1: 폴더 복사

복사: Unreal_mcp/plugins/McpAutomationBridge/
대상: YourUnrealProject/Plugins/McpAutomationBridge/

방법 2: 외부 플러그인 디렉토리 (복사 불필요)

• Unreal Editor 실행 → Edit → Plugins - Plugin Directories(좌측 하단) 클릭 - Additional Plugin Directories에 Unreal_mcp/plugins/ 경로를 추가
• 에디터 재시작 — 외부 위치에서 플러그인을 인식합니다.

이 방식은 .uproject 파일에 경로를 저장하므로, 복사 없이도 플러그인 연결 상태가 유지됩니다.

프로젝트를 열 때 플러그인이 자동으로 컴파일됩니다. UE가 .uplugin과 Source/를 감지하고 UnrealBuildTool을 실행합니다.

비디오 가이드:

Plugin_setup_guide.mp4

⚠️ 프로젝트 최초 실행 시: UE에서 "Would you like to rebuild them now?"라는 메시지가 표시되면 Yes를 클릭하세요. 만약 "Missing Modules — McpAutomationBridge. Engine modules cannot be compiled at runtime. Please build through your IDE."라는 메시지가 나타나면, Visual Studio(Windows) 또는 Xcode(Mac)에서 프로젝트를 열고 거기서 빌드하십시오. 그 이후에는 플러그인이 로드된 상태로 에디터가 정상적으로 열립니다.

플러그인을 한 번 빌드한 후 컴파일된 바이너리(Compiled Binaries)를 배포하면, 대상 머신에서는 IDE나 컴파일 과정이 필요하지 않습니다.

1. 빌드:

# macOS / Linux
./scripts/package-plugin.sh /path/to/UE_5.6
# Windows
...

이 과정은 McpAutomationBridge-v0.5.30-UE5.6-Mac.zip과 같은 zip 파일을 생성합니다.

.

2. 설치: YourProject/Plugins/ 폴더에 압축을 풉니다.

그 다음 프로젝트를 엽니다. 이것으로 끝입니다 — 별도의 컴파일 (Compilation) 단계가 필요하지 않습니다.

참고: 사전 빌드된 바이너리 (Pre-built binaries)는 특정 UE 버전에 종속됩니다. 5.6용 빌드는 5.5, 5.7 또는 5.8에서 작동하지 않습니다.

Edit → Plugins를 통해 활성화한 후, 에디터를 재시작하십시오.

핵심 플러그인 (필수)

플러그인 (Plugin)	용도
MCP Automation Bridge	모든 자동화 작업
Python Editor Script Plugin	Python 기반 에디터 자동화 헬퍼
Editor Scripting Utilities	에셋/액터 (Asset/Actor) 서브시스템 작업
Niagara	시각 효과 및 파티클 시스템
Gameplay Abilities	manage_gas 작업
Smart Objects	AI 스마트 오브젝트 작업

선택적 플러그인 (자동 활성화)

플러그인 (Plugin)	용도
Level Sequence Editor	manage_sequence 작업
Control Rig	animation_physics 작업
GeometryScripting	manage_geometry 작업
Behavior Tree Editor	manage_ai 비헤이비어 트리 (Behavior Tree) 작업
Niagara Editor	Niagara 제작
Environment Query Editor	AI/EQS 작업
MetaSound	manage_audio MetaSound 제작
StateTree	manage_ai 스테이트 트리 (State Tree) 작업
Enhanced Input	manage_networking 입력 매핑 작업
Chaos Cloth	천 시뮬레이션 (Cloth simulation)
Interchange	에셋 임포트/익스포트 (Asset import/export)
Data Validation	데이터 검증
PCG	빌드에 활성화된 경우 manage_pcg 그래프 제작 및 실행
Procedural Mesh Component	절차적 지오메트리 (Procedural geometry)
OnlineSubsystem	세션/네트워킹 작업
OnlineSubsystemUtils	세션/네트워킹 작업

💡 선택적 플러그인은 필요할 때 MCP Automation Bridge 플러그인에 의해 자동으로 활성화됩니다. PCG 지원은 프로젝트에서 PCG를 명시적으로 활성화할 때 소스 프로젝트를 위해 컴파일됩니다. UE 5.2 이상을 위한 버전별 릴리스 패키지에는 PCG 지원이 포함되어 있습니다.

이 플러그인은 내장된 MCP Streamable HTTP 서버를 포함하고 있습니다. AI 클라이언트들은 HTTP를 통해 플러그인에 직접 연결됩니다. TypeScript 브리지, Node.js, npm이 필요하지 않습니다.

Unreal에서 활성화하기:

Edit > Project Settings > Plugins > MCP Automation Bridge - 체크
Enable Native MCP - 포트 설정 (기본값: 3000)

• 선택 사항: 프로젝트별 가이드를 위한 Native MCP Instructions 설정
• 에디터 재시작

다음 주소에서 Streamable HTTP 전송 방식을 사용하도록 MCP 클라이언트를 구성하세요:

Claude Code:

claude mcp add unreal-engine --transport http http://localhost:3000/mcp

또는 ~/.claude/settings.json 또는 프로젝트의 .mcp.json 파일에서 수동으로 설정:

{
"mcpServers": {
"unreal-engine": {
...

Cursor (.cursor/mcp.json):

{
"mcpServers": {
"unreal-engine": {
...

작동 여부 확인:

상태 표시줄 (Status bar) — 에디터 우측 하단에서 ● MCP :3000 (2)를 찾으세요. 녹색 점은 서버가 실행 중임을 의미하며, 괄호 안의 숫자는 활성 세션(active sessions) 수를 나타냅니다. 클릭하여 설정을 열 수 있습니다.
출력 로그 (Output Log) — LogMcpNativeTransport로 필터링하여 연결, 도구 호출(tool calls) 및 세션 활동을 확인하세요: LogMcpNativeTransport: Native MCP server started on http://localhost:3000/mcp LogMcpNativeTransport: MCP session initialized: ... (client: claude-code 2.1.92, active sessions: 1) LogMcpNativeTransport: tools/call: inspect (RequestId=...) LogMcpNativeTransport: tools/call completed: ... (tool=inspect, success=true)

기능:

• 긴 작업 수행 중 실시간 진행 상황을 위한 SSE 스트리밍 (SSE streaming)
• 다중 동시 세션 (Cursor + Claude Code + 기타 도구 동시 사용 가능)
• 동적 도구 관리 (Dynamic tool management) — 핵심 도구는 기본적으로 로드되며, manage_tools를 통해 더 많은 도구를 활성화할 수 있습니다.
• execute_python 액션을 통한 Python 실행 (인라인 코드 또는 .py 파일)
• 기능 토큰 인증 (Capability token authentication) — 네트워크 보안을 위해 프로젝트 설정에서 활성화할 수 있습니다.

Claude Desktop / Cursor 설정 파일에 추가하세요:

Clone/Build 사용 시:

{
"mcpServers": {
"unreal-engine": {
...

NPX 사용 시:

{
"mcpServers": {
"unreal-engine": {
...

필수 사항

UE_PROJECT_PATH="C:/Path/To/YourProject"

Automation Bridge (자동화 브리지)

...

기본적으로, 보안을 위해 자동화 브리지(automation bridge)는 루프백 주소(127.0.0.1)에만 바인딩됩니다. 네트워크상의 다른 머신에서 액세스를 허용하려면 다음 설정을 수행하세요:

TypeScript (MCP Server):

MCP_AUTOMATION_ALLOW_NON_LOOPBACK=true
MCP_AUTOMATION_HOST=0.0.0.0

Unreal Engine Plugin:

• Edit → Project Settings → Plugins → MCP Automation Bridge로 이동합니다. - Security 항목에서 **"Allow Non Loopback"**을 활성화합니다. - Connection 항목에서 **"Listen Host"**를 0.0.0.0으로 설정합니다.

• 에디터를 재시작합니다.

보안 경고: LAN 액세스를 활성화하면 자동화 브리지가 로컬 네트워크에 노출됩니다. 적절한 방화벽 규칙이 있는 신뢰할 수 있는 네트워크에서만 사용하십시오. LAN 모드를 사용할 때는 무단 액세스를 방지하기 위해 기능 토큰 인증(capability token authentication)을 활성화하십시오 (프로젝트 설정에서 Require Capability Token 활성화).

광범위한 all-tools 모드에서 **23개의 MCP 도구(tools)**가 노출됩니다. 관련 액션(actions)은 부모 도구에 직접 포함되어 있어, 클라이언트가 기능을 잃지 않으면서도 더 적은 컨텍스트(context)를 로드할 수 있습니다.

핵심 도구 (Core Tools)

도구 (Tool)	설명 (Description)
manage_asset	에셋(Assets), 머티리얼(Materials), 렌더 타겟(Render Targets), 비헤이비어 트리(Behavior Trees)
manage_blueprint	블루프린트(Blueprints), SCS 컴포넌트(SCS components), 그래프 편집(graph editing), UMG 위젯(UMG widgets), 레이아웃(layout), 바인딩(bindings), 애니메이션(animations)
control_actor	스폰(Spawn), 삭제(delete), 트랜스폼(transform), 물리(physics), 태그(tags)
control_editor	PIE, 카메라(Camera), 뷰포트(viewport), 스크린샷(screenshots)
manage_level	로드/저장(Load/save), 스트리밍(streaming), 라이팅(lighting)
system_control	UBT, 테스트(Tests), 로그(Logs), 프로젝트 설정(Project Settings), CVars, Python 실행(Python Execution)
inspect	오브젝트 인트로스펙션(Object Introspection)
manage_tools	동적 도구 관리 (런타임 시 활성화/비활성화)

월드 빌딩 (World Building)

도구 (Tool)	설명 (Description)
build_environment	지형 (Landscapes), 식생 (foliage), 절차적 지형 (procedural terrain), 조명 (lighting), 스플라인 도로/강/울타리 (spline roads/rivers/fences)
manage_level_structure	레벨 (Levels), 서브레벨 (sublevels), 월드 파티션 (World Partition), 스트리밍 (streaming), 데이터 레이어 (data layers), HLOD, 볼륨 (volumes)
manage_geometry	Geometry Script를 사용한 절차적 메쉬 (procedural mesh) 생성 및 편집
manage_pcg	PCG 그래프 에셋 (PCG graph assets), 서브그래프 (subgraphs), 입력/샘플러/필터/스포너 노드 (input/sampler/filter/spawner nodes), 핀 연결 (pin connections), 실행 (execution), 파티션 그리드 크기 (partition grid size), 노드 설정 (node settings)

게임플레이 시스템 (Gameplay Systems)

도구 (Tool)	설명 (Description)
animation_physics	애니메이션 블루프린트 (Animation BPs), 스켈레톤 (skeletons), 소켓 (sockets), 피직스 에셋 (physics assets), 클로스 (cloth), 차량 (vehicles), 래그돌 (ragdolls), 컨트롤 리그 (Control Rig), IK
manage_effect	Niagara, 파티클 (particles), 디버그 셰이프 (debug shapes), GPU 시뮬레이션 (GPU simulations)
manage_gas	게임플레이 어빌리티 시스템 (Gameplay Ability System): 어빌리티 (abilities), 이펙트 (effects), 속성 (attributes)
manage_character	캐릭터 생성 (Character creation), 이동 (movement), 고급 로코모션 (advanced locomotion)
manage_combat	무기 (Weapons), 투사체 (projectiles), 데미지 (damage), 근접 전투 (melee combat)
manage_ai	AI 컨트롤러 (AI controllers), 비헤이비어 트리 (Behavior Trees), EQS, 인지 (perception), 스테이트 트리 (State Trees), 스마트 오브젝트 (Smart Objects), NavMesh/경로 탐색 (pathfinding)
manage_inventory	아이템 (Items), 장비 (equipment), 루팅 테이블 (loot tables), 제작 (crafting)
manage_interaction	상호작용 오브젝트 (Interactables), 파괴 가능한 오브젝트 (destructibles), 트리거 (triggers)

유틸리티 (Utility)

도구 (Tool)	설명 (Description)
manage_audio	오디오 에셋 (Audio Assets), 컴포넌트 (Components), 사운드 큐 (Sound Cues), MetaSounds, 감쇠 (Attenuation)
manage_sequence	시퀀서 (Sequencer), 시네마틱 (cinematics), 바인딩 (bindings), 트랙 (tracks), 재생 (playback), 키프레임 (keyframes)
manage_networking	복제 (Replication), RPCs, 네트워크 예측 (network prediction), 세션 (sessions), 분할 화면 (split-screen), LAN/음성 (voice), 게임 프레임워크 (game framework), 입력 매핑 (input mappings)

블루프린트 (Blueprints) • 머티리얼 (Materials) • 텍스처 (Textures) • 스태틱 메쉬 (Static Meshes) • 스켈레탈 메쉬 (Skeletal Meshes) • 레벨 (Levels) • 사운드 (Sounds) • 파티클 (Particles) • Niagara 시스템 (Niagara Systems) • 비헤이비어 트리 (Behavior Trees)

docker build -t unreal-mcp .
docker run -it --rm -e UE_PROJECT_PATH=/project unreal-mcp

문서 (Document)	설명 (Description)
핸들러 매핑 (Handler Mappings)	TypeScript에서 C++로의 라우팅 (TypeScript to C++ routing)
...

npm run build # TypeScript 빌드
npm run lint # ESLint 실행
npm run test:unit # 유닛 테스트 실행
...

리소스	설명
프로젝트 로드맵 (Project Roadmap)	48개 단계에 걸친 개발 진행 상황 추적
...

기여(Contributions)를 환영합니다! 다음 사항을 준수해 주세요:

• 버그 발생 시 재현 단계 (reproduction steps)를 포함해 주세요
• Pull Request (PR)는 집중적이고 작게 유지해 주세요
• 기존 코드 스타일 (code style)을 따라 주세요

MIT — LICENSE를 참조하세요