Unity Mcp Bridge

npm NuGet License: MIT

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:

Plugin Marketplace 설치 (권장)

Codex 또는 Claude Code에서 marketplace 방식으로 설치하면 MCP 서버, Skills, Hooks가 한 번에 구성됩니다. Claude Code에서는 추가로 Agents 3종도 함께 사용할 수 있습니다.

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. Codex에서 설치

이 저장소는 Codex marketplace 파일을 포함합니다:

• Marketplace: .agents/plugins/marketplace.json
• Plugin: plugins/unity-mcp/.codex-plugin/plugin.json

Codex CLI에서 marketplace를 추가한 뒤 플러그인을 설치합니다:

codex plugin marketplace add breadpack/UnityMcp
codex plugin add unity-mcp@breadpack-unitymcp

로컬 checkout으로 테스트할 때는 repository root를 marketplace root로 추가합니다:

git clone https://github.com/breadpack/UnityMcp.git
cd UnityMcp
codex plugin marketplace add .
codex plugin add unity-mcp@breadpack-unitymcp

설치 후 새 Codex thread를 시작하면 unity-bridge MCP 서버와 Unity workflow skills가 로드됩니다.

Codex에서 포트나 대기 시간을 바꾸려면 Codex를 실행하는 셸/환경에 아래 변수를 설정합니다:

Step 3. Claude Code에서 설치

이 저장소는 Claude Code marketplace 파일도 포함합니다:

• Marketplace: .claude-plugin/marketplace.json
• Plugin: plugins/unity-mcp/.claude-plugin/plugin.json

Claude Code 세션 내에서:

/plugin marketplace add breadpack/UnityMcp
/plugin install unity-mcp@breadpack-UnityMcp

또는 /plugin 메뉴에서 breadpack-UnityMcp marketplace를 선택한 뒤 unity-mcp를 설치합니다.

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

포트는 workspace(projectPath) 기준으로 9876~9885를 자동 탐색하므로 별도 설정이 필요 없습니다. 고정 포트를 강제하거나 대기 시간을 바꾸려면 환경변수(UNITY_TCP_PORT, UNITY_MAX_WAIT_SEC)를 사용하세요.

Step 4. 검증

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

"Unity에 ping을 보내줘"

포함 구성요소

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

Skills 6종 — Unity workflow 가이드

Agents 3종 (Claude Code) — 특정 도메인 전문 에이전트

Hooks — 자동 상태 관리

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

사용 예시

> Unity 씬 계층을 확인하고 현재 상태를 요약해줘.

> @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"]
    }
  }
}

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

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

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

{
  "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 (overrides auto-discovery):

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

Available Tools (38)

Observation (16)

Scene Manipulation (10)

Component & Property (4)

Material (2)

Asset Management (1)

Prefab (2)

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