lvunreal-mcp

lvunreal-mcp

Unreal Engine 5 에디터를 Claude에서 직접 제어할 수 있는 MCP(Model Context Protocol) 서버입니다. UE5의 Remote Control API를 통해 184개 도구로 에디터 전체를 제어합니다.

주요 기능 (25개 카테고리, 184개 도구)

카테고리	도구 수	설명
Object	4	UObject 프로퍼티/함수 접근
Actor	7	액터 스폰, 삭제, 트랜스폼
Editor	3	콘솔 명령, 뷰포트, 엔진 정보
Level	4	레벨 로드/저장/목록
Asset	2	에셋 검색, 메타데이터
Blueprint	10	생성, 컴파일, 변수, 함수, 컴포넌트
Material	12	파라미터, 텍스처, 인스턴스, 일괄 적용
Material Graph	8	노드 생성/연결/삭제, 리컴파일
Component	6	컴포넌트 추가/제거/프로퍼티
Selection	5	액터 선택/해제/포커스
Viewport	5	카메라, 스크린샷, 뷰모드
Niagara	7	VFX 시스템 스폰/변수/활성화
Sequencer	6	시퀀스 재생/정지/탐색
Animation	6	애니메이션 재생, AnimBP 설정
PIE	5	Play/Stop/Simulate In Editor
Physics	6	물리 시뮬레이션, 콜리전, 임펄스
Audio	5	사운드 스폰/재생/볼륨
Landscape	4	지형 정보/머티리얼/레이어
World	8	월드 설정, 중력, 액터 계층구조
Python	2	Python 명령/스크립트 실행
Outliner	10	이름 변경, 일괄 수정, 정렬, 분배, 교체
Asset Management	12	에셋 이동/복제/삭제/정리
DMX	11	DMX 라이브러리, 픽스처, 값 전송, 시퀀스 녹화
Cinematic	26	시네카메라, 시퀀스, 포스트프로세스, MRQ 렌더
Bridge	10	범용 브릿지: 아직 없는 기능도 자유롭게 사용

Step 1: 필수 프로그램 설치 1-1. Node.js 설치 https://nodejs.org 접속 LTS 버전 (18 이상) 다운로드 & 설치 설치 확인: node --version

v18.x.x 이상이면 OK

1-2. Claude Code 설치 npm install -g @anthropic-ai/claude-code

설치 후 첫 실행:

claude

→ Anthropic 계정 로그인 진행 (브라우저 열림)

Step 2: Unreal Engine 플러그인 활성화 UE5 에디터를 열고 다음 플러그인들을 켜주세요:

Edit → Plugins 메뉴 열기 검색해서 다음 4개 활성화: 플러그인 필수 여부 용도 ✅ Remote Control API 필수 MCP 통신의 핵심 ✅ Python Editor Script Plugin 필수 고급 기능 (DMX, 시네마틱 등) 🟡 DMX DMX 쓸 때 DMX 조명 제어 🟡 Movie Render Queue 영상 렌더 시 시네마틱 렌더링 에디터 재시작 (플러그인 활성화 후 필요) 확인 방법 에디터 재시작 후, 브라우저에서 다음 주소 접속:

http://127.0.0.1:30010/remote/info

JSON 응답이 오면 성공! ✅

Step 3: 프로젝트에 .mcp.json 설정 우리 프로젝트 (jercy_lt_project)에는 이미 .mcp.json이 커밋되어 있어요. Git pull 하면 자동으로 적용됩니다.

만약 없다면, 프로젝트 루트에 .mcp.json 파일 생성:

{ "mcpServers": { "lvunreal-mcp": { "command": "npx", "args": ["-y", "lvunreal-mcp"] } } }

이게 끝이에요! npm에서 자동으로 다운로드됩니다.

Step 4: 사용 시작 4-1. UE5 에디터 실행 (반드시 먼저!) 프로젝트를 UE5 에디터에서 열어두세요.

4-2. Claude Code 실행 프로젝트 폴더에서 Claude Code를 실행:

cd C:\PF_Workspace\jercy_lt_project claude

4-3. 자연어로 명령! Claude에게 바로 말하면 됩니다:

"현재 레벨에 있는 액터 목록 보여줘"

"PointLight를 (500, 0, 200) 위치에 스폰해줘"

"Floor로 시작하는 액터들 이름을 Floor_001, Floor_002... 로 바꿔줘"

"시네카메라 만들고 50mm 렌즈로 설정해줘"

💡 자주 쓰는 명령 예시 하고 싶은 것 Claude에게 이렇게 말하세요 액터 목록 보기 "현재 레벨 액터 목록 보여줘" 액터 스폰 "StaticMeshActor를 원점에 스폰해줘" 이름 정리 "Light로 시작하는 액터들 이름 정리해줘" 머티리얼 적용 "이 액터에 M_Concrete 머티리얼 적용해줘" 스크린샷 "뷰포트 스크린샷 찍어줘" PIE 실행 "플레이 시작해줘" 시네마틱 "10초짜리 시네마틱 시퀀스 만들어줘" 영상 렌더 "1920x1080 PNG로 렌더링해줘" ⚠️ 트러블슈팅 문제 해결 "Cannot connect to Unreal Engine" UE5 에디터가 실행 중인지 확인. Remote Control API 플러그인 켰는지 확인 "npx not found" Node.js 설치 후 터미널 재시작 MCP 서버 인식 안 됨 .mcp.json이 프로젝트 루트에 있는지 확인. claude 재시작 Python 관련 에러 Python Editor Script Plugin 활성화 후 에디터 재시작 포트 30010 안 열림 방화벽 확인, 또는 다른 프로그램이 포트 점유 중인지 확인 정리하면 팀원이 할 일은 딱 4가지:

Node.js 설치 + claude 설치 UE5 플러그인 2개 활성화 (Remote Control API + Python) Git pull (.mcp.json 자동 적용) UE5 열어두고 claude 실행 → 바로 사용!

환경변수

변수	기본값	설명
UE_HOST	127.0.0.1	UE5 에디터 호스트
UE_HTTP_PORT	30010	Remote Control API 포트
UE_TIMEOUT	5000	요청 타임아웃 (ms)

전체 도구 목록

Object Tools (4)

도구	설명
ue_get_property	UObject 프로퍼티 읽기
ue_set_property	UObject 프로퍼티 쓰기
ue_call_function	UObject 함수 호출
ue_describe_object	UObject 메타데이터 (프로퍼티, 함수 목록)

Actor Tools (7)

도구	설명
ue_spawn_actor	클래스명으로 액터 스폰
ue_destroy_actor	액터 삭제
ue_list_actors	레벨의 액터 목록 (클래스 필터)
ue_get_actor_properties	액터 프로퍼티 읽기
ue_set_actor_properties	액터 프로퍼티 쓰기
ue_get_actor_transform	위치/회전/스케일 읽기
ue_set_actor_transform	위치/회전/스케일 쓰기

Editor Tools (3)

도구	설명
ue_run_console_command	콘솔 명령 실행
ue_get_viewport_info	뷰포트 카메라 정보
ue_get_engine_info	엔진/Remote Control API 상태

Level Tools (4)

도구	설명
ue_get_current_level	현재 레벨 정보
ue_load_level	레벨 로드
ue_save_level	현재 레벨 저장
ue_list_levels	프로젝트 내 레벨 목록

Asset Tools (2)

도구	설명
ue_search_assets	에셋 검색
ue_get_asset_metadata	에셋 메타데이터 조회

Blueprint Tools (10)

도구	설명
ue_list_blueprints	블루프린트 에셋 검색
ue_call_blueprint_function	블루프린트 함수 호출
ue_compile_blueprint	블루프린트 컴파일
ue_get_blueprint_variables	블루프린트 변수 목록
ue_set_blueprint_variable_default	블루프린트 변수 기본값 설정
ue_get_blueprint_functions	블루프린트 함수 목록
ue_get_blueprint_components	블루프린트 컴포넌트 목록
ue_add_blueprint_component	블루프린트에 컴포넌트 추가
ue_describe_blueprint	블루프린트 전체 설명 (클래스 계층, 인터페이스)
ue_create_blueprint	새 블루프린트 생성

Material Tools (12)

도구	설명
ue_list_materials	머티리얼 목록
ue_get_material_params	머티리얼 파라미터 조회
ue_set_material_scalar_param	스칼라 파라미터 설정
ue_set_material_vector_param	벡터/색상 파라미터 설정
ue_set_material_texture_param	텍스처 파라미터 설정
ue_create_material_instance	MaterialInstance 생성
ue_assign_material	액터에 머티리얼 적용
ue_get_material_info	머티리얼 상세 정보 (블렌드 모드, 셰이딩 모델 등)
ue_describe_material	머티리얼 전체 구조 설명
ue_set_material_static_switch	스태틱 스위치 파라미터 설정
ue_get_material_expressions	머티리얼 노드 목록
ue_apply_material_to_actors	여러 액터에 머티리얼 일괄 적용

Material Graph Tools (8)

도구	설명
ue_create_material	새 머티리얼 에셋 생성
ue_create_material_expression	머티리얼 노드 추가 (Constant, TextureSample, Multiply 등)
ue_delete_material_expression	머티리얼 노드 삭제
ue_connect_material_property	노드를 머티리얼 속성에 연결 (BaseColor, Roughness 등)
ue_connect_material_expressions	두 노드를 핀으로 연결
ue_recompile_material	머티리얼 리컴파일
ue_set_material_expression_value	노드 프로퍼티 설정 (값, 텍스처, 파라미터 이름 등)
ue_create_material_instance_asset	MaterialEditingLibrary로 머티리얼 인스턴스 생성

Component Tools (6)

도구	설명
ue_list_components	액터의 컴포넌트 목록
ue_add_component	컴포넌트 추가
ue_remove_component	컴포넌트 제거
ue_get_component_property	컴포넌트 프로퍼티 읽기
ue_set_component_property	컴포넌트 프로퍼티 쓰기
ue_set_static_mesh	StaticMesh 변경

Selection Tools (5)

도구	설명
ue_get_selected_actors	현재 선택된 액터 조회
ue_select_actor	액터 선택/해제
ue_select_all_actors	전체 선택 (클래스 필터)
ue_deselect_all	선택 해제
ue_focus_selected	선택된 액터에 카메라 포커스

Viewport Tools (5)

도구	설명
ue_take_screenshot	뷰포트 스크린샷
ue_set_editor_camera	에디터 카메라 위치/방향 설정
ue_get_editor_camera	에디터 카메라 정보
ue_set_viewport_mode	뷰모드 변경 (Lit, Wireframe, Unlit 등)
ue_set_viewport_realtime	실시간 렌더링 on/off

Niagara Tools (7)

도구	설명
ue_list_niagara_systems	나이아가라 시스템 에셋 검색
ue_spawn_niagara_system	나이아가라 시스템 스폰
ue_get_niagara_component	나이아가라 컴포넌트 정보
ue_set_niagara_variable	나이아가라 사용자 변수 설정 (Float, Vec3, Color 등)
ue_activate_niagara	나이아가라 활성화/비활성화
ue_reset_niagara	나이아가라 시스템 리셋
ue_get_niagara_variables	나이아가라 변수 목록

Sequencer Tools (6)

도구	설명
ue_list_sequences	LevelSequence 에셋 목록
ue_get_sequence_info	시퀀스 상세 정보
ue_play_sequence	시퀀스 재생
ue_stop_sequence	시퀀스 정지
ue_set_sequence_playback_position	시퀀스 탐색 (시간 이동)
ue_get_sequence_bindings	시퀀스 액터 바인딩 조회

Animation Tools (6)

도구	설명
ue_list_animations	애니메이션 에셋 목록 (Sequence, Montage, Blueprint)
ue_get_animation_info	애니메이션 에셋 상세 정보
ue_play_animation	SkeletalMesh에 애니메이션 재생
ue_set_anim_blueprint	AnimBlueprint 설정
ue_get_anim_variables	AnimInstance 변수 조회
ue_set_anim_variable	AnimInstance 변수 설정

PIE Tools (5)

도구	설명
ue_play_in_editor	PIE 시작
ue_stop_pie	PIE 중지
ue_is_pie_active	PIE 실행 상태 확인
ue_eject_from_pie	PIE에서 프리카메라로 이젝트
ue_simulate_in_editor	SIE (Simulate In Editor) 시작

Physics Tools (6)

도구	설명
ue_set_simulate_physics	물리 시뮬레이션 on/off
ue_set_collision_enabled	콜리전 타입 설정
ue_set_collision_profile	콜리전 프리셋 설정
ue_add_impulse	물리 임펄스 적용
ue_set_mass	질량 설정 (kg)
ue_set_physics_material	물리 머티리얼 설정

Audio Tools (5)

도구	설명
ue_spawn_sound	사운드 액터 스폰
ue_play_sound_at_actor	액터 위치에서 사운드 재생
ue_set_sound_volume	볼륨 설정
ue_list_sounds	사운드 에셋 목록
ue_stop_sound	사운드 정지

Landscape Tools (4)

도구	설명
ue_list_landscapes	랜드스케이프 액터 목록
ue_get_landscape_info	랜드스케이프 상세 정보
ue_set_landscape_material	랜드스케이프 머티리얼 설정
ue_get_landscape_layer_info	페인트 레이어 정보

World Tools (8)

도구	설명
ue_get_world_info	월드 설정 (게임모드, 중력 등)
ue_set_world_gravity	중력 설정
ue_set_game_mode	게임모드 클래스 설정
ue_get_all_classes	스폰 가능한 클래스 목록
ue_attach_actor	액터 부모-자식 관계 설정
ue_detach_actor	액터 분리
ue_set_actor_folder	아웃라이너 폴더 설정
ue_get_actors_in_folder	폴더별 액터 조회

Outliner Tools (10)

도구	설명
ue_rename_actor	액터 이름 변경
ue_batch_rename_actors	일괄 이름 변경 (Light_001, Light_002...)
ue_find_actors_by_name	이름 패턴으로 액터 검색
ue_duplicate_actors	액터 복제 (오프셋 적용)
ue_batch_set_property	여러 액터 프로퍼티 일괄 설정
ue_batch_set_transform	여러 액터 일괄 이동/회전/스케일
ue_align_actors	액터 정렬 (축별 min/max/center/first)
ue_distribute_actors	액터 균등 분배
ue_replace_actors	액터 교체 (트랜스폼 유지)
ue_set_actor_tags	액터 태그 설정

Asset Management Tools (12)

도구	설명
ue_rename_asset	에셋 이름 변경
ue_duplicate_asset	에셋 복제
ue_delete_asset	에셋 삭제
ue_move_asset	에셋 폴더 이동
ue_batch_rename_assets	에셋 일괄 이름 변경 (Find/Replace)
ue_create_folder	콘텐츠 브라우저 폴더 생성
ue_list_folder_contents	폴더 내용 조회
ue_fix_redirectors	리다이렉터 정리
ue_save_asset	에셋 저장
ue_save_all_dirty	수정된 에셋 전체 저장
ue_find_unused_assets	미사용 에셋 찾기
ue_get_asset_references	에셋 참조 관계 조회

Python Tools (2)

도구	설명
ue_execute_python	UE5 에디터에서 Python 명령 실행 (만능 escape hatch)
ue_execute_python_script	Python 스크립트 파일 실행

DMX Tools (11)

도구	설명
ue_dmx_list_libraries	DMX 라이브러리 에셋 목록
ue_dmx_create_library	새 DMX 라이브러리 생성
ue_dmx_list_fixture_types	픽스처 타입 목록
ue_dmx_list_fixture_patches	픽스처 패치 목록 (유니버스, 채널 정보)
ue_dmx_send_values	DMX 채널 값 전송 (Art-Net/sACN)
ue_dmx_send_fixture_values	픽스처 어트리뷰트 값 전송 (Dimmer, Pan, Tilt 등)
ue_dmx_get_fixture_values	픽스처 현재 값 읽기
ue_dmx_record_to_sequence	DMX 데이터를 LevelSequence에 녹화 설정
ue_dmx_add_fixture_to_sequence	DMX 픽스처 액터를 시퀀스에 추가
ue_dmx_get_protocol_settings	DMX 프로토콜 설정 조회
ue_dmx_spawn_fixture_actor	DMX 픽스처 액터 스폰

Cinematic Tools (26) — 영상 생성 파이프라인 0~100

도구	파이프라인	설명
ue_cine_spawn_camera	0~20 카메라	CineCameraActor 스폰 (렌즈, 필름백 설정)
ue_cine_set_camera_properties	0~20 카메라	카메라 DOF, 포커스, 필름백 세부 설정
ue_cine_spawn_camera_rig_rail	0~20 카메라	돌리 레일 리그 스폰
ue_cine_spawn_camera_rig_crane	0~20 카메라	크레인/짐 리그 스폰
ue_cine_create_level_sequence	20~40 시퀀스	LevelSequence 생성 (FPS, 길이 설정)
ue_cine_add_actor_to_sequence	20~40 시퀀스	액터를 시퀀스 트랙에 추가
ue_cine_add_camera_cut_track	20~40 시퀀스	카메라 컷 트랙 (멀티캠 전환)
ue_cine_add_transform_keyframe	40~60 애니메이션	트랜스폼 키프레임 추가
ue_cine_add_focal_length_keyframe	40~60 애니메이션	줌 키프레임 (초점거리 변경)
ue_cine_spawn_post_process_volume	60~75 룩	PostProcessVolume 스폰 (블룸, 비네팅 등)
ue_cine_set_post_process	60~75 룩	포스트프로세스 상세 설정 (13가지 파라미터)
ue_cine_apply_lut	60~75 룩	LUT 적용 (컬러 그레이딩)
ue_cine_spawn_cinematic_light	60~75 룩	시네마틱 조명 스폰 (Rect/Spot/Point/Directional)
ue_cine_create_render_job	75~100 렌더	MRQ 렌더 잡 생성 (해상도, 포맷 설정)
ue_cine_configure_render_quality	75~100 렌더	렌더 품질 설정 (AA, 샘플링, 콘솔 변수)
ue_cine_render_queue	75~100 렌더	MRQ 실행 (렌더링 시작)
ue_cine_clear_render_queue	75~100 렌더	MRQ 큐 초기화
ue_cine_get_render_queue_status	75~100 렌더	MRQ 상태 조회
ue_cine_start_take_recorder	유틸리티	Take Recorder 녹화 시작 (라이브 퍼포먼스 캡처)
ue_cine_stop_take_recorder	유틸리티	Take Recorder 녹화 중지
ue_cine_set_playrate	유틸리티	시퀀스 재생 속도 설정
ue_cine_set_level_visibility	유틸리티	서브레벨 가시성 토글
ue_cine_pilot_camera	유틸리티	카메라 파일럿 (뷰포트에서 카메라 조종)
ue_cine_eject_pilot	유틸리티	카메라 파일럿 해제
ue_cine_screenshot_from_camera	유틸리티	특정 카메라 시점 스크린샷
ue_cine_full_pipeline	원샷	전체 파이프라인 자동 실행 (카메라→시퀀스→PP→MRQ)

Bridge Tools (10) — 아직 없는 기능도 사용 가능한 범용 브릿지 🌉

도구	역할	설명
ue_explore_object	탐색	아무 UObject의 프로퍼티/함수 목록 조회
ue_find_classes	탐색	키워드로 UE5 클래스 검색 (Actor/Component 표시)
ue_find_subsystems	탐색	사용 가능한 Editor/Engine 서브시스템 목록
ue_explore_class_methods	탐색	클래스의 모든 메서드/프로퍼티 조회
ue_raw_call	호출	아무 UObject의 아무 함수 호출 (만능 함수 호출)
ue_raw_get_property	읽기	아무 UObject의 아무 프로퍼티 읽기
ue_raw_set_property	쓰기	아무 UObject의 아무 프로퍼티 쓰기
ue_python_bridge	Python	설명 + 코드로 아무 Python 실행 (에러 핸들링 포함)
ue_raw_batch	배치	여러 API 호출을 한 번에 묶어서 실행
ue_help	가이드	어떤 도구를 써야 하는지 안내

사용 흐름:

1. 뭘 할 수 있는지 모르겠다 → ue_find_classes "Camera" / ue_find_subsystems
2. 오브젝트는 아는데 함수를 모르겠다 → ue_explore_object / ue_explore_class_methods
3. 전용 도구가 있다 → 전용 도구 사용 (빠르고 안전)
4. 전용 도구가 없다 → ue_raw_call / ue_python_bridge
5. 대량 작업 → ue_raw_batch

사용 예시

Claude Code에서 자연어로 요청하면 됩니다:

레벨 디자인

"PointLight 10개를 원형으로 배치해줘"
"Floor로 시작하는 모든 액터를 찾아서 Z축으로 정렬해줘"
"선택된 액터들을 X축으로 균등 분배해줘"
"모든 StaticMeshActor를 Props/Geometry 폴더로 정리해줘"

머티리얼 & 셰이더

"M_Rock 머티리얼을 만들고 TextureSample 노드를 추가해서 BaseColor에 연결해줘"
"Floor 액터들에 M_Concrete 머티리얼을 일괄 적용해줘"
"M_Base에서 MaterialInstance를 만들고 Roughness를 0.8로 설정해줘"

나이아가라 VFX

"NS_Fire 나이아가라 시스템을 (500, 0, 100) 위치에 스폰해줘"
"나이아가라 Scale 변수를 1.5로 설정하고 활성화해줘"

블루프린트

"BP_Enemy 블루프린트를 만들고 SkeletalMeshComponent를 추가해줘"
"BP_Player의 MaxHealth 기본값을 200으로 변경해줘"
"블루프린트 컴파일해줘"

배치 작업 (노가다 자동화)

"Light로 시작하는 액터들을 Light_001, Light_002... 로 이름 변경해줘"
"선택된 액터 5개를 100 간격으로 복제해줘"
"Materials 폴더에서 Old를 New로 일괄 이름 변경해줘"
"미사용 에셋을 찾아줘"

DMX 조명 제어

"DMX 라이브러리 목록 보여줘"
"MyDMXLibrary의 MovingHead 픽스처에 Dimmer=255, Pan=128 보내줘"
"DMX 픽스처 액터를 레벨에 스폰해줘"
"DMX 데이터를 시퀀스에 녹화해줘"

시네마틱 영상 제작 (0→100 파이프라인)

"시네카메라를 50mm 렌즈, f/1.4로 만들어줘"
"돌리 레일 리그 500cm 길이로 스폰해줘"
"10초짜리 30fps LevelSequence 만들어줘"
"카메라 3대로 멀티캠 컷을 설정해줘"
"PostProcessVolume 추가하고 블룸 0.5, 비네팅 0.3으로 설정해줘"
"LUT 적용해줘"
"1920x1080 PNG로 MRQ 렌더 잡 만들고 렌더링 시작해줘"

원샷 전체 파이프라인 (카메라 배치 → 시퀀스 → 포스트프로세스 → MRQ 렌더까지 한 번에):

"MyCinematic이라는 이름으로 카메라 3대, 10초짜리 시네마틱 영상 파이프라인 전체를 세팅해줘"

플레이 & 디버그

"PIE 시작해줘"
"현재 PIE 실행 중이야?"
"스크린샷 찍어줘"
"콘솔에서 stat fps 실행해줘"

아키텍처

Claude Code ←stdio→ MCP Server (TypeScript) ←HTTP→ UE5 Remote Control API (:30010)

• MCP Server: Claude Code와 stdio로 통신, UE5에 HTTP 요청
• Remote Control API: UE5 내장 플러그인, 모든 UObject에 접근 가능
• Python Escape Hatch: Remote Control API로 직접 접근 어려운 기능은 ue_execute_python으로 해결

트러블슈팅

문제	해결
연결 실패	UE5 에디터 실행 중인지, Remote Control API 플러그인 활성화 확인
Object not found	ue_list_actors로 정확한 경로 확인 후 재시도
블루프린트 오류	ue_compile_blueprint 전에 구조 확인
Python 실행 실패	Python Editor Script Plugin 활성화 필요

라이선스

MIT