Molayo

© 2026 Molayo

GitHub요약2026. 05. 26. 14:16

Glade-tool/glade-mcp-unity

요약

Glade-tool은 Cursor, Claude Code, Windsurf 등 다양한 AI 클라이언트를 Unity 에디터와 직접 연결하는 MCP(Model Context Protocol) 기반 도구입니다. 235개 이상의 도구와 RAG, 시맨틱 검색 기능을 통해 Unity 개발 워크플로우를 혁신합니다.

핵심 포인트

  • MCP를 통한 AI 클라이언트와 Unity 에디터 간의 직접 연결
  • 235개 이상의 Unity 전용 도구 및 시스템 프롬프트 제공
  • 스크립트 시맨틱 검색 및 RAG 기반의 클라우드 인텔리전스 레이어
  • Cursor, Claude Code, Windsurf 등 주요 AI 도구 지원

Cursor, Claude Code, Windsurf, Claude Desktop 및 기타 AI 클라이언트들을 귀하의 Unity Editor에 직접 연결하세요.

235개 이상의 도구. 완전한 Unity 인식 시스템 프롬프트 (System Prompt). GLADE.md 프로젝트 컨텍스트 (Project Context). 스크립트 시맨틱 검색 (Script semantic search). 기술 보정 (Skill calibration). 무료 CC0 에셋 파이프라인 (Kenney). RAG 및 교차 세션 메모리 (Cross-session memory)를 갖춘 클라우드 인텔리전스 레이어 (Cloud intelligence layer). 모든 핵심 기능은 무료이며 로컬에서 작동합니다.

Unity에서: Window > Package Manager > + > Add package from git URL...

Unity 브릿지는 localhost:8765에서 자동으로 시작됩니다.

uv 설치 (1회성):

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

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

그 다음 AI 클라이언트에 MCP 설정을 추가하세요. 클라이언트가 MCP 서버를 자동으로 실행하므로 별도의 수동 서버 단계가 필요 없습니다.

Claude Code

옵션 A — 한 줄 명령어 (권장):

Mac/Linux: claude mcp add --transport stdio gladekit-unity --scope user -- uvx gladekit-mcp

Windows: claude mcp add --transport stdio gladekit-unity --scope user -- cmd /c uvx gladekit-mcp

옵션 B — 수동 설정:

이 리포지토리(repo)를 클론(clone)했다면 .mcp.json이 자동으로 연결됩니다. 그렇지 않다면 Claude Code MCP 설정에 다음을 추가하세요:

{
"mcpServers": {
"gladekit-unity": {
...

Cursor

Cursor Settings > MCP > Add new MCP server:

{
"mcpServers": {
"gladekit-unity": {
...

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (Mac) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows) 파일을 편집하세요:

{
"mcpServers": {
"gladekit-unity": {
...

Windsurf

Windsurf에서 Windsurf Settings → MCP Servers → Open MCP Registry를 연 다음, 설정(톱니바퀴) 아이콘을 클릭하여 mcp_config.json을 엽니다. 아래 스니펫을 추가하거나 ~/.codeium/windsurf/mcp_config.json을 직접 편집하세요:

{
"mcpServers": {
"gladekit-unity": {
...

Unity AI Gateway (에디터 내장형)

Unity AI Gateway (에디터 내장형)

Unity의 내장 AI 어시스턴트는 MCP를 통해 GladeKit에 연결할 수 있습니다. 이를 통해 외부 AI 클라이언트가 필요 없이 Unity Editor 내부에서 GladeKit의 230개 이상의 도구를 사용할 수 있습니다.

필수 사항: AI Gateway 패키지(com.unity.ai.assistant@2.x)가 설치된 Unity 6000.3 이상 버전

  • Unity에서 Edit > Project Settings > AI > MCP Servers로 이동하여 Open Config File을 클릭하고 다음 내용을 붙여넣으세요:
{
"enabled": true,
"path": "",
...

  • Path Configuration 아래에 터미널의 PATH를 User Path에 붙여넣어 Unity가 uvx를 찾을 수 있도록 하세요. PATH를 얻는 방법:
    Mac/Linux: echo $PATH
    Windows: echo %PATH%

  • Refresh Config File and Reload Servers를 클릭하고, 서버 섹션에서 서버가 StartedSuccessfully로 표시되는지 확인하세요.

팁: 만약 uvx를 찾을 수 없다면, 해당 디렉터리를 설정 파일의 path 필드에 추가하세요 (예: Mac에서는 "/opt/homebrew/bin", Windows에서는 "C:\Users\<you>\.local\bin"). 또는 pip install gladekit-mcp를 사용하고 `

기능GladeKit Unity MCPunity-mcp (CoplayDev)
도구 (Tools)16개 카테고리에 걸친 235개 이상의 세분화된 도구약 40개의 통합된 도구
시스템 프롬프트 (System prompt)완전한 Unity 지능 - 렌더 파이프라인 탐지, 입력 시스템 라우팅, 도구 규율 규칙없음
프로젝트 컨텍스트 (Project context)GLADE.md - 모든 요청에 게임 디자인 문서를 주입없음
스크립트 검색 (Script search)OpenAI 임베딩 (embeddings)을 통한 시맨틱 검색 (사용자 키 필요)없음
기술 보정 (Skill calibration)초보자/전문가 자동 탐지, 응답 상세도 조절없음
세션 내 메모리 (In-session memory)remember_for_session - AI가 대화 도중 사실을 저장하고 회상없음
클라우드 지능 (Cloud intelligence)GLADEKIT_API_KEY - RAG 지식 베이스, 세션 간 메모리, 컨벤션 추출없음
라이선스 (License)MITMIT

모든 핵심 기능은 **무료이며 로컬(local)**에서 작동합니다. 클라우드 지능 레이어는 선택 사항이며 GLADEKIT_API_KEY가 필요합니다.

16개 카테고리에 걸친 235개 이상의 도구

Scene • GameObjects • Scripts • Prefabs • Materials • Lighting • VFX & Audio • Animation • IK • Physics • Camera • UI • Input System • Terrain & NavMesh • Profiler • Asset Pipeline

235개 이상의 모든 도구는 실행(dispatch) 가능합니다. Claude Code는 기본적으로 약 80개의 큐레이션된 핵심 도구를 인식합니다 (Claude Code는 실질적으로 128개의 도구 제한이 있으며, Unity AI Gateway는 클라우드 토큰 예산이 있습니다). 전문적인 작업(blend trees, NavMesh, IK, Cinemachine 등)을 위한 확장 도구를 찾으려면 get_relevant_tools를 사용하세요.

5가지 메타 도구 (meta-tools): get_relevant_tools (태스크 기반 도구 탐색 + RAG 컨텍스트), remember_for_session (사실 저장), recall_session_memories (사실 검색), batch_execute (다단계 도구 실행), search_project_scripts (시맨틱 코드 검색).

7가지 MCP 리소스 (resources): 브리지 상태(Bridge health), 프로젝트 컨텍스트, 씬 계층 구조(scene hierarchy), 프로젝트 스크립트, 현재 선택 항목, GLADE.md, 세션 메모리.

GLADE.md

GLADE.md를 생성하세요.

Unity 프로젝트 루트에 있는 파일입니다. MCP 서버는 이 파일을 읽어 모든 요청에 주입합니다. 이는 영구적인 컨텍스트 계층 (context layer) 역할을 합니다. 즉, 게임의 설계 의도, 컨벤션 (conventions), 제약 사항 (constraints)이 항상 범위 내에 있게 됩니다.

# My Game
Genre: 3D platformer
Player: CharacterController, double jump enabled
...

스크립트 시맨틱 검색 (Script semantic search)

MCP 설정의 env 필드에 OPENAI_API_KEY를 설정하면, 서버가 사용자의 쿼리 (query)와 시맨틱 유사성 (semantic similarity)을 기준으로 프로젝트 스크립트의 순위를 매깁니다. "적은 어떻게 스폰되나요?"라고 물으면, 설령 파일 이름이 EnemySpawner가 아니더라도 적절한 스크립트가 나타납니다.

필요한 모든 것은 패키지에 포함되어 있으며, 별도의 설치 플래그나 추가 요소가 필요하지 않습니다. API 키는 platform.openai.com/api-keys에서 발급받을 수 있습니다 (text-embedding-3-small을 통해 검색당 몇 센트 수준의 종량제 방식).

{
"mcpServers": {
"gladekit-unity": {
...

키가 없더라도 search_project_scripts는 여전히 스크립트를 반환하지만, 순위는 매겨지지 않습니다. 키는 OpenAI의 임베딩 엔드포인트 (embedding endpoint) 외에는 어디로도 전송되지 않습니다.

기술 수준 보정 (Skill calibration)

서버는 메시지 전반에 걸친 어휘를 추적하여 사용자가 Unity 초보자인지 전문가인지 감지합니다. 초보자에게는 쉬운 언어로 된 설명과 격려하는 방식의 프레이밍 (framing)을 제공하며, 전문가에게는 간결하고 기술적인 응답을 제공합니다. 보정된 결과는 프로젝트 내의 .gladekit/skill_level.json에 유지됩니다.

에셋 파이프라인 (무료 CC0 임포트)

AI 클라이언트에서 직접 무료로 상업적 이용이 가능한 에셋을 찾고 가져올 수 있는 세 가지 도구를 제공합니다. 모든 에셋은 CC0 (퍼블릭 도메인 — 저작자 표시 불필요)입니다. v1 버전은 Kenney.nl 팩을 지원하며, 추가 제공자 (Freesound, Quaternius, AI 생성)는 로드맵에 포함되어 있습니다.

도구 (Tool)목적 (Purpose)
find_asset설명, 에셋 유형 (asset type), 스타일 및 라이선스(license)를 기준으로 순위가 매겨진 후보를 검색합니다. 읽기 전용이며, Unity로 명령을 전달하지 않습니다.
import_asset다운로드, 압축 해제, Assets/ 폴더 아래 배치, 에셋 유형에 따른 임포트 설정 (import settings) 구성, 그리고 라이선스 메타데이터가 포함된 .gladekit-asset.json 사이드카(sidecar) 파일을 작성합니다. 명시적인 licenseAcknowledged: true 설정이 필요합니다.
list_imported_assets프로젝트의 사이드카 파일들을 탐색하여 라이선스 감사 (license audit) 결과(라이선스 수, 저작자 표시(attribution) 필요 수)를 보여줍니다. 상용 출시 전 유용합니다.

예시 워크플로우 (Example workflow) (Cursor, Claude Code, Windsurf — 모든 클라이언트에서 동일한 패턴 적용):

사용자: 2D 플랫폼 게임을 프로토타이핑 중인데, 플레이스홀더(placeholder) 캐릭터와 타일 아트가 필요해. 무료인 걸로 찾아줘.

AI가 find_asset을 호출합니다:

{
"description": "platformer character and tiles",
"asset_type": "sprite_2d",
...

결과 (생략):

{
"success": true,
"candidates": [
...

사용자: Platformer Pack Redux로 하자. Assets/Sprites/Platformer/로 임포트해줘. CC0 라이선스를 수락할게.

AI가 import_asset을 호출합니다:

{
"candidateId": "kenney/platformer-pack-redux",
"assetType": "sprite_2d",
...

MCP 서버가 로컬에서 다운로드 URL을 해결하며(카탈로그는 서버와 함께 번들로 제공되므로 클라우드 의존성이 없음), 이를 Unity 브릿지(bridge)로 전달합니다. 브릿지는 파일을 다운로드하고 압축을 해제하며, 각 스프라이트(sprite)에 대해 TextureImporter를 구성하고(Texture Type = Sprite, Filter Mode = Point, Uncompressed), 라이선스 사이드카를 작성합니다. 결과:

{
"success": true,
"message": "Imported 360 file(s) from kenney/platformer-pack-redux to Assets/Sprites/Platformer/",
...

스프라이트가 Unity 프로젝트 창에 나타나며, 바로 씬(scene)에 배치할 준비가 됩니다.

사용자: 출시하기 전에 임포트된 에셋들을 감사해줘. 저작자 표시가 필요한 게 있어?

AI가 list_imported_assets를 호출합니다:

{
"success": true,
"count": 1,
...

CC0는 저작자 표시가 필요하지 않으며, 감사 보고서(audit report)에 필수 저작자 표시 항목이 비어 있습니다. 나중에 CC-BY 자산을 가져오면, 저작자를 명시할 수 있도록 여기에 나타납니다.

보안 및 라이선스 규율 (Security and license discipline):

  • LLM은 다운로드 URL을 절대 볼 수 없습니다. URL 해석(URL resolution)은 클라우드/MCP 측에서 수행됩니다. 브릿지 도구(bridge tool)는 해석된 필드가 누락되었거나 LLM에 의해 주입(LLM-injected)된 경우 거부합니다.
    licenseAcknowledged: true는 모든 import_asset 호출 시 필수입니다. 브릿지는 이 값이 없으면 거부합니다. 사용자의 명시적인 확인 없이 이 값을 설정하지 마십시오.
  • 브릿지는 다운로드 전에 _resolvedUrl의 호스트를 제공자별 허용 목록(AssetPipelineGuard.IsResolvedUrlHostAllowed)과 대조하여 검증합니다. 클라우드와 MCP 전처리기(preprocessors)를 모두 우회하는 클라이언트라 할지라도 임의의 다운로드 URL을 몰래 들여올 수 없습니다. 알 수 없는 호스트는 차단(fail closed)됩니다. HTTPS만 허용됩니다.
  • 가져온 모든 자산 번들(asset bundle)에는 후보 ID, 제공자, 라이선스, 저작자 표시 문자열, 소스 URL 및 타임스탬프를 기록하는 .gladekit-asset.json 사이드카(sidecar) 파일이 생성됩니다. list_imported_assets는 감사 보고서를 위해 이 파일들을 읽습니다.
  • 자산 파이프라인(Asset Pipeline) 도구들은 브릿지 측의 AssetPipelineGuard에 의해 제어됩니다. 잘못 설정된 클라이언트는 이를 우회할 수 없습니다.

파이프라인 비활성화 (스튜디오 / 큐레이션된 자산 워크플로우용):

세 가지 도구를 완전히 억제하려면 MCP 서버의 환경 변수에 GLADEKIT_MCP_DISABLE_ASSET_PIPELINE=1을 설정하십시오. 도구 목록에 나타나지 않으며, 호출 시 명확한 오류와 함께 거부됩니다. 이는 AI 기반의 외부 다운로드가 적절하지 않은, 이미 관리되는 자산 워크플로우(Perforce로 추적되는 라이브러리, 내부 자산 스토어 등)를 가진 프로젝트에 권장되는 설정입니다.

{
"mcpServers": {
"gladekit-unity": {
...

Unity 브릿지는 EditorPrefs (GladeAI.AssetPipelineEnabled, 기본값 true)를 통해 동일한 게이트를 강제합니다. POST http://localhost:8765/api/settings { "assetPipelineEnabled": false }를 통해 토글할 수 있습니다.

클라우드 인텔리전스 (Cloud intelligence)

클라우드 기반 기능을 사용하려면 MCP 설정의 env 필드에 GLADEKIT_API_KEY를 설정하십시오:

RAG 지식 베이스 (knowledge base)

  • get_relevant_tools: 선별된 Unity 지식 베이스(API 수정 사항, 에러 패턴)를 쿼리하고 도구 추천과 함께 결과를 주입합니다.

세션 간 지속적 메모리 (Cross-session persistent memory)

  • remember_for_session으로 저장된 사실(facts)은 세션 간에 지속되며 시스템 프롬프트에 다시 주입됩니다.

컨벤션 추출 (Convention extraction): 클라우드 백엔드는 축적된 메모리로부터 코딩 패턴(명명 규칙, 아키텍처, 선호도)을 추출합니다.

모든 클라우드 기능은 성능이 점진적으로 저하(degrade gracefully)됩니다. 즉, API 키가 누락되거나 클라우드에 접속할 수 없는 경우에도 모든 기능은 정상적으로 작동합니다.

{
"mcpServers": {
"gladekit-unity": {
...

전송 방식 (Transports: stdio + streamable HTTP)

GladeKit MCP는 두 가지 전송 방식을 지원합니다. stdio가 기본값이며 모든 MCP 클라이언트와 호환됩니다. 위의 모든 설정은 stdio를 사용합니다.

Streamable HTTP는 URL 기반 설정을 선호하는 클라이언트(Claude Desktop URL 모드, 커스텀 클라이언트)를 위한 것입니다. 서버를 수동으로 실행한 다음, 클라이언트가 해당 URL을 가리키도록 설정하십시오:

# 기본값: host=127.0.0.1, port=8766, path=/mcp
gladekit-mcp --transport http
# 커스텀 host/port/path
...

엔드포인트(Endpoints):

POST/GET/DELETE http://127.0.0.1:8766/mcp

  • MCP streamable-HTTP 엔드포인트

GET http://127.0.0.1:8766/health

  • 활성 상태 확인 (liveness check)

보안 기본 설정:

  • 루프백 전용 (loopback-only)(127.0.0.1)으로 바인딩됩니다. LAN에 노출하려면 --host 0.0.0.0을 사용하십시오. 이는 선택 사항(opt-in)입니다. 루프백 바인딩 시 **DNS 리바인딩 보호 (DNS-rebinding protection)**가 활성화됩니다: Host 헤더가 127.0.0.1:<port> 또는 localhost:<port>가 아닌 요청은 421 Misdirected Request와 함께 거부됩니다.
  • 루프백이 아닌 바인딩은 리바인딩 보호를 비활성화하며(네트워크에 대한 책임은 사용자에게 있음), 시작 시 경고를 출력합니다.

클라이언트 설정 예시:

{
"mcpServers": {
"gladekit-unity": {
...

환경 변수 (Environment Variables)

AI 자동 생성 콘텐츠

본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0