Unity MCP

Unity MCP (Model Context Protocol) Bridge — Connect AI agents to Unity Editor.

Architecture

AI Agent (Claude, Cursor, etc.)
    ↕ stdio (MCP protocol)
UnityMcpBridge (.NET)
    ↕ TCP (binary protocol)
Unity Editor (UnityMcpEditor package)

Two components are required:

Claude Code Plugin 설치 (권장)

Claude Code에서 플러그인으로 설치하면 MCP 서버, Skills, Agents, Hooks가 한 번에 구성됩니다.

Step 1. Unity Editor 패키지 설치

Unity 6000.0+ 필요

Unity Editor > Window > Package Manager > + > Add package from git URL:

https://github.com/breadpack/UnityMcp.git?path=UnityMcpEditor

Step 2. Claude Code에서 플러그인 설치

Claude Code 세션 내에서:

/plugin install --from github:breadpack/UnityMcp

또는 프로젝트 .claude/settings.json에 등록:

{
  "enabledPlugins": {
    "unity-mcp": {
      "source": {
        "source": "github",
        "repo": "breadpack/UnityMcp"
      }
    }
  }
}

설치 시 아래 옵션을 프롬프트로 설정할 수 있습니다:

Step 3. 검증

Unity Editor를 연 상태에서 Claude Code에 다음과 같이 요청:

"Unity에 ping을 보내줘"

포함 구성요소

MCP 서버 (unity-bridge) — 45+ Unity 도구 (씬, 컴포넌트, 에셋, 빌드 등)

Agents 3종 — 특정 도메인 전문 에이전트

Skills 6종 — 워크플로우 가이드 (슬래시 커맨드)

Hooks — 자동 상태 관리

• SessionStart: Unity 연결 상태 체크 및 프로젝트 정보 출력
• PreToolUse: 도구 호출 전 컴파일/도메인 리로드 감지. 진행 중이면 대기 후 재시도.
• PostToolUse: 씬 변경 도구 실행 후 auto_save_scene=true 시 자동 저장.
• PostToolUseFailure: 도구 실행 실패 시 연결 복구 진단.

사용 예시

> @unity-scene-architect 3D 플랫포머 기본 씬을 만들어줘. 바닥, 플레이어, 카메라.

> @unity-debugger 현재 씬의 에러 원인을 찾아줘.

> /unity-mcp:unity-build-deploy
> Windows 타겟으로 빌드해줘.

수동 설치 (플러그인 없이)

플러그인을 사용하지 않고 개별 도구에서 MCP 서버만 쓰고 싶다면:

Quick Start

Step 1. Install MCP Bridge

No pre-install needed — just configure and go (see Step 3).

Or install globally:

# npx (recommended, no .NET required)
npx -y unity-mcp-bridge

# dotnet tool (requires .NET 9.0+ SDK)
dotnet tool install -g dev.breadpack.UnityMcpBridge

Step 2. Install Unity Editor Package

Requires Unity 6000.0+ (Unity 6)

Open Unity Editor > Window > Package Manager > + > Add package from git URL:

https://github.com/breadpack/UnityMcp.git?path=UnityMcpEditor

Newtonsoft.Json (com.unity.nuget.newtonsoft-json) is auto-resolved as a dependency. No other prerequisites required.

Step 3. Configure your AI tool

Add MCP server configuration to your AI tool:

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "unity-mcp-bridge"]
    }
  }
}

Or via CLI:

claude mcp add unity -- npx -y unity-mcp-bridge

Edit %APPDATA%/Claude/claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "unity-mcp-bridge"]
    }
  }
}

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "unity-mcp-bridge"]
    }
  }
}

If you installed via dotnet tool install -g, use the command directly:

{
  "mcpServers": {
    "unity": {
      "command": "unity-mcp-bridge"
    }
  }
}

Step 4. Verify

Open Unity Editor with the package installed, then ask your AI agent:

"Unity에 ping을 보내줘"

Alternative: Clone and Build

If you prefer to build from source:

git clone https://github.com/breadpack/UnityMcp.git
cd UnityMcp/UnityMcpBridge
dotnet run

Configure with:

{
  "mcpServers": {
    "unity": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/UnityMcp/UnityMcpBridge"]
    }
  }
}

Requires .NET 9.0+ SDK

Configuration

Example with custom port:

{
  "mcpServers": {
    "unity": {
      "command": "unity-mcp-bridge",
      "env": { "UNITY_TCP_PORT": "9877" }
    }
  }
}

Available Tools (35)

Observation (14)

Scene Manipulation (10)

Component & Property (4)

Material (2)

Asset Management (1)

Prefab (1)

Animation (1)

Build & Settings (2)

Conditional Features

Addressables Support

To enable Addressable tools, add the scripting define symbol to your Unity project:

1. Edit > Project Settings > Player > Scripting Define Symbols
2. Add UNITY_MCP_ADDRESSABLES

Update

npx는 자동으로 최신 버전을 사용합니다. dotnet tool을 사용하는 경우:

dotnet tool update -g dev.breadpack.UnityMcpBridge

License

MIT