unity-api-mcp

AI 에이전트에 정확한 Unity API 문서를 제공하는 MCP 서버입니다. 잘못된 시그니처, 잘못된 네임스페이스, 사용 중단된 API 사용을 방지합니다.

Unity 6(마이너 스트림별 데이터베이스), Unity 2023, Unity 2022 LTS를 지원합니다. Claude Code, Cursor, Windsurf 또는 MCP 호환 AI 도구와 함께 작동합니다. Unity 설치가 필요하지 않습니다. 지원 버전을 참조하세요. 새로운 Unity 릴리스는 매주 자동으로 감지되어 빌드됩니다.

빠른 시작

MCP 설정(.mcp.json, mcp.json 또는 도구의 MCP 설정)에 추가하고, UNITY_VERSION을 프로젝트에 맞게 설정하세요:

{
  "mcpServers": {
    "unity-api": {
      "command": "uvx",
      "args": ["unity-api-mcp"],
      "env": {
        "UNITY_VERSION": "6000.3"
      }
    }
  }
}

유효한 값: Unity 6 스트림 "6000.3", 또는 "6", "2023", "2022".

첫 실행 시 서버는 올바른 데이터베이스(~20-30MB)를 ~/.unity-api-mcp/에 다운로드합니다.

Related MCP server: Funplay MCP for Unity

작동 방식

1. 버전 감지. 서버가 제공할 Unity 버전을 결정합니다:

2. 데이터베이스 다운로드. 해당 버전의 데이터베이스가 로컬에 캐시되지 않은 경우 GitHub에서 다운로드합니다. Unity 6 마이너 스트림(6000.0, 6000.3, 6000.5, …)은 스트림별 데이터베이스를 가지며, 스트림 데이터베이스가 게시되지 않은 경우 일반 6 데이터베이스로 대체됩니다. 캐시된 데이터베이스는 시작 시 릴리스와의 최신 상태를 확인하므로, 주간 빌드가 기존 설치에 자동으로 도달합니다.

3. 제공. 모든 도구 호출은 버전별 SQLite 데이터베이스를 쿼리합니다. 모든 쿼리는 15ms 이내에 반환됩니다.

각 버전은 해당 릴리스에 대한 올바른 시그니처, 사용 중단 경고 및 멤버 목록이 포함된 자체 데이터베이스를 가지고 있습니다.

도구

적용 범위

모든 UnityEngine 및 UnityEditor 모듈과 C# 소스에서 파싱된 패키지(Input System, Addressables, uGUI(Unity 6의 TextMeshPro 포함), AI Navigation, Netcode)를 포함합니다. Unity 6 데이터베이스당 약 42,500개의 레코드, 각각 약 500개의 사용 중단 경고가 있습니다.

전체 버전 목록: db-v1 릴리스 페이지. CI는 빌드할 때마다 해당 테이블을 재생성합니다. 새로운 Unity 패치는 매주 월요일에 자동으로 감지되어 빌드됩니다.

타사 에셋(DOTween, VContainer, Newtonsoft.Json)은 포함되지 않습니다. 해당 에셋의 경우 프로젝트 소스를 사용하세요.

벤치마크

측정된 결과(약속된 것이 아님): 3개의 테스트베드에서 25개의 연구 질문, 3개의 에이전트 구성이 답변했으며, 모든 답변은 사전에 소스에서 검증된 실제 정답과 비교하여 판단되었습니다. 전체 테스트 프레임워크는 docs/benchmark/에 있으며 하나의 명령어로 재실행됩니다.

재현된 한 가지 환각 사례는 교훈적입니다. SceneManager.LoadSceneAsync의 오버로드를 나열하라는 요청에 대해, MCP가 아닌 두 에이전트는 존재하지 않는 단일 매개변수 LoadSceneAsync(string) 및 LoadSceneAsync(int) 오버로드를 만들어냈습니다. 이에 대해 작성된 코드는 컴파일되지 않습니다. MCP 에이전트는 실제 네 가지 오버로드를 정확히 반환했습니다.

왜 정확성이고 토큰 절약이 아닌가? 에이전트 도구는 이제 코드 검색에 능숙합니다. Claude Code는 처음부터 Grep 도구를 탑재했으며, 현재 모델은 먼저 검색한 다음 좁은 라인 범위를 읽기 때문에 원시 토큰 사용량은 모든 구성에서 비슷했습니다. 그러나 정확한 오버로드, 네임스페이스 및 사용 중단 정보는 프로젝트 파일에 전혀 없습니다. MCP가 없는 에이전트는 사용 예제에서만 추론할 수 있으며, 잘못 추론하면 빌드 실패라는 대가를 치르게 됩니다.

• 3개의 테스트베드: 실제 Unity 6 게임 프로젝트(11개 질문), 순수 Unity API 조회(8개), 2,700~4,600줄 파일의 Unity Input System 패키지 소스(6개)

• 3개의 구성, 동일한 모델 및 턴 제한: MCP 도구 + Grep/Read, Grep/Read 전용, Read 전용

• 실제 정답은 모든 실행 전에 소스를 읽어 검증되었으며, 답변은 별도의 모델 세션이 해당 실제 정답과 비교하여 판단했습니다. 토큰 사용량은 API 사용 필드에서 가져왔습니다.

• 직접 실행: python docs/benchmark/run.py --project <unity-project-path> (2026년 7월 결과; 에이전트 동작은 변하므로 인용 전에 재실행하세요)

CLAUDE.md 스니펫

프로젝트의 CLAUDE.md(또는 동등한 지시 파일)에 다음을 추가하세요. 이 단계는 중요합니다. 이 단계가 없으면 AI는 도구를 가지고 있지만 언제 사용해야 할지 알지 못합니다.

## Unity API Lookup (unity-api MCP)

Use the `unity-api` MCP tools to verify Unity API usage instead of guessing. **Do not hallucinate signatures.**

| When | Tool | Example |
|------|------|---------|
| Unsure about a method's parameters or return type | `get_method_signature` | `get_method_signature("UnityEngine.Tilemaps.Tilemap.SetTile")` |
| Need the `using` directive for a type | `get_namespace` | `get_namespace("SceneManager")` |
| Want to see all members on a class | `get_class_reference` | `get_class_reference("InputAction")` |
| Searching for an API by keyword | `search_unity_api` | `search_unity_api("async load scene")` |
| Checking if an API is deprecated | `get_deprecation_warnings` | `get_deprecation_warnings("FindObjectOfType")` |

**Rules:**
- Before writing a Unity API call you haven't used in this conversation, verify the signature with `get_method_signature`
- Before adding a `using` directive, verify with `get_namespace` if unsure
- Covers: all UnityEngine/UnityEditor modules, Input System, Addressables, uGUI/TextMeshPro, AI Navigation, Netcode
- Does NOT cover: DOTween, VContainer, Newtonsoft.Json (third-party)

설정 세부 정보

UNITY_VERSION을 설정하는 대신 Unity 프로젝트를 가리킬 수 있습니다. 서버가 ProjectSettings/ProjectVersion.txt를 자동으로 읽습니다:

{
  "mcpServers": {
    "unity-api": {
      "command": "uvx",
      "args": ["unity-api-mcp"],
      "env": {
        "UNITY_PROJECT_PATH": "/path/to/your/unity-project"
      }
    }
  }
}

pip install 사용:

pip install unity-api-mcp

{
  "mcpServers": {
    "unity-api": {
      "command": "unity-api-mcp",
      "args": [],
      "env": {
        "UNITY_VERSION": "6000.3"
      }
    }
  }
}

다운로드 대신 자체 Unity 설치에서 데이터베이스를 빌드하려면:

# Install with ingest dependencies
pip install unity-api-mcp[ingest]

# Windows
python -m unity_api_mcp.ingest --unity-version 6000.3 --unity-install "D:/Unity/6000.3.8f1" --project "F:/Unity Projects/MyProject"

# macOS
python -m unity_api_mcp.ingest --unity-version 6000.3 --unity-install "/Applications/Unity/Hub/Editor/6000.3.20f1" --project "/path/to/UnityProject"

# Legacy versions
python -m unity_api_mcp.ingest --unity-version 2022 --unity-install "D:/Unity/2022.3.62f1"

데이터베이스는 기본적으로 ~/.unity-api-mcp/unity_docs_{version}.db에 기록됩니다.

AI 에이전트가 이를 설정하는 경우:

UNITY_VERSION을 내 프로젝트에 맞게 설정하여 uvx를 사용해 MCP 설정에 unity-api-mcp를 추가하고, README의 CLAUDE.md 스니펫을 추가한 다음, get_namespace("SceneManager")로 확인하세요.

unity-api-mcp/
├── src/unity_api_mcp/
│   ├── server.py          # MCP server (5 tools)
│   ├── db.py              # SQLite + FTS5 database layer
│   ├── version.py         # Version detection + DB download
│   ├── xml_parser.py      # Parse Unity XML IntelliSense files
│   ├── cs_doc_parser.py   # Parse C# doc comments from package source
│   ├── unity_paths.py     # Locate Unity install + package dirs
│   └── ingest.py          # CLI ingestion pipeline
└── pyproject.toml

데이터베이스는 ~/.unity-api-mcp/에 저장됩니다(첫 실행 시 다운로드).

문제 해결

함께 보기

unreal-api-mcp: Unreal Engine(C++)을 위한 동일한 개념으로, UE 버전별 주간 자동 빌드 데이터베이스를 제공합니다.

연락처

엔진이나 프레임워크를 위한 맞춤 MCP 서버가 필요하신가요? AI 지원 게임 개발을 위해 토큰 낭비를 줄이고 환각을 방지하는 MCP 도구를 제작합니다. 팀 스택에 유사한 것이 필요하시면 연락주세요.

fuatcankoseoglu@gmail.com

라이선스

MIT