IvanMurzak/Unity-MCP

Unity MCP is an AI-powered game development assistant for Editor & Runtime. Connect Claude, Cursor, & Windsurf to Unity via MCP. Automate workflows, generate code, and enable AI within your games.

Unlike other tools, this plugin works inside your compiled game, allowing for real-time AI debugging and player-AI interaction.

💬 Join our Discord Server - Ask questions, showcase your work, and connect with other developers!

• ✔️ AI agents - Use the best agents from Anthropic, OpenAI, Microsoft, or any other provider with no vendor lock-in
• ✔️ Tools - A wide range of default MCP Tools for operating in Unity Editor
• ✔️ Skills - Generate skills for AI based on operating system, Unity version, plugins in the project
• ✔️ Code and Tests - Develop game mechanics and test them with AI agents
• ✔️ Runtime (in-game) - Use LLMs directly inside your compiled game for dynamic NPC behavior or debugging
• ✔️ Debug support - Let AI debug and fix the problems in a project
• ✔️ Natural conversation - Chat with AI like you would with a human
• ✔️ Flexible deployment - Works locally (stdio) and remotely (http) via configuration
• ✔️ Extensible - Create custom Tools in your project code

https://github.com/user-attachments/assets/228baf4d-4f00-4dce-939d-fb985ebdd8dd

OR use cli

# 1. Install unity-mcp-cli
npm install -g unity-mcp-cli
2. Install "AI Game Developer" in Unity project
unity-mcp-cli install-plugin ./MyUnityProject
3. Sign in to ai-game.dev (opens your browser — OAuth device flow)
unity-mcp-cli login
4. Open Unity project (auto-connects and generates skills)
unity-mcp-cli open ./MyUnityProject

Quick Start

Get up and running in three steps:

1. Install plugin — download the .unitypackage installer or run openupm add com.ivanmurzak.unity.mcp > Alternative: npx unity-mcp-cli install-plugin ./MyUnityProject — see CLI documentation 2. Pick an AI agent — Claude Code, Claude Desktop, GitHub Copilot, Cursor, or any other 3. Setup AI agent — open Window/AI Game Developer in Unity and click Auto-generate skills (recommended) or Configure MCP > Alternative: npx unity-mcp-cli setup-skills claude-code ./MyUnityProject — see CLI documentation

That's it. Ask your AI "Create 3 cubes in a circle with radius 2" and watch it happen. ✨

---

Skills and Tools Reference

The plugin ships with 70+ built-in tools across four categories. Each tool brings AI skill. All tools are available immediately after installation — no extra configuration required. See docs/default-mcp-tools.md for the full reference with detailed descriptions.

🧰 Browse the full MCP tools registry online: ai-game.dev/docs/tools

Project & Assets

• assets-copy - Copy the asset at path and stores it at newPath
• assets-create-folder - Creates a new folder in the specified parent folder
• assets-delete - Delete the assets at paths from the project
• assets-find - Search the asset database using the search filter string
• assets-find-built-in - Search the built-in assets of the Unity Editor
• assets-get-data - Get asset data from the asset file including all serializable fields and properties
• assets-material-create - Create new material asset with default parameters
• assets-modify - Modify asset file in the project
• assets-move - Move the assets at paths in the project (also used for rename)
• assets-prefab-close - Close currently opened prefab
• assets-prefab-create - Create a prefab from a GameObject in the current active scene
• assets-prefab-instantiate - Instantiates prefab in the current active scene
• assets-prefab-open - Open prefab edit mode for a specific GameObject
• assets-prefab-save - Save a prefab in prefab editing mode
• assets-refresh - Refreshes the AssetDatabase
• assets-shader-get-data - Get detailed data about a shader asset (properties, subshaders, passes)
• assets-shader-list-all - List all available shaders in the project assets and packages
• package-add - Install a package from the Unity Package Manager registry, Git URL, or local path
• package-list - List all packages installed in the Unity project (UPM packages)
• package-remove - Remove (uninstall) a package from the Unity project
• package-search - Search for packages in both Unity Package Manager registry and installed packages

Scene & Hierarchy

• gameobject-component-add - Add Component to GameObject
• gameobject-component-destroy - Destroy one or many components from target GameObject
• gameobject-component-get - Get detailed information about a specific Component on a GameObject
• gameobject-component-list-all - List C# class names extended from UnityEngine.Component
• gameobject-component-modify - Modify a specific Component on a GameObject
• gameobject-create - Create a new GameObject in opened Prefab or in a Scene
• gameobject-destroy - Destroy GameObject and all nested GameObjects recursively
• gameobject-duplicate - Duplicate GameObjects in opened Prefab or in a Scene
• gameobject-find - Finds specific GameObject by provided information
• gameobject-modify - Modify GameObjects and/or attached component's fields and properties
• gameobject-set-parent - Set parent GameObject to list of GameObjects
• object-get-data - Get data of the specified Unity Object
• object-modify - Modify the specified Unity Object
• scene-create - Create new scene in the project assets
• scene-get-data - Retrieves the list of root GameObjects in the specified scene
• scene-list-opened - Returns the list of currently opened scenes in Unity Editor
• scene-open - Open scene from the project asset file
• scene-save - Save opened scene to the asset file
• scene-set-active - Set the specified opened scene as the active scene
• scene-unload - Unload scene from the opened scenes in Unity Editor
• screenshot-camera - Captures a screenshot from a camera and returns it as an image
• screenshot-game-view - Captures a screenshot from the Unity Editor Game View
• screenshot-isolated - Render a GameObject in isolation from a chosen angle (optional composite 2x2 view)
• screenshot-scene-view - Captures a screenshot from the Unity Editor Scene View

Scripting & Editor

• console-clear-logs - Clears the MCP log cache and the Unity Editor Console window
• console-get-logs - Retrieves Unity Editor logs with filtering options
• editor-application-get-state - Returns information about the Unity Editor application state (playmode, paused, compilation)
• editor-application-set-state - Control the Unity Editor application state (start/stop/pause playmode)
• editor-selection-get - Get information about the current Selection in the Unity Editor
• editor-selection-set - Set the current Selection in the Unity Editor
• reflection-method-call - Call any C# method with input parameters and return results
• reflection-method-find - Find method in the project using C# Reflection (even private methods)
• script-delete - Delete the script file(s)
• script-execute - Compiles and executes C# code dynamically using Roslyn
• script-read - Reads the content of a script file
• script-update-or-create - Updates or creates script file with the provided C# code
• tests-run - Execute Unity tests (EditMode/PlayMode) with filtering and detailed results
• type-get-json-schema - Generate a JSON Schema for a C# type via reflection

Profiling & Diagnostics

• profiler-capture-frame - Capture the current frame's timing info (delta time, FPS, frame counts)
• profiler-clear-data - Discard all frames currently held by the Editor Profiler
• profiler-enable-module - Toggle the local enabled flag for a named profiler module
• profiler-get-memory-stats - Return a memory statistics snapshot (reserved, allocated, mono heap, graphics)
• profiler-get-rendering-stats - Return frame timing, FPS, vsync, target frame rate, graphics device type
• profiler-get-script-stats - Return script execution timing plus Mono / GC memory usage
• profiler-get-status - Return the profiler's enabled state, active modules, and platform support
• profiler-list-modules - List all known profiler module names with their enabled flag
• profiler-load-data - Read back a previously-saved profiler JSON snapshot
• profiler-save-data - Save a snapshot of profiler-derived stats to a JSON file
• profiler-start - Enable Unity's runtime profiler and open the Profiler window
• profiler-stop - Disable Unity's runtime profiler

Install Additional Skills and Tools

Install extensions when need more tools or create your own tools.

| Extension | Description | | --- | --- | | AI Animation | Set of additional tools for Unity Animations | | AI Cinemachine | MCP Tools for Cinemachine | | AI InputSystem | MCP Tools for the Unity Input System | | AI Navigation | MCP Tools for AI Navigation (NavMesh surfaces, baking, agents, links) | | AI ParticleSystem | Set of additional tools for Unity Particle System | | AI ProBuilder | Set of additional tools for Unity ProBuilder | | AI Splines | MCP Tools for Unity Splines | | AI Terrain | Set of additional tools for Unity Terrain | | AI Tilemap | MCP Tools for Unity 2D Tilemaps | | AI Timeline | MCP Tools for Unity Timeline cutscenes and sequences |

Contents

• Quick Start
• Skills and Tools Reference
• Install Additional Skills and Tools
• Contents
• More Documentation
• Installation
• Step 1: Install Unity MCP Plugin
• Option 1 - Installer
• Option 2 - CLI (recommended)
• Step 2: Install AI agent
• Step 3: Configure AI agent
• Automatic configuration
• Manual configuration
• Command line configuration
• AI Workflow Examples
• Advanced Features for LLM
• Core Capabilities
• Reflection-Powered Features
• Customize Tools
• Add custom Tool
• Add custom MCP Prompt
• Runtime usage (in-game)
• Sample: AI powered Chess game bot
• Why runtime usage is needed?
• Unity MCP Server setup
• Variables
• Plugin Variables
• Docker 📦
• streamableHttp Transport
• stdio Transport
• Custom port
• Binary executable
• How Unity MCP Architecture Works
• What is MCP
• What is AI agent
• What is MCP Server
• What is MCP Tool
• When to use Tool
• What is MCP Resource
• When to use MCP Resource
• What is MCP Prompt
• When to use MCP Prompt
• Contribution 💙💛

More Documentation

| Document | Description | | -------- | ----------- | | Default MCP Tools | Full reference of all built-in tools with descriptions | | MCP Server Setup | Server configuration, environment variables, remote hosting | | Docker Deployment | Step-by-step Docker deployment guide | | Development Guide | Architecture, code style, CI/CD — for contributors | | Wiki | Getting started, tutorials, API reference, FAQ | | CLI Tool | Install plugins, configure, and connect via command line |

Installation

Step 1: Install Unity MCP Plugin

⚠️ Requirements (click)

[!IMPORTANT]

Project path cannot contain spaces

> - ✅ C:/MyProjects/MyProject

- ❌ C:/My Projects/MyProject

- ❌ C:/My Projects/My Project

- ❌ C:/MyProjects/My Project

Option 1 - Installer

• ⬇️ Download Installer
• 📂 Import installer into Unity project

> - You can double-click on the file - Unity will open it automatically > - OR: Open Unity Editor first, then click on Assets/Import Package/Custom Package, and choose the file

Option 2 - CLI (recommended)

Install the plugin via unity-mcp-cli — no Unity Editor needed:

# 1.1 Install unity-mcp-cli                                #  ┌────────────────────┐
npm install -g unity-mcp-cli                               #  │ Available AI agent │
                                                           #  ├────────────────────┤
1.2 (Optional) Install Unity                             #  │ antigravity        │
unity-mcp-cli install-unity                                #  │ claude-code        │
                                                           #  │ claude-desktop     │
1.3 (Optional) Create Unity project                      #  │ cline              │
unity-mcp-cli create-project ./MyUnityProject              #  │ codex              │
                                                           #  │ cursor             │
2. Install "AI Game Developer" in Unity project          #  │ gemini             │
unity-mcp-cli install-plugin ./MyUnityProject              #  │ github-copilot-cli │
                                                           #  │ kilo-code          │
3. Sign in to ai-game.dev (OAuth device flow)            #  │ open-code          │
unity-mcp-cli login                                        #  │ rider-junie        │
                                                           #  │ unity-ai           │
4. Open Unity project (auto-connects and generates skills)  │ vs-copilot         │
unity-mcp-cli open ./MyUnityProject                        #  │ vscode-copilot     │
                                                           #  └────────────────────┘
5. Wait for Unity Editor to be ready
unity-mcp-cli wait-for-ready ./MyUnityProject

See full CLI documentation for all available commands.

Cloud sign-in & project pinning: unity-mcp-cli login runs the browser OAuth device flow and stores the credential in the shared machine store (~/.ai-game-dev/credentials.json) — there is no personal access token to paste. By default the AI-agent config that setup-mcp writes points at a per-project pinned endpoint (https://ai-game.dev/mcp/p/); pass --no-pin to use the shared https://ai-game.dev/mcp endpoint instead. Teams can distribute access with an enrollment code: unity-mcp-cli install-plugin --enroll .

Step 2: Install AI agent

Choose a single AI agent you prefer - you don't need to install all of them. This will be your main chat window to communicate with the LLM.

• Claude Code (recommended)
• Claude Desktop
• GitHub Copilot in VS Code
• Antigravity
• Cursor
• Windsurf
• Any other supported

The AI Game Developer is quite universal, which is why you may use any AI agent you prefer - it will work as smoothly as any other. The only important requirement is that the AI agent must support Skills or dynamic MCP Tool updates.

Step 3: Configure AI agent

Automatic configuration

• Open Unity project
• Open Window/AI Game Developer
• Option 1: Click Auto-generate Skills (recommended)
• Option 2: Click Configure Model Context Protocol (MCP)

If your MCP client is not in the list, use the raw JSON shown in the window to inject it into your MCP client. Read the instructions for your specific MCP client on how to do this.

Manual configuration

If automatic configuration doesn't work for you for any reason, use the JSON from the AI Game Developer (Unity-MCP) window to configure