unity-mcp-cli 레퍼런스

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

설치#

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가 이를 설치합니다.

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

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

일반적인 세션#

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 에디터를 설치합니다. 인자가 없으면 최신 안정 버전을 설치합니다.

create-project#

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

install-plugin#

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

install-extension#

공식 확장을 Packages/manifest.json에 설치합니다. Extensions를 참고하세요.

remove-plugin#

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

configure#

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

bootstrap-local#

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

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

login#

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

setup-mcp#

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

setup-skills#

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

Editor 명령#

open#

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

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

close#

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

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 모드)에서 가져옵니다.

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

run-system-tool#

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

exec#

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

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

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

유지 관리#

update#

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

라이브러리로 사용#

이 패키지는 출력 대신 결과 객체를 반환하는 타입 지정된 Node.js API(installPlugin, removePlugin, configure, setupMcp, installExtension 등)도 내보냅니다. 패키지의 npm README를 참고하세요.

관련 페이지#

• 설치 및 시작하기.
• open이 설정하는 환경 변수는 구성을 참고하세요.
• 데스크톱 앱 자체의 CLI인 gamedev: 앱 CLI.