⚙️ 1. 시작하기 전

사실 Coplay에서 친절하게 가이드를 전부 제공을 한 상태이기 때문에 참고하시면 됩니다.

🐻‍❄️ 1-1. Coplay Github

Coplay Github

📄 1-2. Coplay 공식 기술문서

Coplay 기술문서

---

📥 1-3. 필수 설치 목록

✔️ 1-3-1. Unity 2021.3 LTS+

해당 버전 이상으로 설치해주시고 무조건 LTS로 설치하셔야 합니다.

✔️ 1-3-2. Python 3.10+ and uv

📥 1-3-2-1. 파이썬 설치

파이썬 설치

📥 1-3-2-2. UV 설치

UV는 터미널에서 사용할 수 있도록 해주는 파이썬 패키지 입니
UV 공식 가이드를 참고하시면서 설치하주시면 됩니다

1️⃣ 터미널에서 UV 설치
터미널 열어서 해당 명령키를 입력하여 설치합니다.

① PowerShell을 사용하는 경우
윈도우 사용자는 PowerShell를 사용하시면 됩니다.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

② Git Bash를 사용하는 경우
Powershell이 명령키가 잘 안 먹힐 때가 있어서 그 때는 Git을 설치하여 Git Bash에서 Linux 계열 명령어를 입력해주시면 됩니다.

curl -LsSf https://astral.sh/uv/install.sh | sh

2️⃣ 설치됐는지 확인
재시작해서 해당 명령키를 넣어서 확인하시면 됩니다.

uv --version
uvx --version

Powershell이나 Git Bash 아무 터미널 괜찮습니다!
저 명령어를 입력했을 때 버전이 나오면 설치가 완료된겁니다.

📥 1-3-2-3. An MCP Client

Claude Desktop, Claude Code, Cursor, VS code Copilot, Antigravity 등 원하시는 걸로 설치하시면 됩니다

저는 Claude Code를 사용할 예정입니다

---

⚙️ 2. Unity에 패키지 설치

📥 2-1. Unity MCP 설치

Unity 프로젝트를 먼저 생성하고 PackageManager에서 URL로 패키지를 추가합니다

Window > Package Manager > Add package from git URL...

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

유니티에서 Window > MCP For Unity가 나와있으면 설치 된 겁니다.

📥 2-2. Coplay 설치

Window > Package Manager > Add package from git URL...

로 가셔서 해당 링크 복사해서 설치하시면 됩니다.

https://github.com/CoplayDev/coplay-unity-plugin.git#beta

🚨 2-2-1. Unity 6인 경우 오류

Unity 6에서는 해당 오류가 나오면서 툴바에 Coplay 버튼이 안 보일 겁니다.

We have detected that your project includes custom elements added to the Unity Editor's main toolbar using unsupported methods. This approach is not supported and will lead to issues in future versions. Refer to the official <a href="https://docs.unity3d.com/6000.3/Documentation/ScriptReference/Toolbars.MainToolbar.html">API documentation</a> for adding custom elements to the main toolbar.

Your custom toolbar elements can be unhidden via the context menu (right-click the main toolbar -> <i>Unsupported User Elements</i>).
UnityEngine.UIElements.VisualElement:Add (UnityEngine.UIElements.VisualElement)
Coplay.Coplay/<>c:<CoplayToolbarButton>b__30_0 ()
UnityEditor.EditorApplication:Internal_CallDelayFunctions ()

Coplay 플러그인이 Unity 6의 새로운 툴바 API를 아직 완전히 지원 못해서 나오는 경고입니다.

사용할 수 없는 건 아니니 걱정 안 하셔도 됩니다.

저기 경고 메시지대로 우클릭 → Unsupported User Elements 에서 다시 표시할 수 있습니다.

이렇게 Coplay AI가 나오면 잘 된 겁니다.

---

⚙️ 3. Claude 설치

Claude로 Unity MCP를 사용하려면 무조건 Pro 요금제를 사용하고 있어야 합니다!

그리고 Claude Desktop과 Claude Code 중 하나만 설치하시면 됩니다.

📥 3-1. Claude Desktop 설치

Claude 공식 사이트 가셔서 앱 다운 받으시면 됩니다

📥 3-2. Claude Code 설치

해당 작업은 PowerShell보다는 Git Bash로 설치하시는 걸 권장합니다.

✔️ 3-2-1. Node.js와 npm 설치

https://nodejs.org 에서 LTS 버전 다운로드 후 설치

1️⃣ 설치 확인 (Git Bash)
둘 다 버전 숫자가 뜨면 설치 완료된 겁니다

node --version
npm --version

이 때 PowerShell을 사용하여 npm이 안 먹는 경우가 있습니다.

PowerShell은 기본적으로 외부 스크립트 실행을 막는 보안 정책이 있어서, npm 같은 명령어가 차단될 수 있습니다.

⭐ 해결방법

PowerShell을 관리자 권한으로 열고 아래 명령어 실행합니다

시작 메뉴에서 PowerShell 검색 → 우클릭 → "관리자 권한으로 실행"

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Y 입력 후 터미널 완전히 닫고 재시작하면 npm 정상 작동합니다.

✔️ 3-2-2. Claude Code CLI 설치

터미널을 열고 다음 명령어를 누르시면 됩니다.

npm install -g @anthropic-ai/claude-code

1️⃣ 설치 확인 (Git Bash)
마찬가지로 버전 숫자가 뜨면 설치 완료됨

claude --version

---

🔗 4. Unity MCP 연결

지금까지는 MCP 연결을 위해 필요한 것을 설치했다면 이제는 MCP 연결을 진행할 겁니다.

둘 다 Claude지만 Desktop과 Code 각각 연결하는 방법이 조금 다릅니다.

🔖 4-1. Claude Code

✔️ 4-1-1. Coplay MCP 서버 추가

터미널(Git Bash)에 해당 명령어를 넣어 Claude Code에 서버를 추가합니다.

claude mcp add --scope user --transport stdio coplay-mcp --env MCP_TOOL_TIMEOUT=720000 -- uvx --python ">=3.11" coplay-mcp-server@latest

해당 부분이 나오면 정상적으로 등록된 겁니다.

Added stdio MCP server coplay-mcp with command: uvx --python >=3.11 coplay-mcp-server@latest to user config

✔️ 4-1-2. Claude Code 실행 후 서버가 등록되었는지 확인

Git Bash에 해당 명령어를 입력하시면 Claude Code가 실행됩니다.

claude

다음으로 /mcp를 입력하여 Unity MCP 서버가 있는지 확인합니다

여기서 coplay-mcp가 보인다면 정상적으로 연결된겁니다.

🔖 4-2. Claude Desktop

✔️ 4-2-1. Claude Desktop 실행

✔️ 4-2-2. 설정 > 개발자 > 구성 편집

✔️ 4-2-3. claude_desktop_config.json JSON 파일을 열어서 해당 부분 추가

    {
      "mcpServers": {
        "coplay-mcp": {
          "command": "uvx",
          "args": [
            "--python",
            ">=3.11",
            "coplay-mcp-server@latest"
          ],
          "env": {
            "MCP_TOOL_TIMEOUT": "720000"
          }
        }
      }
    }

✔️ 4-2-4. MCP 서버가 등록 잘 되었는지 확인

Claude 설정에 개발자에 들어가셔서 Coplay MCP 서버가 연결되어 있으면 완료한겁니다.

---

🤖 5. 테스트

연결까지 완료했다면 테스트를 한번 해봅시다

유니티에서 Window > MCP For Unity > Toggle MCP Window 에 들어가주세요.

일단 사용할 AI가 register 되어있는지 확인합니다

지금 이미지처럼 되어있으면 된 겁니다.(전 Claude Code로 테스트 중)

유니티에 테스트 명목으로 한번 시켜보고 정상 작동하는지 확인합니다.

지금 MCP 세팅 전부 완료했는데 기능이 동작하는지 테스트 한번 해줄 수 있을까?