[!IMPORTANT] Union은 더 이상 사용되지 않습니다. Unity 공식 MCP 서버를 사용하세요.

Union ♾️ - Unity MCP 서버

Unity를 위한 모델 컨텍스트 프로토콜(MCP) 서버

주요 기능

• 🖼️ 멀티모달 비전: 에이전트가 사용자의 시야를 볼 수 있습니다. 씬을 확인하고, 카메라를 통해 살펴보고, 플레이 모드를 관찰하며, 에셋 썸네일을 검사할 수 있습니다.

• 🔎 강력한 검색: 계층 구조(Hierarchy)와 프로젝트 에셋 전반에 걸친 동시 검색으로 프로젝트 패널 그 이상의 기능을 제공합니다.

• ✔️ 우수한 코드 분석: 에이전트의 린터보다 더 정확한 코드 분석을 위해 Unity 자체 컴파일러를 활용합니다.

• ⏩ 빠른 시작: 단일 mcp.json 구성 파일로 몇 초 만에 실행할 수 있습니다.

• 🛠️ 확장성: 최소한의 상용구 코드로 프로젝트별 도구를 직접 추가할 수 있습니다.

• 📅 항상 최신 상태: 공식 MCP C# SDK를 통해 현재 2025-06-18 버전인 최신 MCP 프로토콜 버전을 유지합니다.

Related MCP server: Unity MCP Server

호환성

설정

1. node.js 설치

2. mcp.json 구성

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "@nurture-tech/unity-mcp-runner", "-unityPath", "<path to unity editor>", "-projectPath", "<path to unity project>"]
    }
  }
}

이 작업은 Unity 프로젝트에 is.nurture.mcp 패키지를 자동으로 설치합니다. 해당 변경 사항을 소스 제어에 자유롭게 커밋하세요.

도구 소개

Unity AI 툴박스를 만나보세요.

알려진 문제

• Windows에서 Cursor를 통해 실행할 때 Google External Dependency Manager(EDMU)로 인해 Unity가 시작 시 무한 대기 상태에 빠지는 현상이 있습니다. 현재 조사 중입니다.

• test_active_scene 도구가 가끔 Maximum call stack size exceeded. 오류 메시지와 함께 실패합니다.

• search 도구가 가끔 Search index is not ready yet. Please try again later. 오류 메시지와 함께 실패합니다.

프로젝트별 도구 추가

Union은 공식 C# MCP SDK를 사용합니다.

1. 도구를 담을 정적 클래스를 생성합니다. 클래스에 [McpServerToolType] 어노테이션을 추가합니다.

2. 각 도구를 구현할 정적 메서드를 선언합니다. 각 메서드에 [McpServerTool] 어노테이션을 추가합니다.

3. 예제는 Services 디렉토리를 참조하세요.

4. 새로운 도구를 인식시키려면 Unity를 종료하고 에이전트를 다시 시작해야 할 가능성이 높습니다.

사용 팁

Union을 최대한 활용하기 위한 몇 가지 팁입니다:

• 🚀 에이전트를 통해 실행: 항상 AI 에이전트의 MCP 통합을 통해 Unity를 실행하세요. Hub에서 Unity를 실행하면 MCP 서버가 연결되지 않습니다.

• 📂 프로젝트별 설정: 에이전트가 지원하는 경우, 프로젝트별 설정에서 MCP 서버를 구성하세요. 이를 통해 Unity 프로젝트 간에 원활하게 전환할 수 있습니다.

• ⚙️ 명령줄 인수: CI/CD 파이프라인을 위해 -batchmode 또는 -nographics로 실행하는 것과 같은 고급 시나리오의 경우 Unity에 추가 인수를 전달할 수 있습니다. Unity 전용 인수 앞에 -- 구분 기호를 추가하세요:

  {
    "mcpServers": {
      "unity": {
        "command": "npx",
        "args": [
          "-y",
          "@nurture-tech/unity-mcp-runner"
          "-unityPath",
          "<path to unity editor>",
          "-projectPath",
          ".",
          "--",
          "-batchmode",
          "-nographics"
        ]
      }
    }
  }

• ⚠️ 중요: -logFile 명령줄 인수를 사용하지 마세요. MCP 서버는 통신을 위해 Unity의 표준 출력을 사용합니다.

• 🖥️ 비전을 위한 화면 분할: screenshot과 같은 도구를 사용할 때는 Unity 에디터가 화면에 표시되어 있는지 확인하세요. 그렇지 않으면 전경 창의 스크린샷이 찍히게 됩니다.