unreal-mcp

Claude에서 실행 중인 Unreal Engine 에디터를 구동하는 MCP 서버입니다.

Epic의 자체 Python Remote Execution 프로토콜을 사용합니다. 239.0.0.1:6766의 UDP 멀티캐스트로 에디터 인스턴스를 검색한 다음, TCP 채널을 통해 에디터 내부에서 Python을 실행합니다.

Claude  ──stdio──▶  unreal-mcp  ──UDP discovery + TCP──▶  Unreal Editor (PythonScriptPlugin)

프로토콜의 클라이언트 부분은 벤더링되지 않습니다. 서버는 런타임에 엔진 설치본에서 Epic의 remote_execution.py를 찾기 때문에 엔진 버전이 달라도 계속 동작합니다.

요구 사항

• Unreal Engine 5.x (5.6을 기준으로 개발)

• Python 3.10+ 및 uv

Related MCP server: unreal-mcp

설정

1. Unreal에서 원격 실행 활성화 — 이 단계를 모두가 놓칩니다

Remote executing은 기본적으로 꺼져 있습니다. 이 설정을 하지 않으면 에디터가 검색되지 않고 모든 도구가 실패합니다.

1. Edit > Plugins → Python Editor Script Plugin 활성화 → 재시작합니다.

2. Edit > Project Settings > Plugins > Python → Enable Remote Execution 체크합니다.

3. 에디터를 재시작합니다.

2. 설치

cd unreal-mcp
uv sync

3. Claude에 등록

claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "unreal": {
      "command": "uv",
      "args": ["--directory", "E:\\Maya\\unreal-mcp", "run", "unreal-mcp"]
    }
  }
}

그런 다음 새 대화를 시작하세요. 세션 중간에 추가된 서버는 이미 실행 중인 채팅에서 인식되지 않습니다.

엔진이 비표준 경로에 있다면 UNREAL_ENGINE_ROOT를 설정하세요:

"env": { "UNREAL_ENGINE_ROOT": "D:\\Epic\\UE_5.6" }

도구

목록 조회 도구는 limit / offset으로 페이지를 나누며 has_more와 next_offset을 반환합니다.

결과가 반환되는 방식

도구 본문은 result 변수에 값을 할당하고 그 값을 sentinel 사이의 JSON으로 출력하는 하네스에 감싸져 에디터로 전송됩니다. 그 덕분에 원치 않는 print()나 Unreal 로그 줄이 페이로드를 오염시키지 않고, 에디터 내부의 예외는 stdout에 묻힌 traceback 대신 구조화된 오류로 전달됩니다.

보안 참고 사항

unreal_execute_python은 샌드박스 없이 unreal 모듈 전체에 접근하여 에디터의 인터프리터에서 코드를 실행합니다. 프로젝트 콘텐츠를 수정하거나 삭제할 수 있습니다. 에디터 자체의 Python 콘솔과 동일한 주의를 기울여야 합니다.

문제 해결

“No running Unreal Editor was found” — 대부분 위에서 언급한 Enable Remote Execution 설정 때문입니다. unreal_get_status로 확인하세요.

“Lost the connection ... while running a command” — 에디터가 종료되었거나 모달 대화 상자에 막혀 있습니다. 대화 상자를 닫고 다시 시도하면 세션이 자동으로 재검색합니다.

에디터 여러 개가 열려 있음 — 먼저 발견된 노드가 우선합니다. unreal_get_status가 모든 노드를 나열하므로 어느 것이 어느 것인지 알 수 있습니다.