Natfii/UnrealClaude

Unreal Engine 5.7을 위한 Claude Code CLI 통합 - 에디터 내에서 직접 내장된 UE 5.7 문서 컨텍스트를 활용하여 AI 코딩 지원을 받으세요.

지원 플랫폼: Windows (Win64), Linux, macOS (Apple Silicon). Claude Opus 4.7 및 해당 Claude Code 릴리스를 지원합니다.

UnrealClaude는 Claude Code CLI를 Unreal Engine 5.7 에디터에 직접 통합합니다. API를 직접 사용하는 대신, 이 플러그인은 claude 명령줄 도구(command-line tool)를 호출하여 기존의 Claude Code 인증 및 기능을 활용합니다.

주요 기능:

네이티브 에디터 통합 (Native Editor Integration)- 실시간 스트리밍 응답, 도구 호출 그룹화(tool call grouping), 코드 블록 렌더링을 지원하며 에디터에 도킹된 채팅 패널을 제공합니다.
MCP 서버 (MCP Server)- 액터 조작, Blueprint 편집, 레벨 관리, 머티리얼(materials), 입력(input) 등을 위한 20개 이상의 Model Context Protocol (MCP) 도구를 제공합니다.
동적 UE 5.7 컨텍스트 시스템 (Dynamic UE 5.7 Context System)- MCP 브릿지에는 요청 시 정확한 UE 5.7 API 문서를 제공하는 동적 컨텍스트 로더(dynamic context loader)가 포함되어 있습니다.
Blueprint 편집 (Blueprint Editing)- Blueprint, Animation Blueprint, 상태 머신(state machines)을 생성 및 수정할 수 있습니다 (아직 버그가 일부 있으므로 완전히 의존하지 마세요).
레벨 관리 (Level Management)- 레벨 및 맵 템플릿을 프로그래밍 방식으로 열기, 생성 및 관리할 수 있습니다.
에셋 관리 (Asset Management)- 에셋 검색, 종속성(dependencies) 및 참조자(referencers) 쿼리.
비동기 작업 큐 (Async Task Queue)- 실행 시간이 긴 작업도 타임아웃되지 않습니다.
스크립트 실행 (Script Execution)- Claude는 사용자의 허가 하에 스크립트를 작성, 컴파일(Live Coding을 통해), 실행할 수 있습니다.
세션 지속성 (Session Persistence)- 에디터 세션 전반에 걸쳐 대화 기록이 저장됩니다.
프로젝트 인식 (Project-Aware)- 프로젝트 컨텍스트(모듈, 플러그인, 에셋)를 자동으로 수집하며 에디터 뷰포트(viewports)를 볼 수 있습니다.
Claude Code 인증 사용 (Uses Claude Code Auth)- 별도의 API 키 관리가 필요하지 않습니다.

npm install -g @anthropic-ai/claude-code

claude auth login

이렇게 하면 Anthropic 계정(Claude Pro/Max 구독)으로 인증하거나 API 액세스를 설정하기 위한 브라우저 창이 열립니다.

claude --version
claude -p "Hello, can you see me?"

(플러그인 브라우저에서 Editor 카테고리를 확인하세요. 검색 결과에 나타나지 않을 경우 아래로 스크롤해야 할 수도 있습니다)

이 플러그인은 사용자의 플랫폼 및 엔진 버전에 맞춰 소스 코드로부터 빌드(Build)해야 합니다. 사전 빌드된 바이너리(Prebuilt binaries)는 포함되어 있지 않습니다.

이 저장소를 클론(Clone)하세요 (MCP 브리지(MCP bridge) 서브모듈이 포함되어 있습니다):

git clone --recurse-submodules https://github.com/Natfii/UnrealClaude.git

만약 --recurse-submodules 옵션 없이 이미 클론했다면, 다음을 실행하세요:

cd UnrealClaude git submodule update --init

플러그인을 빌드하세요:

Windows: Engine\Build\BatchFiles\RunUAT.bat BuildPlugin -Plugin="PATH\TO\UnrealClaude\UnrealClaude\UnrealClaude.uplugin" -Package="OUTPUT\PATH" -TargetPlatforms=Win64

Linux: Engine/Build/BatchFiles/RunUAT.sh BuildPlugin -Plugin="/path/to/UnrealClaude/UnrealClaude/UnrealClaude.uplugin" -Package="/output/path" -TargetPlatforms=Linux

macOS: Engine/Build/BatchFiles/RunUAT.sh BuildPlugin -Plugin="/path/to/UnrealClaude/UnrealClaude/UnrealClaude.uplugin" -Package="/output/path" -TargetPlatforms=Mac

빌드된 플러그인을 사용자의 프로젝트(Project) 또는 엔진(Engine) 플러그인 폴더로 복사하세요.

옵션 A: 프로젝트 플러그인 (권장)

빌드 결과물을 프로젝트의 Plugins 디렉토리로 복사하세요:

YourProject/
├── Content/
├── Source/
...

옵션 B: 엔진 플러그인 (모든 프로젝트)

엔진의 플러그인 폴더로 복사하세요:

Windows:

C:\Program Files\Epic Games\UE_5.7\Engine\Plugins\Marketplace\UnrealClaude\

Linux:

/path/to/UnrealEngine/Engine/Plugins/Marketplace/UnrealClaude/

블루프린트(Blueprint) 도구 및 에디터 통합을 위해 다음 과정이 필요합니다:

cd <PluginPath>/UnrealClaude/Resources/mcp-bridge
npm install

에디터를 실행하면 플러그인이 자동으로 로드됩니다.

자세한 내용은 INSTALL_MAC.md를 참조하세요.

Node.js 및 Claude Code CLI 설치: brew install node npm install -g @anthropic-ai/claude-code claude

플러그인을 프로젝트의 Plugins/ 폴더에 설치하세요

directoryMCP 브리지 의존성 설치:cd YourProject/Plugins/UnrealClaude/Resources/mcp-bridge npm install

에디터를 실행하고 Tools > Claude Assistant를 여세요

자세한 내용은 INSTALL_LINUX.md를 참조하세요.

라이브러리 설치:sudo dnf install -y nss nspr mesa-libgbm libXcomposite libXdamage libXrandr alsa-lib pciutils-libs libXcursor atk at-spi2-atk pango cairo gdk-pixbuf2 gtk3

클립보드 지원 설치:sudo dnf install -y wl-clipboard # Wayland sudo dnf install -y xclip # X11 폴백 (fallback)

Wayland 설정:export SDL_VIDEODRIVER=wayland export UE_Linux_EnableWaylandNative=1

빌드 및 실행:./UnrealEditor -vulkan

메뉴 → Tools → Claude Assistant

C++에서 커스텀 Actor Component를 어떻게 만드나요?
GAS를 사용하여 체력 시스템을 구현하는 가장 좋은 방법은 무엇인가요?
World Partition에 대해 설명하고 오픈 월드를 위한 스트리밍 설정 방법을 알려주세요.
...

단축키	동작
Enter	메시지 전송
Shift+Enter	입력창에서 줄 바꿈
Escape	현재 요청 취소

대화 내용은 프로젝트의 Saved/UnrealClaude/ directory에 자동으로 저장되며, 에디터를 다시 열 때 복구됩니다. 플러그인은 세션 간의 대화 문맥 (context)을 유지합니다.

UnrealClaude는 프로젝트에 대한 정보를 자동으로 수집합니다:

• 소스 모듈 (Source modules) 및 해당 의존성 (dependencies)
• 활성화된 플러그인 (Enabled plugins)
• 프로젝트 설정 (Project settings)
• 최근 에셋 (Recent assets)
• 커스텀 CLAUDE.md 지침 (Custom CLAUDE.md instructions)

이 플러그인은 Claude 및 외부 도구에 에디터 기능을 노출하는 20개 이상의 도구가 포함된 Model Context Protocol (MCP) 서버를 포함하고 있습니다. MCP 서버는 기본적으로 3000번 포트에서 실행되며 에디터가 로드될 때 자동으로 시작됩니다.

도구 카테고리 (Tool Categories):

Actor Tools (액터 도구)

• 액터 생성 (Spawn), 이동, 삭제, 조사 및 속성 설정

Level Management (레벨 관리)

• 레벨 열기, 템플릿으로부터 새 레벨 생성, 사용 가능한 템플릿 목록 표시

Blueprint Tools (블루프린트 도구)

• 블루프린트 (Blueprint) 생성 및 수정 (변수, 함수, 노드, 핀)

Animation Blueprint Tools (애니메이션 블루프린트 도구)

• 전체 스테이트 머신 (State Machine) 편집 (상태, 트랜지션, 조건, 일괄 작업)

Asset Tools (에셋 도구)

• 에셋 검색, 페이지네이션 (Pagination)을 통한 의존성 및 참조자 쿼리

Character Tools (캐릭터 도구)

• 캐릭터 설정, 이동 설정 및 데이터 쿼리

Material Tools (머티리얼 도구)

• 머티리얼 (Material) 및 머티리얼 인스턴스 (Material Instance) 작업

Enhanced Input Tools (향상된 입력 도구)

• 입력 액션 (Input Action) 및 매핑 컨텍스트 (Mapping Context) 관리

Utility Tools (유틸리티 도구)

• 콘솔 명령 (Console commands), 출력 로그, 뷰포트 캡처, 스크립트 실행

Async Task Queue (비동기 작업 큐)

• 장시간 실행되는 작업을 위한 백그라운드 실행

매개변수, 예시 및 API 상세 정보가 포함된 전체 MCP 도구 문서를 확인하려면 UnrealClaude의 MCP Bridge 리포지토리를 참조하세요.

MCP 브릿지에는 요청 시 정확한 UE 5.7 API 문서를 제공하는 동적 컨텍스트 로더 (Dynamic context loader)가 포함되어 있습니다. unreal_get_ue_context를 사용하여 카테고리별(animation, blueprint, slate, actor, assets, replication)로 쿼리하거나 키워드로 검색할 수 있습니다. 컨텍스트 상태는 unreal_status 출력 결과에 표시됩니다.

Project Settings (프로젝트 세팅) → Plugins (플러그인) → Unreal Claude에서:

Auto-approve script execution (스크립트 실행 자동 승인) (기본값: OFF) — 이 설정이 ON일 때, MCP 브릿지 또는 에디터 내 채팅을 통해 트리거되는 모든 Python / C++ / Console / Editor Utility 스크립트는 권한 확인 대화 상자를 표시하지 않고 즉시 실행됩니다. 각 자동 승인된 스크립트는 감사 추적 (Audit trail)이 보존되도록 유형과 설명이 포함된 LogUnrealClaude 로그 항목을 작성합니다. 스크립트당 확인 절차가 주요한 마찰 요인이 되는 신뢰할 수 있는 MCP 기반 / 에이전트 기반 워크플로우를 위해 설계되었습니다. 연결된 클라이언트를 신뢰할 수 있는 머신 및 프로젝트에서만 활성화하십시오.

이 설정은 [/Script/UnrealClaude.UnrealClaudeSettings] 아래의 Config/DefaultEditor.ini에 저장됩니다.

프로젝트 루트에 CLAUDE.md 파일을 생성하여 내장된 UE5.7 컨텍스트 (Context)를 확장할 수 있습니다:

# My Project Context
## Architecture
- This is a multiplayer survival game
...

기본적으로 플러그인은 Read, Write, Edit, Grep, Glob, Bash 도구들을 사용하여 Claude를 실행합니다. 이는 ClaudeSubsystem.cpp에서 수정할 수 있습니다:

Config.AllowedTools = { TEXT("Read"), TEXT("Grep"), TEXT("Glob") }; // Read-only

• 사용자가 에디터 위젯 (Editor widget)에 프롬프트 (Prompt)를 입력합니다.

• 플러그인이 UE5.7 지식과 프로젝트 정보를 바탕으로 컨텍스트 (Context)를 구축합니다.

• 다음을 실행합니다:
  claude -p --skip-permissions --append-system-prompt "..." "your prompt"

• Claude Code가 사용자의 프로젝트를 작업 디렉토리 (Working directory)로 하여 실행됩니다.

• 응답이 캡처되어 채팅 패널 (Chat panel)에 표시됩니다.

• 대화 내용은 향후 세션을 위해 유지됩니다.

cd "C:\YourProject"
claude -p --skip-permissions \
--allowedTools "Read,Write,Edit,Grep,Glob,Bash" \
...

• Claude가 설치되었는지 확인합니다:
  claude --version

• PATH에 포함되어 있는지 확인합니다:
  where claude

• 설치 후 Unreal Editor를 재시작합니다.

터미널에서 claude auth login을 실행하여 인증합니다.

Claude Code는 프로젝트 디렉토리에서 실행되며 컨텍스트를 위해 파일을 읽을 수 있습니다. 대규모 프로젝트의 경우 초기 응답이 느려질 수 있습니다.

또한 너무 많은 글로벌 Claude Code 플러그인(예: Superpowers, ralp-loop, context7)이 활성화되어 있을 수도 있습니다. 해당 플러그인들의 컨텍스트가 주입되면서 최대 3분 이상의 지연이 발생할 수 있습니다.

Unreal Engine 5.7을 사용 중인지 확인하십시오. 지원되는 플랫폼은 Windows (Win64), Linux, macOS입니다.

3000번 포트를 사용할 수 있는지 확인하십시오. MCP 서버는 LogUnrealClaude에 로그를 남깁니다.

Claude가 MCP 도구들이 지침(Instructions)에는 있지만 기능 목록(Function list)에는 없다고 말하는 경우:

• MCP 브리지 의존성 설치: 가장 흔한 원인은 npm 패키지 누락입니다:
  cd YourProject/Plugins/UnrealClaude/Resources/mcp-bridge npm install

• HTTP 서버가 실행 중인지 확인: 에디터가 열려 있는 상태에서 다음을 테스트합니다:
  curl http://localhost:3000/mcp/status

프로젝트 정보가 포함된 JSON 응답이 보여야 합니다.

• 출력 로그 확인 (Check the Output Log): LogUnrealClaude를 찾으세요.

messages: MCP Server started on http://localhost:3000 메시지가 나타나야 합니다.

• 서버가 실행 중이면 Registered X MCP tools가 표시됩니다.

• 도구(Tools)가 로드되었습니다.

에디터 재시작 (Restart the editor): npm 의존성(dependencies)을 설치한 후, Unreal Editor를 재시작하세요.

새로운 와치독(watchdog)이 중단된 요청(60초)에 대해 경고를 보낼 것입니다. 모든 파일이 디스크에 있는지 확인하세요 (OneDrive, DropBox 등은 비활성화(DISABLE) 하세요).

MCP 브릿지(bridge)는 자체 Vitest 테스트 스위트가 포함된 독립형 저장소(standalone repository)로도 제공됩니다. 만약 브릿지 수준의 문제(도구 목록 표시, 파라미터 변환, 컨텍스트 주입 등)를 겪고 있다면, 브릿지 테스트를 독립적으로 실행할 수 있습니다:

cd path/to/ue5-mcp-bridge
npm install
npm test

이는 실행 중인 Unreal Editor를 요구하지 않고 브릿지를 테스트합니다.

필요에 따라 자유롭게 포크(fork)하세요! 개선 가능한 영역:

• Linux 지원 (@bearyjd님 감사합니다)
• Mac 지원 (@lateralsummer님 감사합니다)
• 추가적인 MCP 도구 (현재 도구들은 리팩토링(refactoring)이 필요하며, 현재로서는 새로운 도구가 없습니다)

MIT License - LICENSE 파일을 참조하세요.

• Unreal Engine 5.7용으로 빌드됨
• Anthropic의 Claude Code와 통합됨