이 페이지는 영어에서 기계 번역되었습니다. 영어 원문 읽기.

CLI 레퍼런스

unreal-mcp-cli 명령 전체 레퍼런스 - Unreal MCP 플러그인 설치, 로그인, AI 에이전트 구성, 에디터 실행, 도구와 Python 실행까지 다룹니다.

2026년 11월 4일 업데이트 Markdown으로 보기

unreal-mcp-cli는 Unreal MCP용 명령줄 도구입니다. 플러그인을 설치하고 업데이트하며, ai-game.dev에 로그인하고, AI 에이전트용 MCP 구성을 작성하며, 올바른 연결 설정으로 Unreal Editor를 실행하고, 스크립트와 CI에서 도구를 호출합니다. Windows, macOS, Linux에서 동작합니다. 이 페이지는 버전 0.26.2를 다룹니다.

CLI 설치

Node.js ^20.19.0 또는 >=22.12.0이 필요합니다.

npm install -g unreal-mcp-cli
unreal-mcp-cli --version

또는 설치 없이 단일 명령으로 실행할 수 있습니다:

npx unreal-mcp-cli@latest status

unreal-mcp-cli <command> --help를 실행하면 각 명령의 내장 도움말을 볼 수 있습니다. 전역 -v, --verbose 플래그는 추가 진단 정보를 출력합니다.

참고: 프로젝트를 [path]로 받는 명령은 이를 위치 인수로 받습니다. [path]가 없는 명령은 -p, --path <dir>로 받습니다. 둘 다 기본값은 현재 폴더입니다. --path 명령에 위치 경로를 전달하면 "too many arguments" 오류가 발생합니다.

명령 개요

명령용도
create-project <path>최소한의 Unreal Engine C++ 프로젝트 스캐폴딩
install-plugin [path]<project>/Plugins에 UnrealMCP 플러그인 설치
update [path]설치된 플러그인 업데이트
remove-plugin [path]플러그인 제거
install-extension <id> [path]Unreal MCP 확장 설치
loginai-game.dev 로그인 (디바이스 코드 흐름)
configureUNREAL_MCP_* 값을 <project>/.env에 기록
setup-mcp [agent]AI 에이전트용 MCP 구성 작성
setup-skills프로젝트용 Claude Code 스킬 작성
open [path]연결 설정과 함께 Unreal Editor 실행
close [path]프로젝트를 실행 중인 에디터 종료
exec [code]에디터에서 Python 실행
status패키지, 프로젝트, 플러그인 및 연결 상태 표시
wait-for-ready프로젝트의 MCP 서버가 응답할 때까지 대기
run-tool <tool>HTTP로 MCP 도구 호출
run-system-tool <tool>HTTP로 시스템 도구 호출
bootstrap-local [path]소스에서 브리지 빌드
install-engine [version]설치된 엔진 감지, Epic 런처 링크

프로젝트 설정 명령

create-project

최소한의 C++ 프로젝트를 스캐폴딩합니다. 옵션: --name <name> (프로젝트 및 모듈 이름, 영문자, 숫자, 밑줄만 허용되며 하이픈 불가), --engine <version> (EngineAssociation, 예: 5.7), --force (비어 있지 않은 폴더 허용).

unreal-mcp-cli create-project ./MyGame --engine 5.7

install-plugin

플러그인을 설치합니다. 로컬 소스가 없으면 GitHub 릴리스에서 CLI 버전과 일치하는 플러그인 소스를 다운로드하며, 먼저 서명을 검증합니다.

플래그의미
--version <v>다운로드할 플러그인 릴리스 (기본값: CLI 버전)
--plugin-source <dir>로컬 플러그인 폴더 사용 (오프라인, CI, 개발)
--junction복사 대신 링크 (Windows, 플러그인 개발용)
--with-server체크섬 검증된 gamedev-mcp-server도 함께 다운로드
--server-version <v>, --server-source <path-or-url>--with-server용 서버 버전 또는 로컬이나 사용자 지정 소스
--enroll <code>, --enroll-stdin브라우저 로그인 대신 에이전트 등록 코드 사용
--base-url <url>--enroll용 인증 기본 URL
-y, --yes머신을 다른 계정으로 전환하는 것 확인

update

설치된 플러그인을 다시 동기화합니다. 버전이 변경되면 Unreal이 깨끗하게 재빌드하도록 오래된 Intermediate/와 C++ Binaries/를 제거하고, 번들된 브리지는 유지합니다. 플래그: --version <v>, --plugin-source <dir>, --force (같은 버전 재설치), --no-clean (빌드 캐시 유지).

remove-plugin

프로젝트에서 Plugins/UnrealMCP를 제거합니다. 옵션 없음.

install-extension

확장을 설치하고, 이를 및 해당 엔진 플러그인을 .uproject에서 활성화합니다. 플래그: --version <x.y.z>, --source <dir>, --build (지금 컴파일), --engine-root <dir> (--build용 엔진), --force.

unreal-mcp-cli install-extension com.ivanmurzak.unreal-ai-pcg ./MyGame --build

bootstrap-local

소스 체크아웃용으로 소스에서 <project>/Intermediate/UnrealMCP/로 브리지를 빌드합니다. .NET 9 SDK가 필요합니다. 플래그: --repo-root <dir>, --plan (빌드 계획만 출력).

install-engine

설치된 엔진을 나열하거나 특정 버전이 있는지 확인합니다. 엔진을 다운로드하지는 않으며, 버전이 없으면 Epic Games Launcher 링크를 제공합니다. 플래그: --manifest <path> (명시적 LauncherInstalled.dat), --install, --yes.

로그인 및 AI 에이전트 명령

login

OAuth 디바이스 코드 흐름으로 로그인하고 자격 증명을 ~/.ai-game-dev/credentials.json에 저장합니다. 이 파일은 머신의 모든 AI Game Dev 도구가 공유합니다.

플래그의미
-p, --path <dir>자격 증명을 머신 저장소 대신 해당 프로젝트의 .env에 저장
--tools-onlyCI 러너용 도구 전용 자격 증명 생성 (앱에서는 사용 불가)
-y, --yes머신을 다른 계정으로 전환할지 확인
--base-url <url>인증 기본 URL (기본값 https://ai-game.dev)
--timeout <ms>전체 폴링 타임아웃

configure

UNREAL_MCP_* 값을 <project>/.env에 기록하고 .env를 gitignore에 추가합니다. 플래그: -p, --path, --mode <Cloud|Custom>, --host <url>, --cloud-url <url>, --token <token>, --auth <option>, --keep-connected, --tools <list>, --start-server, --transport <stdio|http>, --log-level <level>, --no-gitignore.

--agent <id>를 지정하면 대신 관리형 gamedev-mcp-server에 고정된 클라이언트 구성을 작성하도록 요청합니다. 관련 플래그는 --url, --server-version, --server-source입니다.

setup-mcp

에이전트 하나에 대한 MCP 구성 항목을 작성합니다. 에이전트 목록은 AI 클라이언트 연결을 참고하세요.

플래그의미
-p, --path <dir>프로젝트 폴더
--transport <t>http(기본값) 또는 stdio(로컬 서버 다운로드)
--url <url>명시적 서버 URL
--token <token>명시적 베어러 토큰, 프로젝트 키보다 우선
--oauthCloud: URL만 있는 구성, 에이전트가 직접 로그인
--regenerate-keyCloud: 새 프로젝트 키를 만들고 이전 키를 폐기
--no-pin프로젝트 고정 /mcp/p/<pin> 대신 일반 /mcp URL
--dry-run기록하지 않고 스니펫만 출력
--list지원되는 에이전트와 구성 경로 나열

setup-skills

.claude/skills/unreal-mcp/SKILL.md를 작성합니다. 플래그: -p, --path, --url, --token, --force(덮어쓰기).

에디터 명령

open

Unreal Editor를 실행하고 연결 설정을 UNREAL_MCP_* 환경 변수로 전달합니다. 엔진은 프로젝트의 EngineAssociation에서 가져오며, 소스에서 빌드한 엔진은 --engine-root가 필요합니다.

플래그의미
--connection-mode <mode>Custom 또는 Cloud; --host만 지정하면 Custom으로 간주
--host, --token, --auth, --tools, --transport해당하는 UNREAL_MCP_* 변수를 설정
--keep-connected, --start-server해당 변수를 true로 설정
--no-connectUNREAL_MCP_* 변수를 전달하지 않음
--headlessCLI가 소유한 창 없는 에디터를 시작하고 준비될 때까지 대기
--idle <seconds>, --url <url>CLI 소유 에디터의 유휴 종료 및 서버 URL
--engine-root <dir>소스 빌드용 엔진 폴더
--no-build실행 전 네이티브 모듈 빌드 생략
--no-auto-dismiss-startup-dialogsUnreal의 시작 프롬프트를 그대로 둠
--startup-dismiss-timeout-ms, --startup-dismiss-poll-interval-ms프롬프트 닫기 조정 (기본값 12000 및 1000)
--no-cache엔진 경로 다시 탐색

Linux에서는 시작 프롬프트 닫기가 X11에서만 동작합니다.

close

프로젝트를 실행 중인 에디터를 닫습니다. --owned-only를 사용하면 CLI가 시작한 에디터(exec 또는 open --headless 사용)만 닫으며, 저장 후 종료합니다. 직접 연 에디터는 건드리지 않습니다. --force는 제시간에 종료되지 않는 CLI 소유 에디터를 강제 종료하고, --token은 베어러 토큰을 재정의합니다.

exec

python-execute를 통해 에디터에서 Python을 실행합니다. 실행 중인 에디터를 재사용하거나, 화면 밖에서 렌더링하는(스크린샷이 계속 동작하도록) 헤드리스 에디터를 시작하고 도구 호출이 일정 시간 없으면 종료합니다.

unreal-mcp-cli exec "unreal.SystemLibrary.get_engine_version()" -p ./MyGame

플래그: -p, --path, -f, --file <file>(stdin은 -), --include <path>(.ai-game-dev/snippets의 헬퍼, 반복 가능), --window, --idle <seconds>(기본값 300, 0 = 사용 안 함), --ready-timeout <ms>, --timeout <ms>, --raw(JSON 응답 출력), --url, --token, --engine-root, --no-build. 결과는 stdout에, print() 및 로그 줄은 stderr에 출력됩니다.

도구 및 상태 명령

status 및 wait-for-ready

status는 CLI, 프로젝트, 플러그인, 연결 상태를 실시간 연결 확인(--no-probe로 생략)과 함께 보고합니다. wait-for-ready는 서버가 핑에 응답할 때까지 대기합니다(--timeout 기본값 120000ms, --interval 기본값 2000ms). 둘 다 -p, --path, --url, --token을 받습니다.

run-tool 및 run-system-tool

프로젝트의 로컬 MCP 서버를 통해 도구 하나를 호출합니다:

unreal-mcp-cli run-tool rql-query -p ./MyGame --input '{"query":"actors | select Label"}'
unreal-mcp-cli run-system-tool ping -p ./MyGame

플래그: -p, --path, --url, --token, --input <json>, --input-file <file>(stdin은 -), --timeout <ms>(기본값 60000).

동일한 로직을 타입이 지정된 라이브러리(import { openProject, runTool } from 'unreal-mcp-cli')로 사용할 수 있으며, AI Game Dev 앱에서 사용합니다.