Unreal Engine 5.8 MCP 플러그인으로 Claude Code에 언리얼 맡기기: 실험 기능 켜기부터 큐브 세 개 놓기까지
Unreal Engine 5.8에 실험 기능으로 들어온 Unreal MCP 플러그인을 켜고, Claude Code를 연결해 레벨을 요약받고 큐브 세 개를 놓게 하는 과정을 따라 합니다. 실험 기능이라 조심할 점과 되돌리는 법도 함께 정리합니다.
한국어English
기준: Unreal Engine 5.8(캡처, 한국어 화면), Unreal MCP 플러그인 1.0(실험 기능), Claude Code 2.1.316, Epic 공식 문서 "Unreal MCP in Unreal Editor". 2026년 11월에 확인했습니다. 그림은 모두 그래픽카드 메모리 8 GB 노트북에서 찍은 실제 화면입니다. 빨간 번호와 테두리는 설명을 위해 덧그렸습니다.
Unreal Engine 5.8에는 AI가 편집기에 직접 접속하는 공식 플러그인이 들어 있습니다. 출시 노트의 제목은 "MCP Server (Experimental)"이고, 플러그인 화면 이름은 Unreal MCP입니다. 출시 노트는 이 플러그인이 "에이전트형 AI 시스템이 언리얼 에디터에 연결하게 해 준다"고 설명합니다.
MCP(Model Context Protocol)는 AI에게 도구를 꽂는 공통 규격입니다. 콘센트 모양을 하나로 맞춰 두면 어느 전기제품이든 꽂을 수 있는 것처럼, MCP를 지원하는 AI 앱이면 같은 방식으로 언리얼에 연결됩니다. 자세한 뜻은 MCP란 무엇인가에 있습니다. 이 사이트의 Blender MCP 글(Claude Code에 Blender 공식 MCP 붙이기)을 읽었다면 같은 생각을 언리얼에 옮긴 것이라고 보면 됩니다.
이 플러그인은 실험 기능입니다. 공식 문서는 출시 제품에 넣을 때 주의하라고 적었고, 서버에 인증(비밀번호 같은 확인 절차)이 없어 이 컴퓨터 밖으로 열면 안전하지 않다고 안내합니다. 그래서 이 글은 연습용 사본 프로젝트에서만 따라 하는 것을 전제로 합니다.
이 글을 마치면 아래를 할 수 있습니다.
- Unreal MCP와 All Toolsets 플러그인을 켭니다.
- MCP 서버를 자동으로 켜고, 주소와 포트를 확인합니다.
- Claude Code가 읽을 설정 파일(
.mcp.json)을 만듭니다. - Claude Code에게 레벨 요약을 받고, 큐브를 놓게 합니다.
- AI가 바꾼 것을 되돌리고, 실험 기능을 안전하게 씁니다.
1. 전체 구조
| 부품 | 하는 일 | 식당 비유 |
|---|---|---|
| Claude Code | 사람의 말을 이해하고 어떤 도구를 쓸지 정함 | 주문을 받는 직원 |
| Unreal MCP 서버(편집기 안) | AI의 도구 요청을 편집기 동작으로 바꿈 | 주방 창구 |
| 툴셋(All Toolsets) | 액터 놓기, 카메라 옮기기 같은 실제 기능 묶음 | 주방의 조리 도구 |
| 언리얼 에디터 | 실제로 레벨을 바꿈 | 주방 |
공식 문서에 따르면 Unreal MCP 자체는 서버 역할만 하고, 실제 도구는 툴셋 플러그인이 제공합니다. 그래서 두 플러그인을 함께 켜야 합니다. 서버는 이 컴퓨터 안에서만 http://127.0.0.1:8000/mcp로 열립니다. 127.0.0.1은 "이 컴퓨터 자신"을 가리키는 주소입니다.
2. 준비: 연습용 프로젝트
시작 상태: Epic Games 런처에서 Unreal Engine 5.8을 설치한 상태에서 시작합니다.
따라 하기:
- 런처에서 Unreal Engine 5.8을 실행하고, 새 프로젝트를 하나 만듭니다. 이름은
UEDemo처럼 연습용임을 알 수 있게 짓습니다. - 이미 작업 중인 프로젝트로 시험하고 싶다면, 먼저 프로젝트 폴더를 통째로 복사해 사본에서 합니다.
이 글의 그림은 넓은 지형이 깔린 기본 오픈 월드 레벨에서 찍었습니다. 고른 템플릿과 레벨에 따라 여러분 화면의 액터 수는 그림과 다를 수 있습니다.
그래픽카드 메모리가 8 GB인 노트북이라면 다른 무거운 프로그램(Blender, 게임 등)을 닫고 시작하세요. 제 PC에서는 기본 레벨을 연 편집기 하나가 메모리를 약 4.2 GB 썼습니다.
3. 플러그인 두 개 켜기
시작 상태: 앞 절에서 만든 연습용 프로젝트를 편집기로 연 상태에서 시작합니다.
따라 하기:
- 위쪽 메뉴 편집(Edit) ‣ 플러그인(Plugins)을 고릅니다(그림 1의 ②).
- 플러그인 창의 검색 칸에
Unreal MCP를 넣습니다. Unreal MCP 줄의 체크 칸을 켭니다(그림 2의 ①). 이름 옆에 실험단계 기능(Experimental) 표시가 붙어 있습니다(그림 2의 ②). - 검색 칸을 지우고
All Toolsets를 넣어, All Toolsets 줄도 켭니다(그림 3). - 편집기를 다시 시작하라는 안내가 나오면 다시 시작합니다.
그림 1. 편집 메뉴. ① 에디터 개인설정 ② 플러그인. 그림은 AI가 큐브를 놓은 뒤라 맨 위에 실행 취소 항목이 보입니다 (Unreal Editor 화면 캡처)
그림 2. Unreal MCP 플러그인. ① 켜기 체크 ② 이름과 실험단계 기능 표시 (Unreal Editor 화면 캡처)
그림 3. All Toolsets 플러그인. ① 켜기 체크 ② 이름. All Toolsets를 켜면 딸린 툴셋 플러그인이 함께 켜집니다 (Unreal Editor 화면 캡처)
All Toolsets는 여러 툴셋 플러그인을 한 번에 켜 주는 묶음입니다. 공식 문서는 필요한 툴셋만 골라 따로 켜도 된다고 안내합니다. 처음에는 전부 켜 두고 써 보는 편이 이해하기 쉽습니다.
4. MCP 서버 켜기
시작 상태: 앞 절에서 두 플러그인을 켜고 편집기를 다시 시작한 상태에서 이어 갑니다.
따라 하기:
- 편집 ‣ 에디터 개인설정(Editor Preferences)을 엽니다(그림 1의 ①).
- 왼쪽 목록의 일반(General) 아래 모델 컨텍스트 프로토콜(Model Context Protocol)을 고릅니다(그림 4의 ①).
- 서버 URI 경로가
/mcp, 서버 포트 번호가8000인지 봅니다(그림 4의 ②). - 서버 자동 시작(Auto Start Server)을 켭니다(그림 4의 ③). 다음부터는 편집기를 열 때마다 서버가 함께 켜집니다.
- 지금 바로 켜려면 편집기 아래 콘솔 칸(기본 단축키
`)에ModelContextProtocol.StartServer를 넣고Enter를 누릅니다.
그림 4. MCP 서버 설정. ① 모델 컨텍스트 프로토콜 ② 주소 /mcp와 포트 8000 ③ 서버 자동 시작. 그림은 자동 시작을 켜기 전 화면입니다 (Unreal Editor 화면 캡처)
서버가 켜지면 출력 로그(Output Log)에 아래 줄이 찍힙니다.
LogModelContextProtocol: Starting MCP server on port 8000 (override with -ModelContextProtocolPort=N).
다른 프로그램이 8000번 포트를 이미 쓰고 있다면 그림 4의 포트 번호를 바꿉니다. 아래 툴 검색 활성화는 켠 채로 둡니다. 이것이 켜져 있으면 서버가 도구 수백 개를 한꺼번에 내보이지 않고, list_toolsets, describe_toolset, call_tool 세 도구로 필요한 것만 찾아 씁니다. 두꺼운 공구함을 통째로 쏟아 놓지 않고 목록부터 보는 방식이라, AI가 읽어야 할 글이 줄어듭니다.
5. Claude Code 설정 파일 만들기
시작 상태: 앞 절에서 서버를 켠 편집기에서 이어 갑니다.
따라 하기:
- 콘솔 칸에 아래를 넣고
Enter를 누릅니다. 공식 문서에 따르면 프로젝트 폴더(.uproject가 있는 곳)에.mcp.json파일이 만들어집니다.
ModelContextProtocol.GenerateClientConfig ClaudeCode
- 프로젝트 폴더의
.mcp.json을 메모장으로 열어 아래와 같은 내용인지 봅니다.
{ "mcpServers": { "unreal-mcp": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } } }
명령 뒤의 ClaudeCode 자리에 Cursor, VSCode, Gemini, Codex를 넣으면 다른 AI 앱용 설정 파일이 만들어지고, All을 넣으면 전부 만들어집니다. 파일을 손으로 만들어도 내용이 같으면 똑같이 동작합니다. 이 서버는 HTTP(SSE 포함) 방식만 지원하고, 명령줄 연결(stdio)과 WebSocket은 지원하지 않습니다. SSE는 서버가 연결을 열어 둔 채 소식을 이어서 보내는 HTTP 방식입니다.
Claude Code를 아직 설치하지 않았다면 Claude Code 입문을 먼저 보세요. 연결 명령 한 줄로 등록하는 방법도 있습니다. 이때는 프로젝트 폴더에서 claude mcp add --transport http unreal-mcp http://127.0.0.1:8000/mcp를 실행합니다.
6. 첫 명령: 레벨 요약 받기
시작 상태: 편집기가 켜져 있고, .mcp.json이 있는 프로젝트 폴더에서 이어 갑니다.
따라 하기:
- 편집기가 먼저 켜져 있는지 확인합니다. 공식 문서는 연결이 안 되면 편집기를 켠 뒤에 AI 앱을 실행하라고 안내합니다.
- 터미널을 열고 프로젝트 폴더로 옮겨
claude를 실행합니다. 이 폴더의 MCP 서버를 쓸지 물으면 허용합니다. - 아래처럼 물어봅니다. 처음에는 바꾸지 말라고 함께 적어, 읽기만 하게 합니다.
언리얼 에디터에 연결된 unreal-mcp 도구로, 지금 열린 레벨에 어떤 액터가 몇 개 있는지 종류별로 짧게 요약해 줘. 바꾸지는 마.
제 PC에서 이 질문에 Claude Code가 돌려준 답의 앞부분은 이랬습니다.
열린 레벨은 저장하지 않은 새 레벨(/Temp/Untitled_1)이고, 지금 메모리에 로드된 액터는 총 145개입니다.
레벨은 바꾸지 않았고, 조회만 했습니다.
- LandscapeStreamingProxy (랜드스케이프 조각, 8×8): 64
- HLOD0_Instancing (자동으로 만들어진 HLOD 액터): 64
- 조명·환경: DirectionalLight, SkyLight, SkyAtmosphere, ExponentialHeightFog, VolumetricCloud 각 1개
- 엔진이 자동으로 두는 액터(WorldSettings, Brush 등): 9
요약: 기본 오픈월드 템플릿 그대로입니다.
편집기 아웃라이너에는 138개로 보였는데(그림 5), AI는 145개라고 답했습니다. AI는 아웃라이너에 잘 드러나지 않는 엔진 기본 액터(WorldSettings 등)까지 센 것으로 보입니다. AI의 숫자와 화면의 숫자가 다르면, 무엇을 셌는지 다시 물어 확인하세요.
그림 5. AI에게 일을 시키기 전 레벨 (Unreal Editor 화면 캡처)
7. 두 번째 명령: 큐브 세 개 놓기
시작 상태: 앞 절에서 레벨 요약을 받은 Claude Code 화면에서 이어 갑니다.
따라 하기:
- 아래처럼 시킵니다. 무엇을, 어디에, 몇 개, 어떤 이름으로 놓을지와 저장하지 말 것을 함께 적습니다.
unreal-mcp 도구로 지금 레벨의 카메라가 보는 화면 가운데 땅 위에 엔진 기본 큐브(/Engine/BasicShapes/Cube) 3개를 1 m 간격으로 한 줄로 놓고, 이름을 AI_Cube_1~3으로 붙인 뒤 세 큐브가 화면에 잘 보이도록 뷰포트 카메라를 맞춰 줘. 레벨 저장은 하지 마. 끝나면 한 일을 3줄로 알려 줘.
- 편집기 화면을 봅니다. 큐브 세 개가 놓이고 카메라가 옮겨졌는지, 아웃라이너에 AI_Cube_1~3이 생겼는지 확인합니다(그림 6).
그림 6. AI가 바꾼 뒤. ① 놓인 큐브 세 개 ② 아웃라이너의 AI_Cube_1~3 (Unreal Editor 화면 캡처)
제 PC에서 받은 답은 "원래 카메라 화면 한가운데에서 땅과 만나는 지점에 큐브 3개를 놓았고, 큐브 사이를 1 m씩 띄웠다(중심 간격 2 m), 큐브끼리 붙이려던 거라면 말해 달라"는 내용이었습니다. "1 m 간격"을 큐브 사이의 빈틈으로 읽은 것입니다. 기본 큐브는 한 변이 1 m라서 중심끼리는 2 m 떨어졌습니다. 이처럼 말이 두 가지로 읽힐 수 있으면 "중심 사이 1 m"처럼 분명하게 적는 편이 좋습니다.
8. 되돌리기와 안전 점검
AI가 놓은 큐브도 사람이 한 일처럼 실행 취소 기록에 남습니다. 그림 1의 편집 메뉴 맨 위에 "오브젝트 배치 실행 취소"가 보이는 것이 그 기록입니다. 마음에 들지 않으면 Ctrl+Z로 되돌립니다.
| 점검 | 까닭 |
|---|---|
| 연습용 사본 프로젝트에서 하기 | 실험 기능이라 예상과 다른 동작을 할 수 있음 |
| 명령에 "저장하지 마"를 넣고, 결과를 본 뒤 직접 저장하기 | 바뀐 레벨을 사람이 확인한 뒤 남기기 위해 |
| 서버 포트를 이 컴퓨터 밖으로 열지 않기 | 서버에 인증이 없음(공식 문서) |
| 처음 명령은 읽기만 시키기 | AI가 무엇을 보는지 먼저 확인 |
| 쓰지 않을 때는 서버 끄기 | 콘솔 ModelContextProtocol.StopServer |
AI에게 3D 프로그램을 맡길 때의 일반적인 안전 습관은 AI에게 Blender를 맡기기 전 안전 점검에 더 자세히 있습니다. 언리얼에도 그대로 통합니다.
막혔을 때
| 증상 | 까닭 | 해결 |
|---|---|---|
| Claude Code가 unreal-mcp 도구를 못 찾는다 | 편집기보다 Claude Code를 먼저 켬, 또는 다른 폴더에서 실행 | 편집기를 켠 뒤 .mcp.json이 있는 폴더에서 claude 다시 실행 |
| 출력 로그에 Starting MCP server 줄이 없다 | 자동 시작이 꺼져 있음 | 4절대로 서버 자동 시작을 켜거나 콘솔에서 StartServer |
| 도구는 보이는데 할 수 있는 일이 거의 없다 | All Toolsets(또는 필요한 툴셋)를 켜지 않음 | 3절대로 All Toolsets 켜고 편집기 다시 시작 |
| 서버가 켜지지 않고 포트 오류가 난다 | 다른 프로그램이 8000번 포트를 씀 | 그림 4의 포트 번호를 바꾸고 .mcp.json의 주소도 같게 고치기 |
| 편집기가 매우 느려진다 | 무거운 기본 레벨과 다른 프로그램이 메모리를 나눠 씀 | 다른 프로그램을 닫고 가벼운 빈 레벨에서 시험 |
| AI가 레벨을 저장해 버렸다 | 명령에 저장 금지를 적지 않음 | 사본 프로젝트로 돌아가 다시 시작, 다음 명령부터 "저장하지 마" 적기 |
한 줄 정리
Unreal MCP + All Toolsets 켜기, 서버 자동 시작(127.0.0.1:8000/mcp), 콘솔 GenerateClientConfig ClaudeCode, 편집기 먼저 켜고 프로젝트 폴더에서 claude, 사본에서만·저장은 사람이.
참고 자료
- Epic Games, Unreal MCP in Unreal Editor: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-mcp-in-unreal-editor
- Unreal Engine 5.8 출시 노트(MCP Server, Experimental): https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes
- Claude Code 문서, MCP 연결: https://code.claude.com/docs/en/mcp
- 콘솔 명령:
ModelContextProtocol.StartServer,ModelContextProtocol.StopServer,ModelContextProtocol.GenerateClientConfig ClaudeCode - 단축키: 실행 취소
Ctrl+Z, 콘솔 칸` - 그림: 모두 실제 Unreal Engine 5.8 화면(연습용 프로젝트). AI 답 글은 Claude Code가 실제로 돌려준 것의 일부
