MCP Unity

MCP Unity Expert Skill

Complete reference for working with Unity Editor via MCP (Model Context Protocol). 164 tools across 13 categories, integrated chat system, server-side caching.

Version: 1.0.0 | MCP Protocol: 2024-11-05 | Unity: 6000.0+ | Node.js: 18+

1. Architecture Overview

Communication Flow

AI Client (Claude Code, Claude Desktop, etc.)
    |  MCP via stdio
    v
Node.js Bridge (Server~/src/)
    |  JSON-RPC 2.0 over WebSocket
    v
Unity Editor Plugin (Editor/McpServer/)
    |
    +-- Tool Execution (main thread, queued)
    +-- Chat Panel --- Direct HTTP/SSE ---> LLM APIs

Components

Threading Model

WebSocket messages arrive on background threads. McpBehavior.OnMessage queues them to a ConcurrentQueue<QueuedMessage>. EditorApplication.update processes up to 10 messages per frame on the main thread (required for all Unity API calls).

Security

• Path validation: All asset paths must start with Assets/, .. is blocked (TrySanitizePath)
• WebSocket auth: Optional shared secret via UNITY_SECRET env var (query parameter on connect)
• Destructive op confirmation: Chat panel shows dialog before dangerous operations
• API keys: Stored in EditorPrefs (never committed to version control)
• OAuth PKCE: Supported for Anthropic (browser-based flow with auto-refresh)

2. Setup & Configuration

Installation

# Option A: Unity Package Manager (Git URL)
# Window > Package Manager > + > Add package from git URL:
https://github.com/JulianKerignard/mcp-unity.git

# Option B: Local — copy to Packages/com.juliank.mcp-unity/

# Build the bridge
cd Packages/com.juliank.mcp-unity/Server~/
npm install && npm run build

Client Configuration

Claude Code CLI:

claude mcp add mcp-unity -- node /absolute/path/to/Server~/build/index.js

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json macOS):

{
  "mcpServers": {
    "mcp-unity": {
      "command": "node",
      "args": ["/absolute/path/to/Server~/build/index.js"],
      "env": { "UNITY_PORT": "8090" }
    }
  }
}

Cursor / Windsurf / other MCP clients: Same config format as Claude Desktop.

Environment Variables

McpSettings (Unity-side)

Stored in ProjectSettings/McpUnitySettings.json, auto-saved.

Starting the Server

In Unity: Tools > MCP Unity > Server Window → click Start Server. Status indicator turns green when ready. The Setup Wizard (Tools > MCP Unity > Setup Wizard) guides through initial setup (Node.js check, build, config generation).

3. Tool Categories & Usage

Dynamic Loading (Token Optimization)

MCP Unity uses category-based dynamic loading:

• 47 core tools (incl. 2 meta-tools) always available
• 117 additional tools loaded on demand per category
• Use unity_list_tool_categories to discover categories
• Use unity_enable_tool_category to load a category

Meta-Tools

13 Categories Summary

Full tool reference: references/tool-reference-complete.md

Essential Workflows

Session Start (always do this first):

1. unity_get_editor_state              → check play mode, compilation status
2. unity_get_project_overview          → render pipeline, assets, scenes, packages
3. unity_list_gameobjects (tree mode)  → scene hierarchy overview

Scene Modification:

1. unity_list_gameobjects { outputMode: "tree" }   → see hierarchy
2. unity_get_component { gameObjectPath, componentType }   → inspect
3. unity_modify_component_batch { modifications: [...] }   → change (batch!)
4. unity_save_scene                                         → persist

Create Multiple Objects:

unity_create_gameobject_batch {
  objects: [
    { name: "Floor", primitiveType: "Plane", position: {x:0,y:0,z:0}, scale: {x:10,y:1,z:10} },
    { name: "Player", primitiveType: "Capsule", position: {x:0,y:1,z:0},
      components: [{ type: "Rigidbody" }] },
    { name: "Light", primitiveType: "Empty", position: {x:0,y:3,z:0},
      components: [{ type: "Light", properties: { type: 1, intensity: 1.5 } }] }
  ]
}

Script Workflow:

1. unity_create_script { scriptName, savePath, scriptType, methods }
   OR unity_write_script { filePath, content }
2. unity_refresh_and_compile   → trigger domain reload
3. unity_add_component { gameObjectPath, componentType: "YourScript" }

Prefab Workflow:

1. Build a GameObject in scene (create + configure)
2. unity_create_prefab { gameObjectPath, savePath }
3. unity_instantiate_prefab { prefabPath, position }
4. Modify instance → unity_apply_prefab_overrides { gameObjectPath }

Batch Operations

Always prefer batch tools over individual calls:

• unity_create_gameobject_batch — create 2+ objects in one call, single Undo
• unity_modify_component_batch — modify components on multiple objects at once
• unity_set_terrain_heights_batch — sculpt entire terrain regions
• unity_paint_terrain_texture_batch — paint textures on regions

Resources (Read-Only, No Tool Call Needed)

4. Performance Optimization

Token Reduction Rules

Screenshot Workflow (Token-Safe)

// Step 1: Capture to file (NO base64)
unity_take_screenshot {
  view: "Scene",
  returnBase64: false,
  format: "jpg",
  jpgQuality: 60,
  width: 640,
  height: 360
}
// Returns { savedPath: "Assets/Screenshots/..." }

// Step 2: View with Read tool if needed
Read { file_path: "Assets/Screenshots/screenshot.jpg" }

Asset Preview Workflow

// Step 1: Small preview, jpg format
unity_get_asset_preview {
  assetPath: "Assets/Models/Character.fbx",
  size: "small",     // tiny(32), small(64), medium(128)
  format: "jpg",
  jpgQuality: 50
}
// Returns savedPath in Assets/Screenshots/

// Step 2: Read if needed
Read { file_path: savedPath }

Cache System

The Node.js bridge caches read-only results with TTL:

Write operations auto-invalidate relevant cache entries. Max 500 cached entries. Cleanup runs every 60 seconds.

Full invalidation map: references/cache-invalidation-map.md

Common Component Names

Use exact type names (no namespace prefix needed):

• Transform: always present, never add — use unity_set_transform
• Physics: Rigidbody, BoxCollider, SphereCollider, CapsuleCollider, MeshCollider
• Rendering: MeshRenderer, MeshFilter, Light, Camera
• Audio: AudioSource, AudioListener
• Animation: Animator
• UI: Canvas, CanvasScaler, GraphicRaycaster, Image, Text

Material Property Names

All material properties start with underscore (_):

• Standard/Built-in: _Color, _MainTex, _Metallic, _Glossiness, _BumpMap, _EmissionColor
• URP/Lit: _BaseColor, _BaseMap, _Metallic, _Smoothness
• System auto-detects render pipeline. "Standard" maps to "Universal Render Pipeline/Lit" in URP.

5. Chat Panel

Overview

The integrated chat panel runs inside Unity Editor (IMGUI). It calls tools directly via McpToolRegistry — no Node.js bridge needed.

9 Provider Presets

Full provider details: references/provider-configs.md

Tool Execution Loop

1. AI response arrives via SSE streaming
2. Parser detects tool_use content blocks
3. Each tool executed on main thread via McpToolRegistry
4. Results added to conversation → follow-up request
5. Loop continues until no tool calls or max 10 iterations

Destructive Operation Confirmation

These tools trigger a confirmation dialog in chat before execution:

• Destructive: delete_gameobject, delete_asset, clear_baked_data, clear_navmesh, clear_occlusion, remove_terrain_trees, remove_terrain_detail
• Scripts: write_script, create_script, update_script
• Dangerous: execute_menu_item, unpack_prefab
• Long/Irreversible: switch_platform, bake_lighting, bake_lighting_async, bake_navmesh, bake_occlusion

User denial returns "Operation denied by user" error; AI continues without that op.

Features

• Drag & drop: Drag assets/GameObjects into input → @Name mention + full context on send
• Export: Markdown, JSON, Plain Text, or clipboard (toolbar ⇩ button)
• Context bar: Shows token usage vs. model context window
• Markdown rendering: Code blocks, headers, tables, blockquotes, links, lists

EditorPrefs Keys

Per-provider settings stored in EditorPrefs:

• McpUnity_ActiveProvider — active provider ID
• McpUnity_ProviderKey_{id} — API key
• McpUnity_ProviderModel_{id} — selected model
• McpUnity_ProviderMaxTokens_{id} — max tokens
• McpUnity_ProviderEndpoint_{id} — custom endpoint
• McpUnity_ProviderTemp_{id} — temperature

6. Troubleshooting

Connection Issues

Tool Issues

Performance Issues

Chat Issues

7. Advanced Patterns

Custom Tool Development

Full guide: references/custom-tool-guide.md

Quick summary:

1. C#: Register in Editor/McpServer/Tools/ (partial class, McpToolDefinition)
2. TypeScript: Add to Server~/src/tools.ts with defer_loading: true
3. Cache: Add invalidation in Server~/src/cache.ts if tool writes state
4. Build: npm run build in Server~/

Conventions

Key Source Files

Editor/McpServer/
├── McpUnityServer.cs        # Main partial class — lifecycle, queue, helpers
├── McpJsonRpc.cs            # JSON-RPC 2.0 dispatcher + JSON parser
├── McpToolRegistry.cs       # Tool registration, categories, execution
├── McpResourceRegistry.cs   # Resource registration
├── McpProtocol.cs           # Protocol data classes
├── McpSettings.cs           # Persistent settings + shared secret
├── Tools/                   # 164 tool implementations (43 files, partial classes)
├── Chat/                    # AI chat panel (McpChatWindow, ApiClient, OAuth)
├── Helpers/                 # ArgumentParser, ColorParser, GameObjectHelpers
├── Models/                  # LogEntry, QueuedMessage, MemoryCacheData
└── Utils/                   # McpConstants, PathValidator, TypeConverter

Server~/src/
├── index.ts                 # MCP stdio server, request handlers
├── UnityBridge.ts           # WebSocket client + secret auth + reconnect
├── tools.ts                 # 47 core tool definitions (meta + core)
├── resources.ts             # Resource definitions + workflow docs
├── cache.ts                 # TTL cache + invalidation map
└── types.ts                 # Zod schemas, error codes, BridgeConfig

Editor Window Tabs