언리얼 엔진×Claude 연동 매뉴얼

• 2026년 6월 17일 Unreal Fest Chicago에서 공개된 UE 5.8에 실험적 Unreal MCP 플러그인이 들어왔다.
• 에디터 프로세스 안에 로컬 MCP 서버가 떠서(http://127.0.0.1:8000/mcp), Claude Code·Gemini·Codex·Cursor 같은 아무 MCP 에이전트나 에디터를 운전할 수 있다.
• AI가 직접 만지는 것: 액터 배치 · 라이팅 · 머티리얼 · 블루프린트 노드 그래프 · 레벨 레이아웃 · 자동화 테스트. 자연어 한 줄로.
• 설정 흐름: Edit > Plugins에서 켜기 → 서버 시작 → GenerateClientConfig로 .mcp.json 자동 생성 → 프로젝트 루트에서 에이전트 실행.
• Epic 입장(Marcus Wassmer): "창작자를 대체하는 게 아니라, 시간 잡아먹는 반복 작업을 없애는 것." UE6(2027년 말 예정)의 토대로 가는 첫 발.
• ⚠️ 실험 단계 — 인증 없음 · 로컬 전용 · 파괴적 작업 자동승인 금지. 에이전트 권한을 프로덕션 자격증명처럼 다뤄라.

정식 명칭은 Unreal MCP. 별도 서버 프로세스를 띄울 필요 없이, 에디터 안에서 MCP 서버가 직접 돈다. 외부 AI 에이전트는 로컬 HTTP로 거기에 붙기만 하면 된다. 의존성으로 Toolset Registry 플러그인이 함께 켜지고, 이게 에디터 기능을 'AI가 호출 가능한 도구'로 등록해 준다.

무엇을 시킬 수 있나

1플러그인 켜기

Edit > Plugins에서 "Unreal MCP"를 검색해 Enabled 체크. 의존성인 Toolset Registry가 자동으로 같이 켜진다. 프롬프트가 뜨면 에디터를 재시작.

2서버 띄우기

Edit > Editor Preferences > General > Model Context Protocol에서 Auto Start Server를 켜면, 에디터 시작 시 자동으로 http://127.0.0.1:8000/mcp에 바인딩된다. 수동으로 띄우려면 에디터 콘솔(~ 키)에서:

3클라이언트 설정 자동 생성

에디터 콘솔에서 아래를 실행하면, 프로젝트 루트에 연결 정보가 담긴 .mcp.json이 만들어진다. 지원 클라이언트: ClaudeCode · Cursor · VSCode · Gemini · Codex.

4에이전트 실행

.mcp.json이 생성된 프로젝트 루트에서 Claude Code를 실행하면, 에이전트가 알아서 MCP 서버를 발견하고 붙는다. (자세한 Claude 쪽 설정은 Part 02로.)

연결 정보 · 콘솔 명령어

에디터 콘솔에서 자주 쓰는 한 줄들 — 각 줄 우측 복사 버튼으로

공식 권장 경로는 에디터가 만들어 준 .mcp.json을 그대로 쓰는 것이다. 하지만 직접 등록하거나 다른 디렉토리에서 붙이고 싶다면 아래 방법들이 있다.

방법 A — 에디터가 생성한 .mcp.json (권장)

Part 01의 3단계에서 GenerateClientConfig ClaudeCode를 실행하면 프로젝트 루트에 이런 형태의 파일이 생긴다. Claude Code는 실행 디렉토리의 .mcp.json을 자동으로 읽는다.

{
  "mcpServers": {
    "unreal": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

방법 B — 터미널에서 직접 등록

HTTP 트랜스포트라서 Claude Code CLI 한 줄로도 붙일 수 있다. 에디터의 MCP 서버가 떠 있는 상태에서:

연결 확인

Claude Code 안에서 슬래시 명령으로 상태를 본다. unreal 서버가 초록 점과 함께 도구 개수가 0보다 크게 보이면 성공.

이렇게 시켜보면 된다

UE 5.8 공식 플러그인이 나오기 전부터, 커뮤니티가 MCP로 언리얼을 운전하는 도구들을 만들어 왔다. UE 5.5~5.7을 쓰거나, 공식 플러그인보다 더 많은 도구가 필요하면 여전히 유효한 선택지다. 이들은 대개 에디터 안의 별도 플러그인 + 외부 서버 프로세스(Python/Node) 구조로, 클라이언트는 그 외부 서버에 stdio로 붙는다 — 공식의 'HTTP 직결'과는 아키텍처가 다르다.

예: chongdashu/unreal-mcp 설정

플러그인 폴더(UnrealMCP)를 프로젝트 Plugins/에 복사 → Edit > Plugins에서 활성화 → VS 프로젝트 파일 재생성 후 빌드. 그다음 클라이언트 설정에 외부 Python 서버를 등록한다.

{
  "mcpServers": {
    "unrealMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/Python>",
        "run",
        "unreal_mcp_server.py"
      ]
    }
  }
}

설정 파일 위치

• Claude Desktop → ~/.config/claude-desktop/mcp.json
• Cursor → 프로젝트 루트의 .cursor/mcp.json
• Windsurf → ~/.config/windsurf/mcp.json

예: StraySpark — 외부 서버 프로세스 방식

에디터 플러그인을 <Project>/Plugins/UnrealMCP/에 넣고 Edit > Plugins > Project > Unreal MCP에서 "Enabled by Default"를 체크(이게 시작 시 도구 핸들러를 등록한다). 그리고 별도 서버 프로세스를 설치:

{
  "mcpServers": {
    "unreal": {
      "command": "unreal-mcp-server",
      "args": ["--port", "30801", "--profile", "production-safe"],
      "env": {
        "UNREAL_PROJECT_PATH": "/abs/path/YourProject.uproject",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

MCP는 에디터 제어권을 통째로 넘긴다. Epic도 "에이전트 권한을 프로덕션 자격증명처럼 다루라"고 못 박았다. 실험 단계인 만큼 다음은 선택이 아니라 기본기다.

• 항상 피처 브랜치에서. AI가 만지는 동안 메인/프로덕션 브랜치는 건드리지 않는다. 버전 관리(Git/Perforce)는 필수.
• 파괴적 도구는 자동승인 끄기. 이름에 delete · remove · overwrite · reset이 들어간 도구는 매번 사람이 확인한다.
• 가능하면 제한 프로파일. 서드파티 서버라면 read-only나 production-safe 프로파일로 시작하고, unrestricted는 신뢰가 쌓인 뒤에.
• 에디터는 보이게 둔다. 에이전트가 작업하는 동안 에디터 창을 띄워 두고 변경을 눈으로 따라간다.
• 한 에디터에 에이전트 하나. 같은 에디터 인스턴스에 두 에이전트를 동시에 붙이지 않는다 — 상태 충돌의 지름길.
• 로컬 전용임을 기억. 공식 서버는 루프백 바인딩에 인증이 없다. 포트를 외부에 노출하거나 원격에서 붙이려 하지 말 것.

2026년 6월 기준 웹 자료. 공식 문서를 1차 출처로, 나머지는 보도·셋업 가이드·커뮤니티 프로젝트.