이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
유니티 CLI MCP 사용법, 설치부터 클로드(Claude) 연동까지
유니티 CLI MCP(Unity CLI MCP)를 설치하고 클로드 같은 AI에 연결해, 말로 시켜서 유니티 게임을 만드는 방법을 알려 준다. Unity Hub에서 CLI를 설치하는 법, 기본 명령어, 프로젝트 만들기, AI 연결 절차, 총알 피하기 게임 데모까지 순서대로 따라 할 수 있다.

유니티 CLI란, 시작 전 준비물
유니티(Unity)는 게임과 3D 앱을 만드는 제작 프로그램이다. 새로 나온 Unity CLI(명령줄 인터페이스, 마우스 대신 글자 명령을 쳐서 프로그램을 다루는 방식)를 쓰면 마우스로 드래그하던 기존 GUI(버튼과 창을 눌러 쓰는 화면 방식) 대신 텍스트 명령으로 유니티를 다룬다. 원격 제어도 된다. CLI만으로도 에디터를 켜지 않고 콘텐츠 개발을 할 수 있다는 점이 가장 큰 변화다.
준비물은 세 가지다.
- Unity 계정. unity.com에서 가입한다.
- Unity Hub. 유니티 에디터 버전과 프로젝트를 한곳에서 관리하는 관리 프로그램이다. unity.com에서 내려받아 설치하고 Unity 계정으로 로그인한다.
- 평소 쓰는 AI 도구. 클로드 데스크톱 앱처럼 창으로 쓰는 앱이든, 터미널에서 쓰는 AI든 괜찮다.
Unity CLI 설치하기
공식 문서는 구글에서 "Unity CLI"를 검색하면 나오는 영문 Unity Docs 페이지다. 크롬 자동번역을 켜두면 읽기 편하다.
설치는 Unity Hub(최신 3.21 버전)에서 한다.
- Hub 상단의 툴박스 아이콘을 누른다.
- 목록에서 "Unity CLI" 메뉴를 고른다.
- "설치" 버튼을 누르면 10~20초 뒤 완료된다.
- "열기"를 누르면 터미널이 자동으로 열린다.
현재 버전은 베타 6(Experimental, 아직 시험 단계라는 뜻)이고, Hub의 업데이트 메뉴로 최신화할 수 있다.
Hub 없이 설치해도 된다. 공식 문서(2026년 10월 기준)가 안내하는 방법은 아래와 같고, 셋 중 하나만 실행하면 된다.
curl -fsSL https://unity.com/install.sh | bash # macOS·Linux 설치 스크립트
brew install --cask unity-cli # macOS·Linux, Homebrew를 쓸 때
winget install Unity.CLI # 윈도우
Unity Hub는 윈도우뿐 아니라 macOS와 Linux에도 같은 형태로 있다. 툴박스 아이콘에서 Unity CLI를 설치하는 흐름은 동일하고, 달라지는 건 터미널을 여는 방법뿐이다. macOS는 응용 프로그램 > 유틸리티 > 터미널을 열거나 iTerm을 쓰고, Linux는 기본 셸을 쓴다. 아래 명령도 그대로 통한다.
설치 확인과 유니티 CLI 기본 명령어
- 터미널을 연다. 윈도우에서는 작업 표시줄 검색에 "터미널"을 입력해 PowerShell을 연다. 맥은 응용 프로그램 > 유틸리티 > 터미널이다.
unity라고 치고 Enter를 누른다. - 파란 Unity 로고가 뜨면 설치가 된 것이다.
기본 명령어는 아래와 같다. # 뒤는 설명이라 칠 필요가 없다.
unity --version # 설치 확인 겸 버전 보기
unity self-update # CLI 최신화 (unity upgrade도 같은 명령)
unity auth login # 브라우저 창이 따로 열리며 Unity 계정 로그인 (Hub 로그인 창과는 다르다)
unity auth status # 로그인 상태 확인
unity license activate # 라이선스 활성화
unity license list # 보유 라이선스 목록
라이선스는 유니티를 쓸 수 있는 사용권이다. 개인 무료 사용권도 여기에 해당한다.
하위 명령 이름이나 옵션은 베타 단계라 판마다 바뀔 수 있다. 그래서 외워 두는 것보다, 막힐 때마다 아래 두 줄로 설치된 버전의 실제 목록을 확인하는 편이 빠르다.
unity --help
unity <명령> --help # 예: unity license --help
에디터 설치와 프로젝트 생성
에디터는 유니티에서 실제로 게임을 만드는 작업 프로그램 본체다. 설치 가능한 에디터 버전 목록을 먼저 확인하고, 버전 번호나 "LTS"를 지정해 설치한다. LTS는 오랫동안 고쳐 주고 지원하는 안정판이라 처음이라면 이쪽이 무난하다. 설치 경로는 지정하지 않으면 기본 경로(윈도우 기준 Program Files\Unity Hub\Editors 등)를 쓰고, Hub에서 미리 경로를 정해두면 CLI도 그 경로를 따른다.
unity editors # 설치 가능한 에디터 버전 목록
unity templates # 템플릿 목록 (에디터 버전을 지정해 조회)
unity project new # 새 프로젝트 만들기
unity open # 현재 폴더의 프로젝트 열기
템플릿은 2D, 3D처럼 용도별로 미리 짜 둔 빈 프로젝트 틀이다. 프로젝트를 만드는 순서는 이렇다.
- 설치된 에디터 버전 기준으로 템플릿 목록을 조회한다.
- 원하는 템플릿 이름을 복사한다(Ctrl+C).
- 프로젝트 생성 명령을 실행하고 프로젝트 이름을 입력한다.
- 복사해둔 템플릿 이름을 붙여넣는다.
- 사용할 에디터 버전을 지정한다.
각 단계에서 붙는 옵션 이름은 unity project new --help
프로젝트를 열 때는 터미널에서 해당 폴더로 이동한 뒤 unity opencd 폴더경로
Unity Pipeline 패키지는 무슨 역할을 하나
이번에 새로 생긴 레이어다. 패키지는 유니티 프로젝트에 끼워 넣는 기능 묶음을 말한다. Pipeline 패키지는 CLI 명령을 실제 유니티 에디터에 전달하는 로컬 서버(Editor Server)라고 보면 된다. 로컬 서버는 내 컴퓨터 안에서 명령을 받아 전해 주는 중계 프로그램이다.
HTTP와 JSON 기반 프로토콜을 쓰지만, 사용자는 프로토콜을 몰라도 CLI 명령만 알면 된다. 프로토콜은 프로그램끼리 말을 주고받는 약속된 형식이다. 터미널뿐 아니라 직접 만든 웹페이지나 애플리케이션 같은 커스텀 UI에서도 이 구조로 유니티를 제어할 수 있다.
유니티 CLI MCP를 클로드에 연결하는 방법
MCP는 클로드 같은 AI가 외부 프로그램을 직접 조작하게 해주는 연결 규격이다. 유니티 CLI MCP는 기존에 유니티 에디터 안에 있던 "Unity MCP"(에디터 설정 → AI 메뉴에서 서버 연결하던 방식)를 대체한다. 그 기존 도구는 점차 없어질 예정이다.
"Unity AI 결제(월 10달러)가 있어야 MCP를 쓸 수 있다"는 오해가 있는데, Unity CLI MCP는 무료로 쓸 수 있다. Claude·
연결 전에 확인할 것
- Unity 에디터 6.0 LTS 이상. CLI가 실행 중인 에디터를 다루려면 이 버전이 필요하다.
- 위에서 설치한 Unity CLI(
unity --version이 나와야 한다). - 클로드 쪽 프로그램. 터미널이나 클로드 데스크톱 앱의 Code 탭에서 쓰는 클로드 코드가 가장 잘 맞는다. 클로드 데스크톱 앱의 채팅에서도 쓸 수 있다.
- 프로젝트에 에디터 안 AI 도우미(AI Assistant) 패키지가 들어 있다면 2.13 이상이어야 CLI와 충돌하지 않는다.
연결 순서
- 터미널에서 유니티 프로젝트 폴더로 이동해 Pipeline 패키지를 넣고, 그 프로젝트를 에디터로 연다. Pipeline 패키지는 앞 구획에서 설명한 중계 서버다.
unity pipeline install
unity open
- MCP 설정을 만든다. 먼저 목록을 보고, 쓰는 클로드 프로그램 이름을 붙여 다시 실행하면 그 프로그램의 MCP 설정 파일에 유니티 서버가 들어간다. Claude 말고도 VS Code, Cursor, Windsurf, Codex 같은 도구가 목록에 나온다.
unity mcp configure --list # 구성 가능한 클라이언트와 현재 설정 상태
unity mcp configure <클라이언트> # 예: unity mcp configure claude
<클라이언트> 자리에는 목록에 나온 이름을 그대로 쓴다. 클로드 데스크톱 앱이면 앱을 완전히 종료했다가 다시 켜야 새 설정을 읽는다.
- 유니티 공식 스킬을 넣는다. 스킬은 AI에게 특정 작업 방법을 알려주는 설명서 묶음이다. 공식 스킬은 GitHub
Unity-Technologies/unity-agent-plugin저장소에 있고, 그 안의skills/unity-cli폴더가 Unity CLI 스킬이다. 쓰는 곳에 따라 넣는 법이 다르다.
클로드 코드에서는 세션 안에서 아래 두 줄을 차례로 입력한다. 범위를 물으면, 여러 프로젝트에 쓸 거라면 나(user)를 고른다.
/plugin marketplace add Unity-Technologies/unity-agent-plugin
/plugin install unity@unity-agent-plugin
클로드 데스크톱 앱 채팅에서는 저장소를 ZIP으로 받아 압축을 풀고, skills/unity-cli 폴더만 다시 ZIP으로 묶는다(SKILL.md
CLI로 바로 넣을 수도 있다. unity skill install <클라이언트>unity skill install --help
- AI 도구에서 방금 만든 유니티 프로젝트 폴더를 작업 폴더(루트)로 연다. 클로드 코드는 터미널에서 그 폴더로
cd한 뒤claude를 실행하거나, 데스크톱 앱 Code 탭에서 그 폴더를 고른다. - AI에게 "Unity CLI 스킬을 사용해서 이 프로젝트를 한번 실행해봐"라고 프롬프트(AI에게 주는 지시 문장)를 입력한다. 명령 실행 권한을 묻는 창이 뜨면 "자동 허용"으로 바꿔야 매번 확인을 누르지 않아도 된다. 화면에 "스킬 사용" 표시가 뜨면 정상 연동된 것이다.
목록에 없는 AI를 쓰고 있다면 설정 파일을 손으로 만들어도 된다. MCP 설정은 어느 클라이언트나 "이 명령을 이 인자로 실행해서 서버로 붙여라"는 JSON(프로그램이 읽는 정리된 텍스트 형식) 한 덩이다. 그래서 목록에 있는 클라이언트 하나로 파일을 한 번 만들어 두고, 그 내용을 자기 클라이언트의 MCP 설정 위치에 옮겨 적으면 된다. AI가 프로젝트를 열었을 때 Pipeline 패키지가 없으면 먼저 설치를 제안하기도 한다.
연결됐는지 확인하기
- 터미널에서
unity status를 실행하면 연결된 에디터의 포트, 프로젝트 경로, 버전이 나온다. 아무것도 안 나오면 에디터가 꺼져 있거나 Pipeline 패키지가 없는 것이다. - 클로드 코드에서는
claude mcp list(터미널) 또는 세션 안/mcp에 유니티 서버가 연결됨으로 보이는지 본다. 입력창에 /unity:를 치면 플러그인 스킬 목록이 뜨고, /plugin의 Installed 탭에 unity가 켜져 있으면 스킬 설치도 끝난 것이다. - 클로드 데스크톱 앱 채팅에서는 사용자 지정 → 스킬에 Unity CLI 스킬이 켜져 있는지 본다.
- 마지막으로 AI에게 "Unity CLI MCP를 연결하고 현재 장면 상태를 점검해봐"라고 물으면 AI가 버전·프로젝트·서버 정보와 씬(게임 속 한 장면) 오브젝트(장면에 놓인 물체) 목록까지 보고한다.
지우거나 끄기
- MCP 연결: 클로드 코드는
claude mcp list에 보이는 이름으로 claude mcp remove <이름>을 실행한다. 다른 클라이언트는 그 설정 파일에서 유니티 항목을 지운다. - 스킬: 클로드 코드는
claude plugin uninstall unity@unity-agent-plugin, 클로드 데스크톱 앱은 사용자 지정 → 스킬에서 스킬을 고른 뒤 "…" → 삭제. - Unity CLI 자체: 설치 스크립트로 넣었다면
unity self-uninstall -y, Homebrew나 winget으로 넣었다면 그 패키지 관리자로 지운다.
막힐 때
unity명령을 못 찾는다: 터미널을 새로 열거나, 설치 폴더를 PATH에 넣는다.unity doctor가 진단 결과를 보여 준다. /plugin명령이 없다: 클로드 코드가 오래된 판이다.claude --version으로 보고 업데이트한다. VS Code 확장에서는 /plugins를 쓴다. - 스킬은 보이는데 에디터가 안 움직인다: 에디터가 열려 있는지, 그 프로젝트에
unity pipeline install을 했는지, unity status에 에디터가 잡히는지 차례로 본다.
말로 시켜 만드는 총알 피하기 게임 데모
큐브 생성 같은 간단한 오브젝트 조작을 확인한 뒤, 미리 준비한 "총알 피하기 게임" 기획을 프롬프트로 전달하면 된다. 이 데모에서 Claude는 스크립트(게임 동작을 정하는 코드 파일) 생성, 씬 배치, 테스트 실행, 밸런스 조정까지 CLI 명령으로 수행했다. 총알 생성 위치 오류가 나오자 실시간 프롬프트로 수정을 요청해 해결했다.
같은 데모를 따라 해보려면 이 정도로 시키면 된다.
Unity CLI 스킬을 써서 이 프로젝트에 간단한 총알 피하기 게임을 만들어 줘.
- 플레이어는 화면 아래쪽에서 좌우로만 움직인다
- 총알은 화면 위 바깥에서 생성돼 아래로 내려온다. 화면 안에서 생기면 안 된다
- 총알에 닿으면 게임 오버, 살아 있는 시간을 점수로 표시한다
- 씬 배치와 스크립트를 만든 다음 플레이 모드로 한 번 돌려서 오류가 없는지 확인해 줘
- 오류가 있으면 고치고, 무엇을 왜 고쳤는지 알려 줘
먼저 무엇을 만들지 계획을 정리해서 보여주고, 내가 좋다고 하면 그때 파일을 만들어 줘.
마지막 한 줄은 넣어 두는 편이 낫다. 자동 허용을 켜 두면 AI가 확인 없이 파일을 만들기 시작하므로, 계획을 먼저 받아보는 쪽이 되돌리기 쉽다.
유니티 CLI MCP의 장점: 토큰 절약과 업데이트
CLI 명령이 미리 정해져 있어서 AI 응답의 "노이즈"가 줄고 불필요한 토큰 소모도 억제된다. 토큰은 AI가 글을 처리하는 단위로, 사용량과 비용을 셈하는 기준이 된다.
지금 베타 단계인 CLI 명령어 자체도 계속 효율적으로 업데이트될 예정이다. 명령이 다듬어지면 이를 쓰는 AI 에이전트 성능도 함께 좋아질 것이라는 기대가 있다.
자주 묻는 질문
유니티 CLI MCP는 무료인가요?
무료로 쓸 수 있다. 월 10달러인 Unity AI 결제가 있어야 한다는 말은 오해다. 다만 유니티 에디터 자체의 라이선스 조건과 요금은 바뀔 수 있으니 공식 안내를 확인해야 한다.
유니티 CLI는 맥에서도 쓸 수 있나요?
쓸 수 있다. Unity Hub는 macOS와 Linux에도 있고, 툴박스 아이콘에서 Unity CLI를 설치하는 흐름도 같다. 터미널을 여는 방법만 다르고, 명령어는 그대로 통한다.
기존 Unity MCP와 유니티 CLI MCP는 뭐가 다른가요?
기존 Unity MCP는 에디터 안의 AI 메뉴에서 서버를 연결하는 방식이었다. 유니티 CLI MCP는 에디터 밖의 명령줄 도구를 통해 AI가 유니티를 다루는 방식이고, 기존 도구를 대체한다. 기존 도구는 점차 없어질 예정이다.
클로드가 유니티 프로젝트를 인식하지 못하면 어떻게 하나요?
터미널에서 unity statusunity pipeline install/unity: 입력, 앱은 사용자 지정 → 스킬)도 함께 본다. 명령 이름이 다르게 나오면 unity --help 목록이 기준이다.
이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.
원본 영상 보러가기 ↗