MCP를 통해 AI 어시스턴트를 Unreal Editor에 직접 연결하기

MCP를 통해 AI 어시스턴트를 Unreal Editor에 직접 연결하기

기능 · 설치 · 사용법 · 도구 참조 · 문제 해결

Unreal MCP는 Model Context Protocol (MCP)을 통해 AI 어시스턴트를 Unreal Editor에 연결합니다. 액터(Actor) 생성, Blueprint 그래프 구축, Behavior Tree 구성, UMG 위젯 디자인, 머티리얼(Material) 편집 등 모든 작업을 자연어(Natural Language)로 수행할 수 있습니다.

84개의 내장 도구(Built-in tools)를 제공하며, Unreal Engine의 모든 Python API에 직접 접근할 수 있습니다. 즉, 모든 BlueprintCallable 함수, 모든 에디터 서브시스템(Editor subsystem), 엔진이 Python에 노출하는 모든 것에 접근 가능합니다. C++이나 재컴파일(Recompilation)은 필요하지 않습니다.

클릭하여 YouTube에서 데모 시청

카테고리	기능	도구 수
액터 조작 (Actor Manipulation)	액터 생성, 복제, 변형, 삭제. Surface 레이캐스팅 (Raycasting). View frustum 쿼리. 속성(Property) Get/Set.	17
레벨 관리 (Level Management)	레벨 생성 및 열기. 선택적 클래스 필터를 사용하여 레벨 액터 목록 표시. 월드 설정(중력, 시간 팽창) 구성.	4
에셋 관리 (Asset Management)	이름/유형별 에셋 검색 및 필터링. 스태틱 메시(Static mesh) 상세 정보 검색.	2
머티리얼 시스템 (Material System)	표현식(Expressions) 생성 및 연결. 머티리얼 인스턴스 파라미터 (스칼라, 벡터, 텍스처, 스태틱 스위치). 재컴파일 (Recompilation).	11
Blueprint 그래프 (Blueprint Graph)	그래프 구조, 노드(Node), 핀(Pin), 변수 읽기. 노드 추가, 연결, 제거. 전체 그래프 구축 및 컴파일. SCS 컴포넌트 관리. 자동 레이아웃 (Auto layout).	16
Behavior Tree	Behavior Tree 생성 및 읽기. Blackboard 에셋 및 키 관리. 완전한 BT 계층 구조 구축.	12
UMG 위젯 블루프린트 (UMG Widget Blueprint)	위젯 블루프린트 생성. 위젯 추가/제거 (15개 유형). 속성, 슬롯 레이아웃, 텍스트 스타일 및 위젯 C++ 속성 설정. 컴파일.	10
에디터 도구 (Editor Tools)	선택 관리 (Selection management). 액터의 머티리얼/메시 교체. Blueprint 기반 교체.	6
게임 설정 (Game Settings)	게임 모드(Game mode) 구성. 입력 액션(Input action) 및 매핑 설정.	3
유틸리티 (Utilities)	Unreal Engine의 Python API에 대한 전체 접근 권한을 가진 임의의 Python 실행. 출력 로그(Output log) 검색. LiveCoding 컴파일.	3

Unreal Engine 5.6+ Python 3.11+ uv— 빠른 Python 패키지 매니저(package manager)— MCP 클라이언트 (MCP client) (Claude Desktop, VS Code, Cursor 등)

옵션 A: GitHub에서 클론 (권장)

cd YourProject/Plugins
git clone https://github.com/GenOrca/unreal-mcp.git

YourProject/
└── Plugins/
└── unreal-mcp/
...

옵션 B: Fab에서 설치

참고

Fab 버전은 최신 GitHub 릴리스보다 뒤처질 수 있습니다. Fab에서 설치한 후에도 이 저장소의 mcp-server/ 폴더가 여전히 필요합니다.

• Unreal Engine에서 프로젝트를 엽니다.
• Edit > Plugins — Unreal-MCPython 및 Python Editor Script Plugin을 활성화합니다.
• 에디터를 재시작합니다.

MCP 클라이언트 설정에 서버를 추가합니다:

{
"mcpServers": {
"unreal-mcpython": {
...

중요

경로를 mcp-server 폴더의 실제 절대 경로(absolute path)로 교체하십시오.

클라이언트별 설정 파일 위치

클라이언트	경로
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
VS Code / Cursor	워크스페이스 내의 .vscode/mcp.json

• MCP 클라이언트를 재시작합니다.
• MCP 서버가 자동으로 시작됩니다.
• 확인 — 클라이언트에 Unreal-MCPython 도구들이 나열되어 있어야 합니다.

원하는 내용을 자연어로 설명하기만 하면 됩니다:

"지형 표면에 나무 10개를 무작위로 배치해줘"
"이름에 'rock'이 포함된 모든 스태틱 메시(static meshes)를 찾아줘"
"MI_Ground의 베이스 컬러(base color)를 진한 갈색으로 설정해줘"
...

액터 조작 (Actor Manipulation) (17개 도구)

도구 (Tool)	설명 (Description)
spawn_from_object	기존 에셋 (Asset)으로부터 액터 (Actor) 스폰
spawn_from_class	클래스 (Class)로부터 액터 (Actor) 스폰
spawn_on_surface_raycast	레이캐스트 (Raycast)를 통해 표면 위에 액터 (Actor) 스폰
duplicate_selected	선택된 액터 (Actors) 복제
delete_by_label	라벨 (Label)에 따라 액터 (Actors) 삭제
select_all	모든 액터 (Actors) 선택
invert_selection	현재 선택 영역 반전
list_all_with_locations	위치 정보를 포함한 모든 액터 (Actors) 목록 나열
get_all_details	액터 (Actors)에 대한 상세 정보 가져오기
set_transform	전체 트랜스폼 (Transform: 위치, 회전, 스케일) 설정
set_location	액터 (Actor) 위치 설정
set_rotation	액터 (Actor) 회전 설정
set_scale	액터 (Actor) 스케일 설정
get_property	액터 (Actor) 속성 (Property) 값 가져오기
set_property	액터 (Actor) 속성 (Property) 값 설정
line_trace	라인 트레이스 (Line Trace) 레이캐스트 (Raycast) 수행
get_in_view_frustum	카메라 시야 절두체 (View Frustum) 내의 액터 (Actors) 가져오기

레벨 관리 (Level Management) (4개 도구)

도구 (Tool)	설명 (Description)
create_level	새로운 빈 레벨 (Level)을 생성하고 열기
load_level	콘텐츠 브라우저 (Content-browser) 경로를 통해 기존 레벨 (Level) 열기
list_level_actors	현재 레벨 (Level)의 모든 액터 (Actors) 목록 나열 (선택적 클래스 필터 적용 가능)
set_world_settings	현재 레벨 (Level)의 중력 (Gravity) 및 시간 팽창 (Time Dilation) 설정

에셋 관리 (Asset Management) (2개 도구)

도구 (Tool)	설명 (Description)
find_by_query	이름/유형별 에셋 (Assets) 검색 및 필터링
get_static_mesh_details	스태틱 메시 (Static Mesh) 상세 정보 가져오기

머티리얼 시스템 (Material System) (11개 도구)

도구 (Tool)	설명 (Description)
create_expression	머티리얼 익스프레션 (Material Expression) 노드 생성
connect_expressions	두 개의 머티리얼 익스프레션 (Material Expression) 연결
recompile	머티리얼 (Material) 재컴파일
get_mi_scalar_param	머티리얼 인스턴스 (Material Instance)에서 스칼라 파라미터 (Scalar Parameter) 가져오기
set_mi_scalar_param	머티리얼 인스턴스 (Material Instance)에 스칼라 파라미터 (Scalar Parameter) 설정
get_mi_vector_param	머티리얼 인스턴스 (Material Instance)에서 벡터 파라미터 (Vector Parameter) 가져오기
set_mi_vector_param	머티리얼 인스턴스 (Material Instance)에 벡터 파라미터 (Vector Parameter) 설정
get_mi_texture_param	머티리얼 인스턴스 (Material Instance)에서 텍스처 파라미터 (Texture Parameter) 가져오기
set_mi_texture_param	머티리얼 인스턴스 (Material Instance)에 텍스처 파라미터 (Texture Parameter) 설정
get_mi_static_switch	머티리얼 인스턴스 (Material Instance)에서 스태틱 스위치 (Static Switch) 가져오기
set_mi_static_switch	머티리얼 인스턴스 (Material Instance)에 스태틱 스위치 (Static Switch) 설정

Blueprint Graph (16개 도구)

도구 (Tool)	설명 (Description)
get_selected_bp_nodes	선택된 블루프린트 (Blueprint) 노드 가져오기
get_selected_bp_node_infos	선택된 노드의 상세 정보 가져오기
get_blueprint_graph_info	전체 그래프 구조 읽기
list_callable_functions	블루프린트 (Blueprint) 컨텍스트 내에서 호출 가능한 함수 목록 나열
list_blueprint_variables	블루프린트 (Blueprint) 변수 목록 나열
add_blueprint_node	그래프에 노드 추가
connect_blueprint_pins	두 개의 핀 (Pin) 연결
remove_blueprint_node	노드 제거
build_blueprint_graph	JSON으로부터 전체 그래프 구축
compile_blueprint	블루프린트 (Blueprint) 컴파일
list_blueprint_components	블루프린트 (Blueprint)의 모든 SCS 컴포넌트 목록 나열
add_component_to_blueprint	블루프린트 (Blueprint)의 SCS에 컴포넌트 추가
remove_component_from_blueprint	블루프린트 (Blueprint)의 SCS에서 컴포넌트 제거
set_component_property	블루프린트 (Blueprint) 컴포넌트 템플릿의 속성 설정
set_blueprint_node_position	블루프린트 (Blueprint) 그래프 노드를 지정된 좌표로 이동
auto_layout_graph	블루프린트 (Blueprint) 그래프의 모든 노드 자동 레이아웃

Behavior Tree (12개 도구)

도구 (Tool)	설명 (Description)
list_behavior_trees	모든 Behavior Tree (BT) 에셋 목록 나열
get_behavior_tree_structure	BT 구조 읽기
get_blackboard_data	Blackboard 데이터 가져오기
get_bt_node_details	BT 노드 상세 정보 가져오기
get_selected_bt_nodes	선택된 BT 노드 가져오기
create_behavior_tree	새로운 Behavior Tree 생성
create_blackboard	새로운 Blackboard 생성
add_blackboard_key	Blackboard에 키 추가
remove_blackboard_key	Blackboard에서 키 제거
set_blackboard_to_behavior_tree	BT에 Blackboard 할당
build_behavior_tree	완전한 BT 계층 구조 구축
list_bt_node_classes	사용 가능한 BT 노드 클래스 목록 나열

UMG Widget Blueprint (10개 도구)

도구 (Tool)	설명 (Description)
create_widget_blueprint	새로운 Widget Blueprint 에셋 생성
get_widget_blueprint_info	위젯 트리 계층 구조 및 위젯 목록 가져오기
add_widget	트리에 위젯 추가 (15개 유형 지원)
set_widget_properties	텍스트, 글꼴 크기, 색상, 가시성, Canvas Slot 레이아웃 설정
remove_widget	트리에서 위젯 제거
compile_widget_blueprint	Widget Blueprint 컴파일 및 유효성 검사
set_slot_layout	CanvasPanelSlot 레이아웃 설정 (앵커, 위치, 크기, 정렬)
set_text_style	TextBlock의 글꼴 크기, 텍스트 색상 및 외곽선 설정
get_widget_property	지정된 위젯의 C++ UPROPERTY 값 가져오기
set_widget_property	지정된 위젯의 C++ UPROPERTY 값 설정

지원되는 위젯 유형: CanvasPanel, TextBlock, Button, Image, HorizontalBox, VerticalBox, Border, Overlay, ScrollBox, SizeBox, CheckBox, EditableText, EditableTextBox, ProgressBar, Slider

Editor Tools (6개 도구)

도구 (Tool)	설명 (Description)
get_selected_assets	현재 선택된 에셋 (assets) 가져오기
replace_mtl_on_selected	선택된 액터 (actors)의 머티리얼 (material) 교체
replace_mtl_on_specified	지정된 액터 (actors)의 머티리얼 (material) 교체
replace_mesh_on_selected	선택된 액터 (actors)의 메시 (mesh) 교체
replace_mesh_on_specified	지정된 액터 (actors)의 메시 (mesh) 교체
replace_selected_with_bp	선택된 액터 (actors)를 블루프린트 (Blueprint)로 교체

Game Settings (3개 도구) & Utilities (3개 도구)

도구 (Tool)	설명 (Description)
set_game_mode	게임 모드 (game mode) 설정
add_input_action	입력 액션 (input action) 추가
add_input_mapping	입력 매핑 (input mapping) 추가
get_output_log	Unreal 출력 로그 (output log) 검색
execute_python	Unreal Engine의 Python API에 대한 전체 권한을 가진 임의의 Python 코드 실행
livecoding_compile	에디터를 재시작하지 않고 LiveCoding C++ 핫 리로드 (hot-reload) 컴파일 트리거

문제 (Problem)	해결책 (Solution)
MCP 서버가 시작되지 않음	Python 3.11+ 및 uv가 설치되어 있는지 확인
...

GitHub에서 이슈 (Issues), 기능 요청 (feature requests), 그리고 풀 리퀘스트 (pull requests)를 환영합니다.