UEFN MCP Server

Model Context Protocol을 통해 UEFN (Unreal Editor for Fortnite)을 Claude Code로 제어합니다.

Claude Code  <--stdio-->  MCP Server (mcp_server.py)  <--HTTP 127.0.0.1:8765-->  Listener (uefn_listener.py, inside UEFN)
                                   |--TCP 127.0.0.1:1962-->  UEFN VerseWorkflowServer   (verse_compile / verse_status / verse_push)
                                   |--stdio------------->  verse-lsp.exe                (verse_symbols / verse_hover / ...)
...

• 110가지 도구: 액터, 에셋, 레벨, 뷰포트, 머티리얼, Niagara, 애니메이션, 스태틱 메시, 데이터 테이블, 에셋 유효성 검사, 디바이스 @editable 와이어링, Play-In-Editor 제어, StaticMeshActor 산개(scatter), Verse 소스 내부 조사(introspection), Verse 컴파일/푸시, Verse 코드 탐색, UEFN 세션 상태 / 실행, 그리고 임의 Python 실행
• C++ 컴파일 없음 — 순수 Python으로, UEFN 버전 전반에 걸쳐 작동합니다.
• 메인 스레드 안전(Main-thread safe) — 모든 unreal.* 호출은 에디터 틱 콜백을 통해 디스패치됩니다.
• 자동 시작(Autostart) — 프로젝트가 열릴 때 리스너가 스스로 시작합니다 ( Auto-start 참고).
• 충돌 복구(Crash recovery) — UEFN 세션 도구는 에디터 상태를 읽고 충돌 후 UEFN을 재실행합니다; UEFN session and crash recovery 참고.
• 입력 시뮬레이션 없음(No input simulation) — 서버는 마우스나 키보드 입력을 절대 전송하지 않습니다. 되돌리기(undo)가 어려운 도구들은 실험적 도구로 표시됩니다.

0.5.0 버전의 새로운 기능

• UEFN 세션 (uefn_session.py, 3개 도구): uefn_status (에디터 로그에서 읽기 전용 상태, 프로세스 및 포트), uefn_launch_project (UEFN 시작, 프로젝트 열기, 리스너 대기; 충돌 후 남은 크래시 리포터를 중지할 수 있음), uefn_set_load_on_startup. 이 도구들은 마우스나 키보드 입력을 보내지 않습니다: UEFN이 HUB에서 멈추면 사용자가 프로젝트를 엽니다.
• [실험적] 태그: 되돌리거나 열린 레벨 외부에서 작동하기 어려운 7개 도구는 호출할 때마다 사용자에게 확인을 요청합니다. Experimental tools 참조.
• setup.ps1: 새 머신을 위한 하나의 불변(idempotent) 설정 단계 (-DryRun).
• 안전 수정 사항 (리스너 프로토콜 0.3.3): 회전은 이름이 지정된 축 {"pitch", "yaw", "roll"}입니다 (문서화된 [pitch, yaw, roll] 목록은 이전에 [roll, pitch, yaw]로 적용되었습니다); staticmesh_* 도구는 UEFN 42.20을 충돌시키는 게터(getters) 호출을 중지했습니다. Conventions 참조.

전체 목록: CHANGELOG.md.

0.4.0에서 새로워진 점

커뮤니티 포크가 이 저장소에 병합되었습니다: 79개의 새로운 도구(재질, Niagara, 애니메이션, 정적 메시, 에셋 관리, 데이터 테이블, 유효성 검사, 스크린샷, 장치 @editable 필드, Play-In-Editor, scatter, Verse introspection), 에디터 리스너 없이 Verse를 컴파일하고 푸시하며 탐색하는 Verse 모듈, ensure_mcp_hook.ps1을 통한 리스너 자동 시작, 시스템 트레이 아이콘, 그리고 프로젝트 전환 후에도 유지되는 리스너. 전체 목록: CHANGELOG.md.

빠른 시작

0. 한 단계: setup.ps1

git clone https://github.com/kirchuvakov/uefn-mcp-server
powershell -NoProfile -ExecutionPolicy Bypass -File .n-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-server -DryRun    # 무엇을 할지 보여줌
powershell -NoProfile -ExecutionPolicy Bypass -File .n-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-servern-mcp-server -ScheduleHook -Project "<path>\<Island>.uefnproject"```

스크립트는 **멱등성(idempotent)**을 가지므로(클론 이동 후 또는 Fortnite 업데이트 후에 다시 실행해도 무방함): 실제 Python 3.10 이상 버전을 찾고, `requirements.txt`를 설치하며, `UEFN_MCP_PATH`를 설정하고, 리스너 자동 시작 훅(`-ScheduleHook`은 Fortnite 업데이트 후에도 재설치하는 시간별 작업을 추가함)을 설치하며, UEFN 설치 상태, "Load on Startup" 활성화 여부, 그리고 프로젝트에서 Python이 활성화되었는지 여부를 보고하고, 남은 항목들을 출력합니다. 옵션: `-WithTray`(트레이 아이콘 패키징을 `vendor/`에 수행), `-WithMss`, `-EnableLoadLastProject`(UEFN이 HUB 대신 마지막 프로젝트를 시작 시 재열기; 권장됨, 아래 참조), `-RegisterClaude`(사용자 범위 등록), `-Python <python.exe>`, `-SkipPip`, `-DryRun`.

> **권장 사항: Load on Startup = 가장 최근 프로젝트(Most Recent Project).** UEFN은 자주 충돌합니다. 에이전트가 스스로 복구할 수 있도록 하려면, **에디터 환경설정(Editor Preferences) > 로딩 및 저장(Loading & Saving) > 시작 시 로드(Load on Startup)**를 **가장 최근 프로젝트(Most Recent Project)**로 설정하세요 (HUB 화면도 동일한 선택기를 가집니다). 이렇게 하면 `uefn_launch_project`가 UEFN을 재실행하고, 프로젝트는 HUB 없이 열리며, 리스너가 [훅](#auto-start)을 통해 자동 시작됩니다. 이것이 없으면 UEFN은 매번 재실행 후 HUB에서 멈추고 프로젝트를 수동으로 클릭해야 합니다. UEFN을 종료한 상태에서도 `setup.ps1 -EnableLoadLastProject`를 실행하거나 에이전트가 `uefn_set_load_on_startup('LastProject')`를 호출하도록 할 수 있습니다. 자세한 내용은 [UEFN 세션 및 충돌 복구](#uefn-session-and-crash-recovery)을 참조하세요.

아래의 1~6단계는 스크립트가 자동화하는 내용이며, 사용자가 직접 수행해야 하는 두 가지 작업(각 프로젝트에서 Python 활성화하기(3단계)와 Claude Code에서 서버 승인하기(5단계))를 제외합니다. 대화형 방식을 선호하십니까? Claude Code에 *"Help me set up UEFN MCP server"*라고 요청하세요.

### 1. 클론 및 `UEFN_MCP_PATH` 지정

```powershell
git clone https://github.com/kirchuvakov/uefn-mcp-server
[Environment]::SetEnvironmentVariable('UEFN_MCP_PATH', (Resolve-Path .\uefn-mcp-server).Path, 'User')

어떤 폴더든 작동합니다. 아래의 설정 스니펫들은 UEFN_MCP_PATH를 통해 서버를 찾기 때문에, 프로젝트에 절대 경로가 작성되지 않습니다. 설정을 마친 후 터미널과 Claude Code를 재시작하세요.

2. MCP SDK 설치 (호스트 Python 사용, UEFN 내부 아님)

pip install -r requirements.txt

실제 Python 3.10+ 설치본을 사용하세요. Windows의 경우, 기본 python 명령이 Microsoft Store 별칭(%LOCALAPPDATA%\Microsoft\WindowsApps\python.exe)으로 해석될 수 있으며, Claude Code는 이를 시작할 수 없습니다: Windows 설정에서 python.exe 앱 실행 별칭을 끄거나, 아래 command에 실제 python.exe의 전체 경로를 입력하세요.

3. UEFN에서 Python 활성화하기

1. UEFN에서 프로젝트 열기
2. Project > Project Settings로 이동
3. Python을 검색하고 Python Editor Script Plugin 옆의 체크박스를 선택합니다.

UEFN은 이 설정을 프로젝트별, 사용자별(EnablePythonLocallyPerProject)로 유지하므로, 리스너를 자동 시작해야 하는 모든 프로젝트에 이 설정이 필요합니다.

4. UEFN 내부에서 리스너 시작하기

자동 시작(권장, 일회성 설정): Auto-start 참조. 언제든지 수동으로 시작하려면: Tools > Execute Python Script > 클론 폴더의 uefn_listener.py를 실행합니다.

**상태 창(status window)**이 나타나 다음 정보를 보여줍니다:

• 리스너 상태(Listener status) — 실행 중일 때 녹색, 중지했을 때 빨간색
• MCP 서버 상태(MCP Server status) — Claude Code가 연결되었을 때 녹색 (10초마다 하트비트)
• 포트(Port) — 리스너가 중지된 경우 편집 가능
• 메트릭(Metrics) — 가동 시간, 요청 횟수, 오류, 마지막 명령, 평균 응답 시간
• 제어판(Controls) — Stop / Start / Restart 버튼

이 창을 닫는다고 해서 리스너가 중지되는 것은 아닙니다. 단지 숨겨지는 것뿐입니다. 에디터 세션이 유지되는 동안에는 시스템 트레이 아이콘(system-tray icon) (선택 사항, Tray icon 참조)이 알림 영역에 남아 있습니다: 왼쪽 클릭(또는 Show window)으로 창을 다시 열 수 있으며, 메뉴에서도 Hide window, Restart listener, Start/Stop listener 및 Quit (stop & remove tray) 옵션이 있습니다.

5. Claude Code 구성하기

프로젝트 루트의 .mcp.json 파일에서 (Claude Code는 이 파일 내의 ${VAR}와 ${VAR:-default}를 확장합니다):

unreal-mcp는 Epic 자체의 MCP 서버로, UEFN이 Toolsets를 활성화하여 실행되는 동안 사용할 수 있습니다. 이 서버는 (에셋/액터 검색, 장치 속성 읽기, 세션) 기능을 보완합니다. 프로젝트 범위의 .mcp.json 서버는 Claude Code에서 한 번 승인되어야 합니다 (/mcp). 만약 '승인 대기(pending approval)' 상태로 남아 있다면, 대신 사용자 범위에서 이 서버를 등록하세요:

claude mcp add uefn -s user -- python "$env:UEFN_MCP_PATH\mcp_server.py"

6. Claude Code 재시작하기

Claude Code는 시작 시 MCP 서버를 불러옵니다. claude mcp list로 확인하고 (출력에서 uefn ... Connected가 예상됨) *"ping UEFN"*을 물어보세요.

사용해 보기

Claude Code에 다음 질문들을 해보세요:

• "레벨의 모든 액터 목록을 보여줘"
• "위치 100, 200, 300에 큐브를 생성해줘"
• "Verse 코드를 컴파일하고 오류를 보여줘"
• "뷰포트 카메라를 원점(origin)을 바라보도록 이동시켜줘"

트레이 아이콘 (Tray icon)

트레이 아이콘은 UEFN의 임베디드 Python (3.11)용으로 빌드된 pystray와 Pillow가 필요하므로, 호스트 Python 대신 ./vendor 폴더(gitignored)에 넣어야 합니다. UEFN 자체의 python.exe로 한 번 채워주세요 (pip과 함께 제공됨):

$uefnPython = Join-Path $env:ProgramFiles 'Epic Games\Fortnite\Engine\Binaries\ThirdParty\Python3\Win64\python.exe'  # Fortnite가 다른 곳에 있는 경우 조정하세요
& $uefnPython -m pip install --target "$env:UEFN_MCP_PATH\vendor" pystray Pillow

pystray 0.19.5 및 Pillow 12.2.0 (cp311 wheel)으로 테스트되었습니다. 만약 vendor/ 폴더가 없더라도 모든 것이 작동합니다. 단지 트레이 아이콘 없이 창이 숨겨질 뿐입니다.

자동 시작 (Auto-start)

UEFN은 프로젝트를 열자마자 Python을 시작하지만 (해당 프로젝트의 3단계 완료 시), 오직 엔진 플러그인 폴더의 고정된 화이트리스트에서만 init_unreal.py를 실행합니다. init_unreal.py 파일을 Content/Python, Documents/UnrealEngine/Python 또는 UE_PYTHONPATH에 복사하는 것은 아무것도 시작하지 않으며, UEFN 프로젝트 내부의 .py 파일은 [ContainsPythonData] 오류와 함께 세션 업로드를 실패하게 만듭니다.

ensure_mcp_hook.ps1은 Epic의 화이트리스트에 등록된 <Fortnite>\Engine\Plugins\Experimental\Toolsets\EditorToolset\Content\Python\init_unreal.py 파일에 작은 마크드 훅(marked hook)을 추가합니다. 이 훅은 해당 저장소(repo)의 init_unreal.py를 실행하며, 이는 해당 저장소를 sys.path에 추가하고 uefn_listener를 임포트합니다. 이후 출력 로그에는 [MCP] Listener started on http://127.0.0.1:8765와 [MCP] Auto-started on port 8765가 표시됩니다.

$hook = Join-Path $env:UEFN_MCP_PATH 'ensure_mcp_hook.ps1'
powershell -NoProfile -ExecutionPolicy Bypass -File $hook -DryRun   # 실행 시도만 보여줌
powershell -NoProfile -ExecutionPolicy Bypass -File $hook           # 훅을 추가함 (Program Files가 쓰기 보호된 경우 권한 상승된 셸 필요)

Fortnite 업데이트는 Epic 파일을 덮어쓰고 훅을 제거합니다 (증상: 프로젝트를 연 후 [MCP] Auto-started 메시지가 없음). 이 스크립트는 불변(idempotent)하므로, Windows가 매시간 다시 실행하도록 설정하는 것이 좋습니다:

schtasks /Create /F /SC HOURLY /TN "UEFN-MCP-hook" /TR "powershell.exe -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File `"$hook`""

이 훅은 다음 프로젝트를 열 때 효력이 발생하며, 이미 열려 있는 프로젝트에서 리스너를 원격으로 시작하는 방법은 없습니다 ( Tools > Execute Python Script 사용). 옵션: -FortniteDir (또는 UEFN_FORTNITE_DIR; 기본값은 Epic 런처 매니페스트의 값이며, 그렇지 않으면 %ProgramFiles%\Epic Games\Fortnite), -Target (또는 UEFN_MCP_HOOK_TARGET; 기본값: 이전 설치본이 생성한 경우 사용자별 shim인 Documents\UnrealEngine\Python\init_unreal.py, 그렇지 않으면 이 저장소의 init_unreal.py), -DryRun. 스크립트는 작성 전에 Epic 파일을 백업하고 ensure_mcp_hook.log에 기록합니다.

Tools

execute_python 도구는 가장 강력하며 — 에디터 내부에서 임의의 Python 코드를 실행하고 unreal 모듈에 완전하게 접근할 수 있습니다:

# DESC: 액터 레이블 목록화      <- 선택 사항: 상태 창의 작업 레이블로 표시됨
# 사전 채워진 변수: unreal, actor_sub, asset_sub, level_sub, tk, get_tk_root
# 값을 반환하려면 `result`에 할당합니다
... 

Tkinter 참고: execute_python을 통해 UI 창을 생성할 때는 get_tk_root() + tk.Toplevel(root)를 사용하세요. 절대 tk.Tk()를 호출하지 마세요 — 여러 인스턴스는 에디터를 충돌시킵니다.

타임아웃: 리스너 호출은 30초 후에 반환되지만, 코드는 에디터에서 계속 실행됩니다. 장기 작업을 더 작은 호출로 분할하고, 시간 초과된 호출을 재실행하는 대신 나중에 에디터 상태를 확인하세요.

실험적 도구 (Experimental tools)

일곱 개의 도구는 되돌리기 어렵거나 열린 레벨 외부와 상호작용하는 작업을 수행합니다: 임의 코드 실행, 에셋 삭제 또는 이름 변경, 라이브 세션에 푸시, 리스너 중지, UEFN 시작 또는 설정 편집. 이들은 [experimental] 태그를 가지고 있으며, 에이전트는 각 호출 전에 사용자에게 확인을 요청해야 합니다: