/ 디렉터리 / 플레이그라운드 / unity-mcp
← 모든 서버 ↗ GitHub
● 커뮤니티 CoplayDev ⚡ 바로 사용

unity-mcp

제작: CoplayDev · CoplayDev/unity-mcp

Claude에서 Unity Editor를 제어합니다 — 씬을 구축하고, C# 스크립트를 작성하고, 테스트를 실행하고, 콘솔을 검사할 수 있으며, 모두 채팅 내에서 수행합니다.

Unity용 MCP(CoplayDev 개발)는 씬 계층 구조, 프리팹, 머티리얼, 패키지, 스크립트, 테스트, 프로파일러를 다루는 40개 이상의 도구를 제공합니다. Unity 패키지와 Python 브리지로 설치되며, Unity 측에서는 AI가 연결하는 로컬 HTTP 서버를 실행합니다. Claude Desktop, Cursor, VS Code 및 모든 MCP 클라이언트에서 작동합니다.

▶ 데모 보기 📦 설치 💡 사용 사례

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

unity.replay ▶ 준비됨
0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "unity",
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json
{
  "context_servers": {
    "unity": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/CoplayDev/unity-mcp"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add unity -- TODO 'See README: https://github.com/CoplayDev/unity-mcp'

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: unity-mcp

텍스트 설명으로 Unity 씬을 프로토타입하는 방법

👤 게임 디자이너, 솔로 개발자, 해커톤 팀 ⏱ ~20 min intermediate

언제 쓸까: '저폴리 숲에 플레이어와 5명의 순찰 적'에서 모든 GameObject를 손으로 연결하지 않고도 실행 가능한 씬으로 이동하고 싶을 때 사용합니다.

사전 조건
  • Unity 2021.3 LTS 이상, Python 3.10+, uv — brew install uv로 uv를 설치합니다. Unity는 unity.com/download에서 설치합니다.
  • Unity 패키지 설치 — Window > Package Manager > + > Add from git URL: https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
흐름
  1. 원하는 씬을 설명합니다.
    'ForestDemo'라는 새로운 씬을 생성합니다. 200x200 저폴리 지형, 원점에 리지드바디가 있는 플레이어 캡슐, (-50,-50)~(50,50) 사이에 무작위로 배치된 5개의 큐브 적을 추가합니다.✓ 복사됨
    → 씬이 생성되었고, GameObjects가 Hierarchy에 나타나며, Unity가 변경 사항을 실시간으로 반영합니다.
  2. 동작 스크립트를 요청합니다.
    두 개의 무작위 웨이포인트 사이를 이동하는 C# 스크립트 EnemyPatrol.cs를 만들고, 모든 Enemy* GameObject에 첨부합니다.✓ 복사됨
    → 새 스크립트가 깔끔하게 컴파일되고 적에 첨부됩니다.
  3. Play 모드에 진입하여 반복합니다.
    Play 모드에 5초 동안 진입한 후 콘솔을 읽고 오류가 발생했는지 알려줍니다.✓ 복사됨
    → 런타임 로그가 반환되고, Claude는 모든 NullReferenceException에 대한 구체적인 수정을 제안합니다.

결과: 무기가 있는 적의 실행 가능한 프로토타입 씬 — 채팅으로 15분 이내에 완성됩니다.

함정
  • 연쇄 컴파일 오류로 인해 스크립트 편집이 거부됩니다. — Claude에게 apply_text_edits 전에 manage_script validate를 실행하도록 요청합니다.
  • 도메인 재로드가 세션 중간에 런타임 상태를 지웁니다. — 스크립트 편집 전에 씬을 명시적으로 저장합니다. 이후에 refresh_unity를 사용합니다.
함께 쓰기: filesystem · github

Unity 컴파일/런타임 오류를 채팅에서 진단하고 수정하는 방법

👤 빨간 콘솔에 갇혀있는 Unity 개발자 ⏱ ~15 min intermediate

언제 쓸까: 콘솔이 큰 리팩터링이나 패키지 업데이트로 인한 오류로 가득 차 있고 두 번째 관점이 필요할 때 사용합니다.

흐름
  1. 콘솔을 끌어옵니다.
    Unity 콘솔을 읽고 오류를 근본 원인별로 그룹화합니다.✓ 복사됨
    → 그룹화된 오류 카테고리 및 식별된 가능한 파일
  2. 문제가 있는 스크립트를 읽습니다.
    언급된 상위 스크립트를 열고, 줄을 찾아 왜 깨지는지 설명합니다.✓ 복사됨
    → 줄 번호를 참조하는 구체적인 수정 제안
  3. 최소 패치를 적용합니다.
    컴파일을 위해 가장 작은 변경을 적용하고, Unity를 새로고침한 후 콘솔을 다시 읽습니다.✓ 복사됨
    → 오류 개수가 감소하고 새로운 오류가 도입되지 않음

결과: 녹색 콘솔 및 커밋 전에 검토할 수 있는 diff

함정
  • Claude는 다른 스크립트의 API 계약을 위반하는 수정을 제안합니다. — 편집하기 전에 참조를 찾도록 요청합니다(find_in_file).
함께 쓰기: github

Unity EditMode/PlayMode 테스트를 실행하고 실패를 읽는 방법

👤 실제 테스트 스위트를 가진 Unity 개발자 ⏱ ~15 min intermediate

언제 쓸까: PR을 열기 전이거나 CI가 다운되었을 때 빠른 로컬 통과를 원할 때 사용합니다.

흐름
  1. 테스트 실행을 시작합니다.
    Tests.EditMode 어셈블리에서 모든 EditMode 테스트를 실행합니다.✓ 복사됨
    → 테스트 작업 ID가 반환되고 상태가 스트리밍됩니다.
  2. 실패를 요약합니다.
    각 실패한 테스트에 대해 어설션 메시지와 발생한 줄을 표시합니다.✓ 복사됨
    → 테스트별 진단
  3. 가장 작은 실패부터 수정합니다.
    내 마지막 변경으로 인해 가장 가능성이 높은 실패를 선택하고 패치를 제안합니다.✓ 복사됨
    → 구체적인 편집 제안

결과: 추적 가능한 편집이 있는 녹색 테스트 실행

함정
  • PlayMode 테스트는 다른 어셈블리가 필요합니다. — EditMode 대 PlayMode를 명시적으로 지정합니다.
함께 쓰기: github

조합

다른 MCP와 조합해 10배 효율

unity + github

씬과 스크립트를 스캐폴드하고, 변경 사항을 커밋하고, 검토를 위해 PR을 엽니다.

Unity에서 EnemyPatrol 기능을 빌드하고, 새 스크립트와 씬 변경 사항을 'feature/enemy-patrol' 브랜치에 커밋한 후, 변경 사항 요약과 함께 PR을 엽니다.✓ 복사됨
unity + filesystem

로컬 폴더에서 3D 에셋 배치를 가져오고 프리팹에 연결합니다.

/Downloads/kenney-nature-pack을 읽고, 모든 .fbx를 Assets/Models/로 가져온 후, 콜라이더가 있는 각 트리에 대한 프리팹을 만듭니다.✓ 복사됨
unity + unity-2 + unity-3

워크플로에 가장 적합한 Unity MCP를 선택합니다 — 한 번에 하나만 실행합니다.

내 2D 타일맵 프로젝트를 위해 MCP for Unity 대 CoderGamester mcp-unity를 비교한 후, 더 나은 것을 유지합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구입력언제 호출비용
manage_scene action: 'create'|'open'|'save'|'load', name?: str, path?: str 모든 씬 라이프사이클 변경 free
find_gameobjects query: str, scene?: str 이름, 태그 또는 컴포넌트로 객체 찾기 free
manage_components target: str, action: 'add'|'remove'|'modify', component: str, values?: obj 컴포넌트 연결 또는 조정 free
manage_script action: 'create'|'read'|'delete', path: str, body?: str 전체 파일 스크립트 쓰기 — 부분 편집의 경우 apply_text_edits 사용 free
apply_text_edits path: str, edits: Edit[] 외과적 패치; 전체 재작성보다 더 안전함 free
read_console since_ms?: int 모든 변경 후 오류/경고 검사 free
run_tests mode: 'EditMode'|'PlayMode', filter?: str 테스트 실행 시작; get_test_job으로 폴링 free
refresh_unity 스크립트 또는 에셋 생성/수정 후 free
manage_asset action, path, ... 에셋 가져오기/이동/삭제 free
unity_docs query: str 인라인에서 Unity API 문서 조회 free

비용 및 제한

운영 비용

API 쿼터
원격 API 없음 — 머신에서 완전히 실행됩니다.
호출당 토큰
씬 계층 구조 읽기: 500–3000 토큰. 스크립트 읽기: 파일 크기에 따라 다름
금액
무료(오픈 소스, MIT)
팁
도구 허용 목록을 통해 사용하지 않을 도구(예: manage_vfx, manage_probuilder)를 비활성화하여 프롬프트 풋프린트를 축소합니다.

보안

권한, 시크릿, 파급범위

최소 스코프: Unity 프로젝트에 대한 로컬 파일시스템 쓰기
자격 증명 저장: 필요 없음 — localhost HTTP만 사용
데이터 외부 송신: Localhost만(http://localhost:8080/mcp). 기본적으로 원격 측정 없음.
절대 부여 금지: 활성 프로젝트 외부의 Unity 프로젝트에 대한 액세스

문제 해결

자주 발생하는 오류와 해결

Claude가 연결할 수 없습니다: ECONNREFUSED localhost:8080

MCP 패키지가 로드된 Unity Editor가 열려 있어야 합니다. Window > MCP for Unity > Status를 확인하세요.

확인: curl http://localhost:8080/mcp/ping
apply_text_edits가 'file changed on disk' 보고

다른 도구가 파일을 수정했습니다. 다시 편집하기 전에 manage_script로 다시 읽으세요.

refresh_unity가 영원히 멈춥니다.

대개 컴파일 오류가 도메인 재로드를 잠급니다. Unity를 열고 빨간 스크립트를 수정한 후 다시 시도하세요.

확인: 수동으로 Unity 콘솔 확인
Package Manager 'Could not resolve git URL'

프록시 뒤에 있거나 PATH에 git이 없습니다. git을 설치하고 다시 시도하거나 대신 OpenUPM 설치를 사용하세요.

확인: git --version

대안

unity-mcp 다른 것과 비교

대안언제 쓰나단점/장점
Unity-MCP (IvanMurzak)CLI 기반 설정 및 Roslyn 기반 C# 실행을 원할 때Coplay보다 커뮤니티가 작고 다른 도구 표면
mcp-unity (CoderGamester)씬 조작 및 테스트에 초점을 맞춘 더 간단한 도구 세트를 원할 때더 적은 도구, 머티리얼/VFX의 적은 범위

더 보기

리소스

📖 GitHub에서 공식 README 읽기

🐙 열린 이슈 보기

🔍 400+ MCP 서버 및 Skills 전체 보기