설치 — Unity · AI Game Developer Wiki

이 페이지는 Unity 프로젝트에 Unity MCP 플러그인을 추가하는 모든 방법과 각 방법이 프로젝트에 미치는 영향, 그리고 플러그인을 다시 제거하는 방법을 보여줍니다. 모든 경로가 OpenUPM 레지스트리에서 동일한 패키지 com.ivanmurzak.unity.mcp를 설치하므로, 워크플로에 맞는 방법을 선택하면 됩니다.

요구 사항

Unity 2022.3 이상. 패키지는 최소 버전으로 2022.3을 선언하며, Unity 6 릴리스도 지원합니다.
공백이 없는 프로젝트 경로. C:/Projects/MyGame은 괜찮지만 C:/My Projects/My Game은 안 됩니다. 경로에 공백이 있으면 플러그인이 시작 시 오류를 기록합니다.
Windows에서 짧은 프로젝트 경로. 플러그인은 NuGet DLL을 Assets/Plugins/NuGet에 복사합니다. 결과 경로가 Windows의 260자 제한을 넘으면 설치가 중단되고 프로젝트를 더 짧은 폴더로 옮기라는 안내가 표시됩니다.
처음 열 때 인터넷 접속. 플러그인은 NuGet에서 .NET 의존성을, Custom 모드에서는 GitHub에서 MCP 서버 바이너리를 다운로드합니다.
unity-mcp-cli 전용: Node.js ^20.19.0 또는 >=22.12.0.

옵션 1: AI Game Dev 데스크톱 앱 (권장)

AI Game Dev 앱은 터미널이나 머신의 Node.js 없이 플러그인을 설치하고 연결해 줍니다.

앱을 다운로드하고 ai-game.dev 계정으로 로그인하세요.
앱에서 Unity 프로젝트 폴더를 여세요. 앱이 Unity 프로젝트임을 감지합니다.
Install Package를 클릭하세요. 앱은 OpenUPM의 최신 릴리스 버전으로 Packages/manifest.json에 플러그인을 추가하며, 이미 설치된 더 새로운 버전을 다운그레이드하지 않습니다. 앱에서 생성한 프로젝트에는 플러그인이 자동으로 포함됩니다.
앱에서 에디터를 여세요. 앱이 세션을 전달하므로 플러그인이 별도 로그인 없이 ai-game.dev를 통해 연결됩니다.

앱은 확장 기능도 설치하고 AI 에이전트 자체를 실행하므로 별도의 MCP 클라이언트가 필요 없습니다. 자세한 내용은 앱 위키의 설치 및 프로젝트와 엔진을 참고하세요.

옵션 2: unity-mcp-cli

unity-mcp-cli는 Packages/manifest.json을 직접 편집하므로 Unity를 열어 둘 필요가 없습니다:

npm install -g unity-mcp-cli
unity-mcp-cli install-plugin ./MyUnityProject

전역 설치 없이 실행할 수도 있습니다:

npx unity-mcp-cli install-plugin ./MyUnityProject

install-plugin은 스코프 com.ivanmurzak 및 extensions.unity로 OpenUPM 스코프 레지스트리를 추가하고, 최신 OpenUPM 버전으로 com.ivanmurzak.unity.mcp를 dependencies에 추가하며, 이미 설치된 더 높은 버전을 다운그레이드하지 않습니다. 버전을 고정하려면 --plugin-version <version>을 전달하세요. 프로젝트 폴더에서 명령을 실행하는 경우 경로는 선택 사항입니다.

CLI로 Unity를 설치하고 프로젝트를 먼저 생성할 수도 있습니다:

unity-mcp-cli install-unity
unity-mcp-cli create-project ./MyUnityProject

Unity Hub가 없으면 CLI가 설치합니다. 이후 패키지 관리자가 패키지를 해석할 수 있도록 Unity에서 프로젝트를 여세요. 모든 명령은 CLI 레퍼런스에 있습니다.

옵션 3: OpenUPM

OpenUPM CLI가 설치되어 있다면 프로젝트 폴더에서 다음을 실행하세요:

openupm add com.ivanmurzak.unity.mcp

OpenUPM CLI 없이 Packages/manifest.json에 레지스트리와 의존성을 직접 추가하세요. OpenUPM 패키지 페이지에 표시된 버전을 사용하세요:

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.ivanmurzak", "extensions.unity"]
    }
  ],
  "dependencies": {
    "com.ivanmurzak.unity.mcp": "1.6.2"
  }
}

이 항목들을 기존 파일에 병합하고, 다른 의존성을 대체하지 마세요.

옵션 4: .unitypackage 설치 프로그램

AI-Game-Dev-Installer.unitypackage를 다운로드하세요.
Unity에서 프로젝트를 여세요.
파일을 두 번 클릭하거나 Assets > Import Package > Custom Package를 사용해 파일을 선택하세요.
Import를 클릭하세요.

설치 프로그램은 작은 에디터 스크립트입니다. OpenUPM 스코프 레지스트리와 플러그인 의존성을 Packages/manifest.json에 추가한 뒤 Assets에서 자신을 삭제합니다. 그런 다음 패키지 관리자가 실제 패키지를 다운로드합니다.

처음 열 때 일어나는 일

패키지가 도착하면 플러그인이 스스로를 준비합니다:

필요한 .NET 라이브러리(MCP 플러그인 라이브러리, ReflectorNet, RQL, SignalR, System.Text.Json 등)를 NuGet에서 Assets/Plugins/NuGet으로 다운로드하고, Library/NuGetCache에 캐시하며, Unity가 한 번 재컴파일합니다. 이 DLL들이 동기화되지 않는 경우 Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs를 사용하세요.
GitHub에서 해당 플랫폼용 gamedev-mcp-server 바이너리를 Library/mcp-server/<platform>/(예: win-x64, osx-arm64, linux-x64)로 다운로드합니다. 서버는 HTTP 전송을 쓰는 Custom 모드에서만 시작되며, 기본값인 Cloud 모드에서는 로컬 서버를 시작하지 않습니다.
AI Game Developer 창은 Window > AI Game Developer — MCP에서 사용할 수 있게 됩니다(단축키 Ctrl+Alt+A, macOS에서는 Cmd+Option+A). Scene View 툴바에도 이 창을 여는 AI 오버레이 버튼이 추가됩니다.

Library/는 기본적으로 버전 관리에서 제외되므로 서버 바이너리는 절대 커밋되지 않습니다. CI 환경에서는 플러그인이 서버 다운로드와 시작을 건너뜁니다.

플러그인 업데이트

OpenUPM에 더 새로운 버전이 있으면 플러그인이 에디터 시작 시 업데이트 팝업을 표시합니다. Tools > AI Game Developer > Updates > Check for Updates로 직접 확인할 수도 있습니다. 업데이트하려면 패키지 관리자에서 버전을 변경하거나, unity-mcp-cli install-plugin을 다시 실행하거나(최신 버전을 설치합니다), 데스크톱 앱에서 업데이트하도록 하세요.

한 사람이 플러그인 버전을 관리하는 팀이라면 Edit > Project Settings > AI Game Developer를 열고 Disable update notifications for the entire team을 활성화하세요. 이 설정은 ProjectSettings/AI-Game-Developer-UpdateSettings.asset에 저장되며, 해당 파일을 커밋하세요. 동일한 토글이 **Tools > AI Game Developer > Updates > Disable Update Notifications (Team)**에도 있습니다.

제거

Window > Package Manager를 열고 AI Game Developer — MCP를 선택한 뒤 Remove를 클릭하거나, unity-mcp-cli remove-plugin ./MyUnityProject를 실행하세요. 다른 패키지가 사용할 수 있으므로 CLI는 스코프 레지스트리를 유지합니다.
Unity를 종료하고 Assets/Plugins/NuGet 폴더와 그 Assets/Plugins/NuGet.meta 파일을 삭제하세요.

다음 단계

시작하기: AI 클라이언트를 연결하고 첫 프롬프트를 실행하세요.
확장 기능: Cinemachine, ProBuilder, Tilemap 등을 위한 툴 팩을 추가하세요.
설치 중 문제가 발생하면 문제 해결을 참고하세요.

요구 사항#

옵션 1: AI Game Dev 데스크톱 앱 (권장)#

옵션 2: unity-mcp-cli#

옵션 3: OpenUPM#

옵션 4: .unitypackage 설치 프로그램#

처음 열 때 일어나는 일#

플러그인 업데이트#

제거#

다음 단계#