# unity-mcp-cli 레퍼런스 — Unity · AI Game Developer Wiki

unity-mcp-cli 명령 레퍼런스 - Unity MCP 설치, 로그인, AI 에이전트 설정 작성, Unity 헤드리스 실행, 터미널에서 도구와 C# 실행까지.

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

`unity-mcp-cli`는 Unity MCP용 명령줄 도구입니다. Unity와 플러그인을 설치하고, ai-game.dev에 로그인하며, AI 에이전트 설정을 작성하고, 에디터를 열고 닫으며, 터미널이나 CI 스크립트에서 MCP 도구를 호출하거나 에디터에서 C#을 실행합니다. 이 페이지는 버전 1.6.2의 모든 명령과 플래그를 나열합니다.

## 설치

```bash
npm install -g unity-mcp-cli
```

또는 설치 없이 아무 명령이나 실행할 수 있습니다: `npx unity-mcp-cli <command>`. Node.js `^20.19.0` 또는 `>=22.12.0`이 필요하며 Windows, macOS, Linux에서 동작합니다. 에디터를 관리하는 명령은 Unity Hub CLI를 사용하며, Unity Hub가 없으면 CLI가 이를 설치합니다.

모든 명령에서 사용할 수 있는 전역 옵션:

| 옵션 | 설명 |
| --- | --- |
| `-v, --verbose` | 상세 진단 출력 |
| `-V, --version` | CLI 버전 출력 |
| `--help` | 해당 명령의 도움말 |

비대화형 터미널(CI)에서는 CLI가 스피너와 색상을 자동으로 비활성화합니다. 프로젝트 경로를 받는 대부분의 명령은 이를 위치 인자 또는 `--path`로 받으며, 기본값은 현재 폴더입니다.

## 일반적인 세션

```bash
unity-mcp-cli install-plugin ./MyGame
unity-mcp-cli login
unity-mcp-cli setup-mcp claude-code ./MyGame
unity-mcp-cli open ./MyGame
unity-mcp-cli wait-for-ready ./MyGame
unity-mcp-cli run-tool tests-run ./MyGame --input '{"testMode":"EditMode"}'
unity-mcp-cli close ./MyGame
```

## 프로젝트 설정 명령

### install-unity

Unity Hub를 통해 Unity 에디터를 설치합니다. 인자가 없으면 최신 안정 버전을 설치합니다.

| 인자 / 옵션 | 설명 |
| --- | --- |
| `[version]` | 에디터 버전, 예: `6000.3.1f1` |
| `--path <path>` | 기존 프로젝트에서 필요한 버전을 읽습니다 |

### create-project

에디터로 새 Unity 프로젝트를 생성합니다: `unity-mcp-cli create-project ./MyGame --unity 6000.3.1f1`.

| 인자 / 옵션 | 설명 |
| --- | --- |
| `[path]` | 프로젝트를 생성할 위치 (필수, 또는 `--path`) |
| `--unity <version>` | 에디터 버전 (기본값: 설치된 가장 높은 버전) |

### install-plugin

OpenUPM 스코프 레지스트리와 `com.ivanmurzak.unity.mcp`를 `Packages/manifest.json`에 추가합니다. 더 높은 버전이 설치되어 있으면 다운그레이드하지 않습니다. 해당 폴더는 Unity 프로젝트여야 합니다.

| 옵션 | 설명 |
| --- | --- |
| `[path]` | Unity 프로젝트 (기본값: 현재 폴더) |
| `--plugin-version <version>` | 설치할 버전 (기본값: OpenUPM 최신 버전) |
| `--with-server` | 이 머신용 `gamedev-mcp-server` 바이너리도 CLI 자체 폴더에 다운로드합니다 |
| `--server-version <version>` | `--with-server`에 사용할 서버 버전 |
| `--server-source <path-or-url>` | 로컬 zip 또는 URL에서 서버 설치 (오프라인 또는 CI용, 체크섬 검증 생략) |
| `--enroll <code>` | 이 프로젝트에 고정된 플러그인 자격 증명을 위해 팀 등록 코드를 사용합니다 |
| `--enroll-stdin` | 셸 기록에 남지 않도록 stdin에서 등록 코드를 읽습니다 |
| `--yes` | `--enroll` 중 계정 전환 같은 확인 프롬프트를 승인합니다 |

### install-extension

공식 확장을 `Packages/manifest.json`에 설치합니다. [Extensions](https://ai-game.dev/ko/docs/wiki/unity/extensions)를 참고하세요.

| 인자 / 옵션 | 설명 |
| --- | --- |
| `[id]` | 카탈로그 이름(`Tilemap`) 또는 패키지 id(`com.ivanmurzak.unity.mcp.tilemap`) |
| `[path]` | Unity 프로젝트 (기본값: 현재 폴더) |
| `--extension-version <version>` | 설치할 버전 (기본값: OpenUPM 최신 버전) |
| `--list` | 설치 가능한 확장 목록을 출력하고 종료 (프로젝트나 네트워크 불필요) |

### remove-plugin

`Packages/manifest.json`에서 `com.ivanmurzak.unity.mcp`를 제거하고 스코프 레지스트리는 유지합니다. `[path]`를 받습니다 (필수, 또는 `--path`).

### configure

`UserSettings/AI-Game-Developer-Config.json`에서 도구, 프롬프트, 리소스를 표시하거나 숨깁니다. 숨겨진 항목도 이름으로 호출하면 여전히 실행됩니다.

| 옵션 | 설명 |
| --- | --- |
| `[path]` | Unity 프로젝트 (필수, 또는 `--path`) |
| `--list` | 현재 구성을 출력하고 종료 |
| `--enable-tools <names>`, `--disable-tools <names>` | 특정 도구를 표시하거나 숨김 (쉼표로 구분) |
| `--enable-all-tools`, `--disable-all-tools` | 모든 도구를 표시하거나 숨김 |
| `--enable-prompts <names>`, `--disable-prompts <names>` | 프롬프트에 대해 동일하게 적용 |
| `--enable-all-prompts`, `--disable-all-prompts` | 모든 프롬프트 |
| `--enable-resources <names>`, `--disable-resources <names>` | 리소스에 대해 동일하게 적용 |
| `--enable-all-resources`, `--disable-all-resources` | 모든 리소스 |
| `--agent <id>` | 대신 관리형 서버의 구성기를 통해 AI 에이전트 설정을 작성합니다 |
| `--url <url>` | `--agent`와 함께 전달되는 서버 URL |

### bootstrap-local

프로젝트 구성을 주어진 서버 URL과 토큰으로 Custom(로컬) 모드에 고정합니다. 멱등적입니다.

| 옵션 | 설명 |
| --- | --- |
| `[path]` | Unity 프로젝트 (기본값: 현재 폴더) |
| `--url <url>` | 로컬 MCP 서버 URL (필수) |
| `--token <token>` | 로컬 베어러 토큰 (필수) |
| `--dry-run` | 기록하지 않고 변경될 내용만 보고합니다 |

## 로그인 및 AI 에이전트 명령

### login

브라우저 OAuth 디바이스 플로우로 ai-game.dev에 로그인하고 자격 증명을 `~/.ai-game-dev/credentials.json`에 저장합니다. Editor 플러그인과 데스크톱 앱은 같은 자격 증명을 사용합니다. 이미 로그인되어 있으면 즉시 종료됩니다.

| 옵션 | 설명 |
| --- | --- |
| `--project <path>` | 자격 증명을 머신 저장소 대신 `<path>/.ai-game-dev/`에 저장합니다 |
| `--force` | 자격 증명이 있어도 다시 로그인합니다 |
| `--tools-only` | CI 러너용으로 엔진 도구만 인가하며, 에이전트 자격 증명은 저장하지 않습니다 |
| `--yes` | 프롬프트 없이 계정 전환을 확인합니다 |

### setup-mcp

AI 에이전트의 MCP 설정을 작성하며, Editor 창의 **Configure**와 동일한 출력입니다. 기본적으로 URL은 이 프로젝트에 고정되고(`https://ai-game.dev/mcp/p/<pin>`), Cloud HTTP 설정의 경우 로그인되어 있으면 이 프로젝트의 키를 포함합니다. [AI 클라이언트 연결](https://ai-game.dev/ko/docs/wiki/unity/connecting-ai-clients)을 참고하세요.

| 옵션 | 설명 |
| --- | --- |
| `[agent-id]` | 설정할 에이전트. 예: `claude-code`, `cursor`, `codex` |
| `[path]` | Unity 프로젝트 (기본값: 현재 폴더) |
| `--transport <transport>` | `http` (기본값) 또는 `stdio` |
| `--url <url>` | `http`용 서버 URL 재정의 |
| `--token <token>` | 프로젝트 키 대신 이 Personal Access Token을 기록합니다 |
| `--oauth` | URL만 있는 설정을 작성하며, 에이전트가 자체 OAuth로 로그인합니다 |
| `--regenerate-key` | 새 프로젝트 키를 발급하고 설정을 다시 작성한 뒤 이전 키를 폐기합니다 |
| `--no-pin` | 고정되지 않은 `https://ai-game.dev/mcp` 엔드포인트를 사용합니다 |
| `--list` | 에이전트 id와 각 설정 경로를 나열합니다 |

### setup-skills

실행 중인 Editor를 통해 에이전트의 스킬 파일을 생성합니다. 플러그인이 연결된 상태로 Unity가 열려 있어야 합니다.

| 옵션 | 설명 |
| --- | --- |
| `[agent-id]` | 스킬을 생성할 에이전트 |
| `[path]` | Unity 프로젝트 (기본값: 현재 폴더) |
| `--url <url>`, `--token <token>` | 서버 URL 및 토큰 재정의 |
| `--timeout <ms>` | 요청 타임아웃 (기본값 60000) |
| `--list` | 에이전트와 스킬 지원 여부를 나열합니다 |

## Editor 명령

### open

Unity Editor에서 프로젝트를 열고, 주어진 옵션으로 플러그인의 연결 환경 변수를 설정합니다. 에디터는 분리된 프로세스로 시작됩니다.

| 옵션 | 설명 |
| --- | --- |
| `[path]` | Unity 프로젝트 (기본값: 현재 폴더) |
| `--unity <version>` | 에디터 버전 (기본값: 프로젝트 버전, 그다음 설치된 최고 버전) |
| `--editor-path <path>` | 에디터 실행 파일을 직접 지정하며 Unity Hub 탐색을 건너뜁니다 |
| `--no-connect` | MCP 연결 변수 없이 엽니다 |
| `--url <url>` | 서버 URL (`UNITY_MCP_HOST` 설정, `UNITY_MCP_CLOUD_URL`의 별칭) |
| `--keep-connected` | 연결을 강제로 켭니다 |
| `--token <token>` | 로컬 서버 토큰 (`UNITY_MCP_TOKEN` 설정) |
| `--auth <option>` | 인가 모드 (`UNITY_MCP_AUTH_OPTION` 설정). 이 버전은 `none` 또는 `required`를 허용합니다 |
| `--tools <names>` | 표시할 도구를 쉼표로 구분해 지정 (`UNITY_MCP_TOOLS` 설정) |
| `--transport <method>` | `streamableHttp` 또는 `stdio` |
| `--start-server <value>` | 로컬 서버 자동 시작을 위한 `true` 또는 `false` |
| `--headless` | 창 없이 시작하고(`-batchmode`, 그래픽 유지) MCP 서버가 응답할 때까지 기다립니다 |
| `--idle-timeout <seconds>` | 도구 호출 없이 이 시간(초)이 지나면 변경된 씬과 에셋을 먼저 저장한 뒤 종료합니다 |
| `--ready-timeout <ms>` | `--headless`와 함께 사용할 때 대기 시간 (기본값 300000) |
| `--no-auto-dismiss-launch-errors` | Unity의 "실행 시 컴파일 오류" 대화상자에서 **Ignore**를 클릭하지 않습니다 |
| `--launch-dismiss-timeout-ms <ms>` | 해당 대화상자를 감시할 총 시간 (기본값 30000) |
| `--launch-dismiss-poll-interval-ms <ms>` | 대화상자 폴링 간격 (기본값 1500) |

실행 오류 대화상자를 닫으려면 macOS에서는 터미널에 접근성 권한이 필요하고, Linux X11에서는 `xdotool`이 필요합니다(Wayland는 지원되지 않음).

### close

프로젝트의 Editor를 정상적으로 닫습니다: `unity-mcp-cli close ./MyGame --timeout 60 --force`. 실행 중이 아닌 Editor를 닫아도 성공합니다.

| 옵션 | 설명 |
| --- | --- |
| `[path]` | Unity 프로젝트 (기본값: 현재 폴더) |
| `--timeout <seconds>` | 정상 종료를 기다립니다 (기본값 30) |
| `--force` | 그때까지 종료되지 않으면 Editor를 강제 종료합니다 |
| `--owned-only` | CLI가 시작한 Editor만 닫습니다 (`exec`, `open --headless`) |

### wait-for-ready

Editor와 MCP 서버가 도구 호출을 받아들일 때까지 폴링합니다. 옵션: `[path]`, `--url`, `--token`, `--timeout <ms>` (기본값 120000), `--interval <ms>` (기본값 3000).

### status

Unity가 실행 중인지, 로컬 MCP 서버가 응답하는지, 설정된 서버(예: 클라우드)에 연결할 수 있는지 보여줍니다. 옵션: `[path]`, `--url`, `--token`, `--timeout <ms>` (기본값 5000).

## 도구 명령

### run-tool

서버의 HTTP API를 통해 MCP 도구를 호출합니다. URL과 토큰은 재정의하지 않는 한 프로젝트 설정(Custom 또는 Cloud 모드)에서 가져옵니다.

```bash
unity-mcp-cli run-tool rql-query ./MyGame --input '{"query":"objects | where name == \"Player\" | select path name active"}'
unity-mcp-cli run-tool unity-tool-list ./MyGame --raw
```

| 옵션 | 설명 |
| --- | --- |
| `<tool-name>` | 호출할 도구 |
| `[path]` | Unity 프로젝트. 설정 및 포트 감지에 사용됩니다 |
| `--url <url>`, `--token <token>` | 설정을 우회하는 재정의 |
| `--input <json>`, `--input-file <file>` | 도구 인수 (기본값 `{}`) |
| `--raw` | 원시 JSON 출력 |
| `--timeout <ms>` | 요청 타임아웃 (기본값 60000) |

### run-system-tool

`run-tool`과 동일한 옵션이며, MCP 클라이언트에 노출되지 않는 시스템 도구(예: 스킬 생성 및 세션 제어)에 사용합니다.

### exec

`script-execute`를 통해 에디터에서 C#을 실행하고 결과를 출력합니다. 열려 있는 에디터가 있으면 그것을 사용하고, 없으면 이후 호출을 위해 대기 상태를 유지하다가 `--idle`초 후 종료되는 헤드리스 에디터를 시작합니다.

```bash
unity-mcp-cli exec 'GameObject.FindObjectsOfType<Camera>().Length'
echo 'Application.unityVersion' | unity-mcp-cli exec
```

| 옵션 | 설명 |
| --- | --- |
| `[code]` | C# 문이며 마지막 식이 결과입니다 (`-f` 또는 stdin 사용) |
| `--path <path>` | Unity 프로젝트 (기본값: 현재 폴더) |
| `-f, --file <file>` | 파일에서 코드 읽기 (stdin은 `-`) |
| `--using <namespace>` | 추가 네임스페이스, 반복 가능 |
| `--include <path>` | `.ai-game-dev/snippets` 아래의 헬퍼 `.cs` 파일 또는 폴더, 반복 가능 |
| `--window` | 헤드리스 대신 창을 표시하여 에디터 시작 |
| `--idle <seconds>` | `exec`로 시작된 에디터가 종료되기까지의 유휴 시간 (기본값 300, 0이면 종료하지 않음) |
| `--ready-timeout <ms>` | 에디터 대기 (기본값 300000) |
| `--timeout <ms>` | 도구 호출 타임아웃 |
| `--raw` | 원시 도구 응답 JSON |
| `--url <url>`, `--token <token>` | 재정의 |

컴파일 오류가 발생하면 코드 1로 종료하고 해당 줄을 알려줍니다.

## 유지 관리

### update

CLI를 최신 npm 버전으로 업데이트합니다. `--check`는 확인만 하며 업데이트가 있으면 코드 2로 종료합니다. `npx`에서는 업데이트할 것이 없습니다.

## 라이브러리로 사용

이 패키지는 출력 대신 결과 객체를 반환하는 타입 지정된 Node.js API(`installPlugin`, `removePlugin`, `configure`, `setupMcp`, `installExtension` 등)도 내보냅니다. 패키지의 [npm README](https://www.npmjs.com/package/unity-mcp-cli)를 참고하세요.

## 관련 페이지

- [설치](https://ai-game.dev/ko/docs/wiki/unity/installation) 및 [시작하기](https://ai-game.dev/ko/docs/wiki/unity/getting-started).
- `open`이 설정하는 환경 변수는 [구성](https://ai-game.dev/ko/docs/wiki/unity/configuration#overrides)을 참고하세요.
- 데스크톱 앱 자체의 CLI인 `gamedev`: [앱 CLI](https://ai-game.dev/ko/docs/wiki/app/cli).

---

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

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