# CLI 레퍼런스 — Unreal Engine · AI Game Developer Wiki

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

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/unreal/cli).

`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`이 필요합니다.

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

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

```bash
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 확장 설치 |
| `login` | ai-game.dev 로그인 (디바이스 코드 흐름) |
| `configure` | `UNREAL_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` (비어 있지 않은 폴더 허용).

```bash
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

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

```bash
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-only` | CI 러너용 도구 전용 자격 증명 생성 (앱에서는 사용 불가) |
| `-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 클라이언트 연결](https://ai-game.dev/ko/docs/wiki/unreal/connecting-ai-clients#setup-mcp)을 참고하세요.

| 플래그 | 의미 |
| --- | --- |
| `-p, --path <dir>` | 프로젝트 폴더 |
| `--transport <t>` | `http`(기본값) 또는 `stdio`(로컬 서버 다운로드) |
| `--url <url>` | 명시적 서버 URL |
| `--token <token>` | 명시적 베어러 토큰, 프로젝트 키보다 우선 |
| `--oauth` | Cloud: URL만 있는 구성, 에이전트가 직접 로그인 |
| `--regenerate-key` | Cloud: 새 프로젝트 키를 만들고 이전 키를 폐기 |
| `--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-connect` | `UNREAL_MCP_*` 변수를 전달하지 않음 |
| `--headless` | CLI가 소유한 창 없는 에디터를 시작하고 준비될 때까지 대기 |
| `--idle <seconds>`, `--url <url>` | CLI 소유 에디터의 유휴 종료 및 서버 URL |
| `--engine-root <dir>` | 소스 빌드용 엔진 폴더 |
| `--no-build` | 실행 전 네이티브 모듈 빌드 생략 |
| `--no-auto-dismiss-startup-dialogs` | Unreal의 시작 프롬프트를 그대로 둠 |
| `--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을 실행합니다. 실행 중인 에디터를 재사용하거나, 화면 밖에서 렌더링하는(스크린샷이 계속 동작하도록) 헤드리스 에디터를 시작하고 도구 호출이 일정 시간 없으면 종료합니다.

```bash
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 서버를 통해 도구 하나를 호출합니다:

```bash
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 앱](https://ai-game.dev/ko/docs/wiki/app)에서 사용합니다.

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/unreal/cli

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/unreal/cli