Unreal MCP

🌟 개요

Unreal Engine 5.5 + Python + Cursor AI를 연결하여 코드 작성 및 편집에 AI 보조를 도입하는 방법을 소개.

카테고리	가능한 작업
액터 관리	• 액터 생성 및 삭제 (큐브, 구체, 조명, 카메라 등) • 액터의 변환 설정 (위치, 회전, 크기) • 액터 속성 조회 및 이름으로 검색 • 현재 레벨에 존재하는 모든 액터 나열
블루프린트 개발	• 커스텀 컴포넌트를 포함한 새로운 블루프린트 클래스 생성 • 컴포넌트 추가 및 설정 (메시, 카메라, 조명 등) • 컴포넌트 속성 및 물리 설정 구성 • 블루프린트 컴파일 및 인스턴스 생성 • 플레이어 입력 매핑 생성
블루프린트 노드 그래프	• 이벤트 노드 추가 (BeginPlay, Tick 등) • 함수 호출 노드 생성 및 연결 • 커스텀 타입과 기본값을 가진 변수 추가 • 컴포넌트 및 Self 참조 생성 • 그래프 내 노드 검색 및 관리
에디터 제어	• 특정 액터 또는 위치로 뷰포트 포커스 • 뷰포트 카메라의 방향 및 거리 제어

 

출처

GitHub - chongdashu/unreal-mcp: Enable AI assistant clients like Cursor, Windsurf and Claude Desktop to control Unreal Engine th

---

🔧 준비사항

• Python 3.12 이상
• Unreal Engine 5.5 이상
• Cursor IDE 설치 (다른 MCP 클라이언트도 가능. (예: Claude Desktop, Cursor, Windsurf))
• Git Bash

---

📦 1. Unreal MCP 클론하기

 

git clone https://github.com/mcptools/unreal-mcp.git
cd unreal-mcp/Python

 

🐍 2. Python 가상환경 만들기 (uv 사용)

uv는 Python 의존성 관리 도구입니다.

curl -LsSf https://astral.sh/uv/install.sh | sh

uv venv
source .venv\Scripts\activate		# Windows
					# 또는
.venv/bin/activate			# macOS / Linux

만약 아래와 같이 나온다면

$ uv venv
bash: uv: command not found

1. unreal-mcp/Python 경로가 맞는지 확인

2. Window 검색 -> 시스템 환경 변수 편집 -> 환경변수 ->
Path 편집 -> 새로 만들기 -> C:\Users\(개인 설정에 따라 다름)\.local\bin

3. 처음 부터 다시 설치 진행

📥 3. 의존성 설치

uv pip install -e .

설치가 완료되면 unreal-mcp 관련 패키지들이 설치됩니다.

---

🛠️ 4. Unreal Engine 프로젝트 설정

MCP Starter Project 사용 (선택 사항)

UnrealMCP 저장소 내 MCPGameProject는 기본 구성된 UE 5.5 프로젝트입니다.

수동으로 프로젝트 설정하기

1. .uproject 우클릭 → Generate Visual Studio project files
2. Visual Studio 열기
3. Development Editor 선택 후 빌드

빌드가 완료되면 Unreal Editor를 열고 플러그인이 정상적으로 로딩됩니다.

---

🧠 5. MCP 서버 설정 (Cursor 연결용)

1. Cursor 우측 상단 설정 클릭

 

2. MCP 클릭

 

3. + Add new global MCP server 클릭하고  아래 내용 추가

{
  "mcpServers": {
    "unrealMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "자신이 clone한 unreal-mcp/Python까지의 경로"
        "run",
        "unreal_mcp_server.py"
      ]
    }
  }
}

---

🚀 6. MCP 서버 실행하기

Unreal Editor를 먼저 실행한 상태에서 아래 명령 실행:

uv --directory ./Python run unreal_mcp_server.py

 

실행되면 아무 메시지 없이 멈춘 것처럼 보이는 게 정상입니다. (서버가 대기 상태로 들어감)

 

만약 아래와 같이 나온다면

error: 지정된 파일을 찾을 수 없습니다.

 

Python 폴더 안에 unreal_mcp_server.py 가 있는지 확인.