dev.breadpack.UnityMcpBridge
MCP (Model Context Protocol) Bridge for Unity Editor โ connect AI agents to Unity Editor
Ask AI about dev.breadpack.UnityMcpBridge
Powered by Claude ยท Grounded in docs
I know everything about dev.breadpack.UnityMcpBridge. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:
| Component | Role | Install method |
|---|---|---|
| UnityMcpBridge | .NET MCP server (stdio โ TCP) | npx / dotnet tool / clone |
| UnityMcpEditor | Unity Editor plugin (TCP server + handlers) | UPM git URL |
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"
}
}
}
}
์ค์น ์ ์๋ ์ต์ ์ ํ๋กฌํํธ๋ก ์ค์ ํ ์ ์์ต๋๋ค:
| ์ต์ | ์ค๋ช | ๊ธฐ๋ณธ |
|---|---|---|
unity_tcp_port | Unity TCP ํฌํธ | 9876 |
auto_save_scene | ์ฌ ๋ณ๊ฒฝ ํ ์๋ ์ ์ฅ | false |
check_compile_status | ๋๊ตฌ ํธ์ถ ์ ์ปดํ์ผ ์ํ ์ฒดํฌ | true |
check_domain_reload | ๋๊ตฌ ํธ์ถ ์ ๋๋ฉ์ธ ๋ฆฌ๋ก๋ ์ํ ์ฒดํฌ | true |
max_wait_seconds | ์ปดํ์ผ/๋ฆฌ๋ก๋ ๋๊ธฐ ์ต๋ ์๊ฐ(์ด) | 60 |
Step 3. ๊ฒ์ฆ
Unity Editor๋ฅผ ์ฐ ์ํ์์ Claude Code์ ๋ค์๊ณผ ๊ฐ์ด ์์ฒญ:
"Unity์ ping์ ๋ณด๋ด์ค"
ํฌํจ ๊ตฌ์ฑ์์
MCP ์๋ฒ (unity-bridge) โ 45+ Unity ๋๊ตฌ (์ฌ, ์ปดํฌ๋ํธ, ์์ , ๋น๋ ๋ฑ)
Agents 3์ข โ ํน์ ๋๋ฉ์ธ ์ ๋ฌธ ์์ด์ ํธ
| Agent | ์ญํ |
|---|---|
unity-scene-architect | ์ฌ ์ค๊ณ, GameObject/์ปดํฌ๋ํธ/UI ๊ตฌ์ฑ |
unity-debugger | ์๋ฌ ์ถ์ , Play Mode ๊ฒ์ฌ, ์ฑ๋ฅ ๋ถ์ |
unity-asset-manager | Material, Prefab, Addressable, ๋น๋ ๊ด๋ฆฌ |
Skills 6์ข โ ์ํฌํ๋ก์ฐ ๊ฐ์ด๋ (์ฌ๋์ ์ปค๋งจ๋)
| Skill | ๋ช ๋ น์ด |
|---|---|
| Scene Setup | /unity-mcp:unity-scene-setup |
| UI Build | /unity-mcp:unity-ui-build |
| Material Setup | /unity-mcp:unity-material-setup |
| Prefab Workflow | /unity-mcp:unity-prefab-workflow |
| Debug | /unity-mcp:unity-debug |
| Build & Deploy | /unity-mcp:unity-build-deploy |
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:
Claude Code (.mcp.json in project root)
{
"mcpServers": {
"unity": {
"command": "npx",
"args": ["-y", "unity-mcp-bridge"]
}
}
}
Or via CLI:
claude mcp add unity -- npx -y unity-mcp-bridge
Claude Desktop
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"]
}
}
}
Cursor / VS Code (.cursor/mcp.json or .vscode/mcp.json)
{
"mcpServers": {
"unity": {
"command": "npx",
"args": ["-y", "unity-mcp-bridge"]
}
}
}
Using dotnet tool instead
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
| Environment Variable | Default | Description |
|---|---|---|
UNITY_TCP_PORT | 9876 | TCP port to connect to Unity Editor |
Example with custom port:
{
"mcpServers": {
"unity": {
"command": "unity-mcp-bridge",
"env": { "UNITY_TCP_PORT": "9877" }
}
}
}
Available Tools (35)
Observation (14)
| Tool | Description |
|---|---|
unity_ping | Check Unity Editor connection |
unity_get_hierarchy | Get scene hierarchy |
unity_get_asset_hierarchy | Inspect Prefab/Scene hierarchy without opening |
unity_get_component_details | Get component property details |
unity_get_screen | Get current screen info (Play Mode) |
unity_get_ui_tree | Get UI Toolkit visual tree (Play Mode) |
unity_get_ugui_tree | Get UGUI Canvas hierarchy |
unity_get_console_logs | Get console log entries |
unity_get_available_actions | List clickable UI actions (Play Mode) |
unity_take_screenshot | Capture game view screenshot (Play Mode) |
unity_render_uxml | Render UXML to image |
unity_refresh_assets | Refresh AssetDatabase |
unity_addressable_add | Add asset to Addressable group (requires package) |
unity_addressable_set_address | Set Addressable asset address (requires package) |
Scene Manipulation (10)
| Tool | Description |
|---|---|
unity_create_gameobject | Create new GameObject |
unity_delete_gameobject | Delete GameObject (dryRun supported) |
unity_reparent_gameobject | Change parent of GameObject |
unity_set_transform | Set position / rotation / scale |
unity_set_active | Activate / deactivate GameObject |
unity_select_gameobject | Select and ping in Editor |
unity_save_scene | Save current scene |
unity_load_scene | Open scene (Single / Additive) |
unity_play_mode | Enter / exit / toggle Play Mode |
unity_instantiate_prefab | Instantiate prefab in scene |
Component & Property (4)
| Tool | Description |
|---|---|
unity_add_component | Add component to GameObject |
unity_remove_component | Remove component (dryRun supported) |
unity_set_property | Set component property (dot-notation, array, asset ref) |
unity_set_asset_reference | Set asset reference on component field |
Material (2)
| Tool | Description |
|---|---|
unity_create_material | Create new Material asset |
unity_set_material_property | Set material property (color, float, texture, vector) |
Asset Management (1)
| Tool | Description |
|---|---|
unity_manage_asset | Move / copy / delete asset, create folder |
Prefab (1)
| Tool | Description |
|---|---|
unity_prefab_edit | Enter / save / exit Prefab edit mode |
Animation (1)
| Tool | Description |
|---|---|
unity_animator_control | Set Animator parameters, query state (Play Mode) |
Build & Settings (2)
| Tool | Description |
|---|---|
unity_build | Build player (Windows, macOS, Linux, Android, iOS, WebGL) |
unity_project_settings | Read / write PlayerSettings, QualitySettings, Physics, Time |
Conditional Features
Addressables Support
To enable Addressable tools, add the scripting define symbol to your Unity project:
- Edit > Project Settings > Player > Scripting Define Symbols
- Add
UNITY_MCP_ADDRESSABLES
Update
npx๋ ์๋์ผ๋ก ์ต์ ๋ฒ์ ์ ์ฌ์ฉํฉ๋๋ค. dotnet tool์ ์ฌ์ฉํ๋ ๊ฒฝ์ฐ:
dotnet tool update -g dev.breadpack.UnityMcpBridge
