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:
- Install plugin — download the
.unitypackageinstaller or runopenupm add com.ivanmurzak.unity.mcpAlternative:
npx unity-mcp-cli install-plugin ./MyUnityProject— see CLI documentation - Pick an AI agent — Claude Code, Claude Desktop, GitHub Copilot, Cursor, or any other
- Setup AI agent — open
Window/AI Game Developerin 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
assets-copy- Copy the asset at path and stores it at newPathassets-create-folder- Creates a new folder in the specified parent folderassets-delete- Delete the assets at paths from the projectassets-find- Search the asset database using the search filter stringassets-find-built-in- Search the built-in assets of the Unity Editorassets-get-data- Get asset data from the asset file including all serializable fields and propertiesassets-material-create- Create new material asset with default parametersassets-modify- Modify asset file in the projectassets-move- Move the assets at paths in the project (also used for rename)assets-prefab-close- Close currently opened prefabassets-prefab-create- Create a prefab from a GameObject in the current active sceneassets-prefab-instantiate- Instantiates prefab in the current active sceneassets-prefab-open- Open prefab edit mode for a specific GameObjectassets-prefab-save- Save a prefab in prefab editing modeassets-refresh- Refreshes the AssetDatabaseassets-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 packagespackage-add- Install a package from the Unity Package Manager registry, Git URL, or local pathpackage-list- List all packages installed in the Unity project (UPM packages)package-remove- Remove (uninstall) a package from the Unity projectpackage-search- Search for packages in both Unity Package Manager registry and installed packages
gameobject-component-add- Add Component to GameObjectgameobject-component-destroy- Destroy one or many components from target GameObjectgameobject-component-get- Get detailed information about a specific Component on a GameObjectgameobject-component-list-all- List C# class names extended from UnityEngine.Componentgameobject-component-modify- Modify a specific Component on a GameObjectgameobject-create- Create a new GameObject in opened Prefab or in a Scenegameobject-destroy- Destroy GameObject and all nested GameObjects recursivelygameobject-duplicate- Duplicate GameObjects in opened Prefab or in a Scenegameobject-find- Finds specific GameObject by provided informationgameobject-modify- Modify GameObjects and/or attached component's fields and propertiesgameobject-set-parent- Set parent GameObject to list of GameObjectsobject-get-data- Get data of the specified Unity Objectobject-modify- Modify the specified Unity Objectscene-create- Create new scene in the project assetsscene-get-data- Retrieves the list of root GameObjects in the specified scenescene-list-opened- Returns the list of currently opened scenes in Unity Editorscene-open- Open scene from the project asset filescene-save- Save opened scene to the asset filescene-set-active- Set the specified opened scene as the active scenescene-unload- Unload scene from the opened scenes in Unity Editorscreenshot-camera- Captures a screenshot from a camera and returns it as an imagescreenshot-game-view- Captures a screenshot from the Unity Editor Game Viewscreenshot-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
console-clear-logs- Clears the MCP log cache and the Unity Editor Console windowconsole-get-logs- Retrieves Unity Editor logs with filtering optionseditor-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 Editoreditor-selection-set- Set the current Selection in the Unity Editorreflection-method-call- Call any C# method with input parameters and return resultsreflection-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 Roslynscript-read- Reads the content of a script filescript-update-or-create- Updates or creates script file with the provided C# codetests-run- Execute Unity tests (EditMode/PlayMode) with filtering and detailed resultstype-get-json-schema- Generate a JSON Schema for a C# type via reflection
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 Profilerprofiler-enable-module- Toggle the local enabled flag for a named profiler moduleprofiler-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 typeprofiler-get-script-stats- Return script execution timing plus Mono / GC memory usageprofiler-get-status- Return the profiler's enabled state, active modules, and platform supportprofiler-list-modules- List all known profiler module names with their enabled flagprofiler-load-data- Read back a previously-saved profiler JSON snapshotprofiler-save-data- Save a snapshot of profiler-derived stats to a JSON fileprofiler-start- Enable Unity's runtime profiler and open the Profiler windowprofiler-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
- Contents
- Installation
- AI Workflow Examples
- Customize Tools
- Runtime usage (in-game)
- Unity
MCP Serversetup - How Unity MCP Architecture Works
- 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
[!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 loginruns 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 thatsetup-mcpwrites points at a per-project pinned endpoint (https://ai-game.dev/mcp/p/<pin>); pass--no-pinto use the sharedhttps://ai-game.dev/mcpendpoint instead. Teams can distribute access with an enrollment code:unity-mcp-cli install-plugin --enroll <code>.
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-generateSkills (recommended) - Option 2: Click
ConfigureModel 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 any MCP Client manually.
Command line configuration
1. Choose your <command> for your environment
| Platform | <command> |
|---|---|
| Windows x64 | "<unityProjectPath>/Library/mcp-server/win-x64/gamedev-mcp-server.exe" port=<port> client-transport=stdio |
| Windows x86 | "<unityProjectPath>/Library/mcp-server/win-x86/gamedev-mcp-server.exe" port=<port> client-transport=stdio |
| Windows arm64 | "<unityProjectPath>/Library/mcp-server/win-arm64/gamedev-mcp-server.exe" port=<port> client-transport=stdio |
| MacOS Apple-Silicon | "<unityProjectPath>/Library/mcp-server/osx-arm64/gamedev-mcp-server" port=<port> client-transport=stdio |
| MacOS Apple-Intel | "<unityProjectPath>/Library/mcp-server/osx-x64/gamedev-mcp-server" port=<port> client-transport=stdio |
| Linux x64 | "<unityProjectPath>/Library/mcp-server/linux-x64/gamedev-mcp-server" port=<port> client-transport=stdio |
| Linux arm64 | "<unityProjectPath>/Library/mcp-server/linux-arm64/gamedev-mcp-server" port=<port> client-transport=stdio |
2. Replace <unityProjectPath> with the full path to Unity project
3. Replace <port> with your port from AI Game Developer configuration
4. Add MCP server using command line
gemini mcp add ai-game-developer <command>
Replace
<command>from the table above
claude mcp add ai-game-developer <command>
Replace
<command>from the table above
copilot
/mcp add
Server name: ai-game-developer
Server type: local
Command: <command>
Replace
<command>from the table above
AI Workflow Examples
Communicate with the AI (LLM) in your AI agent. Ask it to do anything you want. The better you describe your task or idea, the better it will perform the job.
Some AI agents allow you to choose different LLM models. Pay attention to this feature, as some models may work much better than others.
Example prompts:
Explain my scene hierarchy
Create 3 spheres on top of each other
Create metallic golden material and attach it to a new sphere gameObject
Make sure
Agentmode is enabled if using VS Code with Copilot
Disabling update notifications for the whole team
The plugin shows an update popup at Editor startup when a newer version is available on OpenUPM. By default, each team member sees this popup until they individually click "Do not show again" (which is a per-user setting stored on their machine).
For multi-person Unity projects where one engineer owns plugin versioning, you can disable the popup for the entire team by opening Edit ▸ Project Settings ▸ AI Game Developer and enabling "Disable update notifications for the entire team". The setting is persisted to ProjectSettings/AI-Game-Developer-UpdateSettings.asset and only needs to be set once per project — commit that file and every team member who pulls the commit will have the popup suppressed.
The same toggle is also reachable via Tools ▸ AI Game Developer ▸ Updates ▸ Disable Update Notifications (Team) in the menu bar.
Advanced Features for LLM
Unity MCP provides advanced tools that enable the LLM to work faster and more effectively, avoiding mistakes and self-correcting when errors occur. Everything is designed to achieve your goals efficiently.
Core Capabilities
- ✔️ Agent-ready tools - Find anything you need in 1-2 steps
- ✔️ Instant compilation - C# code compilation & execution using
Roslynfor faster iteration - ✔️ Full asset access - Read/write access to assets and C# scripts
- ✔️ Intelligent feedback - Well-described positive and negative feedback for proper issue understanding
Reflection-Powered Features
- ✔️ Object references - Provide references to existing objects for instant C# code
- ✔️ Project data access - Get full access to entire project data in a readable format
- ✔️ Granular modifications - Populate & modify any piece of data in the project
- ✔️ Method discovery - Find any method in the entire codebase, including compiled DLL files
- ✔️ Method execution - Call any method in the entire codebase
- ✔️ Advanced parameters - Provide any property for method calls, even references to existing objects in memory
- ✔️ Live Unity API - Unity API instantly available - even when Unity changes, you get the fresh API
- ✔️ Self-documenting - Access human-readable descriptions of any
class,method, orpropertyviaDescriptionattributes
Customize Tools
Unity MCP supports custom MCP Tool, MCP Resource, and MCP Prompt development by project owners. The MCP server takes data from the Unity MCP Plugin and exposes it to a client. Anyone in the MCP communication chain will receive information about new MCP features, which the LLM may decide to use at some point.
Add custom Tool
To add a custom Tool, you need:
- A class with the
AiToolTypeattribute - A method in the class with the
AiToolattribute - Optional: Add a
Descriptionattribute to each method argument to help the LLM understand it - Optional: Use
string? optional = nullproperties with?and default values to mark them asoptionalfor the LLM
Note that the line
MainThread.Instance.Run(() =>allows you to run code on the main thread, which is required for interacting with Unity's API. If you don't need this and running the tool in a background thread is acceptable, avoid using the main thread for efficiency purposes.
[AiToolType]
public class Tool_GameObject
{
[AiTool
(
"MyCustomTask",
Title = "Create a new GameObject"
)]
[Description("Explain here to LLM what is this, when it should be called.")]
public string CustomTask
(
[Description("Explain to LLM what is this.")]
string inputData
)
{
// do anything in background thread
return MainThread.Instance.Run(() =>
{
// do something in main thread if needed
return $"[Success] Operation completed.";
});
}
}
Add custom MCP Prompt
MCP Prompt allows you to inject custom prompts into the conversation with the LLM. It supports two sender roles: User and Assistant. This is a quick way to instruct the LLM to perform specific tasks. You can generate prompts using custom data, providing lists or any other relevant information.
[AiPromptType]
public static class Prompt_ScriptingCode
{
[AiPrompt(Name = "add-event-system", Role = Role.User)]
[Description("Implement UnityEvent-based communication system between GameObjects.")]
public string AddEventSystem()
{
return "Create event system using UnityEvents, UnityActions, or custom event delegates for decoupled communication between game systems and components.";
}
}
Runtime usage (in-game)
Use Unity MCP in your game/app. Use Tools, Resources or Prompts. By default there are no tools, you would need to implement your custom.
// Build MCP plugin
var mcpPlugin = UnityMcpPluginRuntime.Initialize(builder =>
{
builder.WithConfig(config =>
{
config.Host = "http://localhost:8080";
config.Token = "your-token";
});
// Automatically register all tools from the current assembly
builder.WithToolsFromAssembly(Assembly.GetExecutingAssembly());
})
.Build();
await mcpPlugin.Connect(); // Start active connection with retry to the MCP server
await mcpPlugin.Disconnect(); // Stop active connection and close existed connection
Sample: AI powered Chess game bot
There is a classic Chess game. Lets outsource to LLM the bot logic. Bot should do the turn using game rules.
[AiToolType]
public static class ChessGameAI
{
[AiTool("chess-do-turn", Title = "Do the turn")]
[Description("Do the turn in the chess game. Returns true if the turn was accepted, false otherwise.")]
public static Task<bool> DoTurn(int figureId, Vector2Int position)
{
return MainThread.Instance.RunAsync(() => ChessGameController.Instance.DoTurn(figureId, position));
}
[AiTool("chess-get-board", Title = "Get the board")]
[Description("Get the current state of the chess board.")]
public static Task<BoardData> GetBoard()
{
return MainThread.Instance.RunAsync(() => ChessGameController.Instance.GetBoardData());
}
}
Why runtime usage is needed?
There are many use cases, lets imagine you are working on a Chess game with bot. You may outsource the bot decision making to LLM by writing few lines of code.
Unity MCP Server setup
Unity MCP Server supports many different launch options and Docker deployment. Both transport protocols are supported: streamableHttp and stdio. If you need to customize or deploy Unity MCP Server to a cloud, this section is for you. Read more...
Variables
Doesn't matter what launch option you choose, all of them support custom configuration using both Environment Variables and Command Line Arguments. It would work with default values, if you just need to launch it, don't waste your time for the variables. Just make sure Unity Plugin also has default values, especially the --port, they should be equal.
| Environment Variable | Command Line Args | Description |
|---|---|---|
MCP_PLUGIN_PORT |
--port |
Client -> Server <- Plugin connection port (default: 8080) |
MCP_PLUGIN_CLIENT_TIMEOUT |
--plugin-timeout |
Plugin -> Server connection timeout (ms) (default: 10000) |
MCP_PLUGIN_CLIENT_TRANSPORT |
--client-transport |
Client -> Server transport type: stdio or streamableHttp (default: streamableHttp) |
MCP_AUTHORIZATION |
--authorization |
Authentication mode for incoming Client connections: none, oauth, or token (default: none; the legacy required mode was removed) |
MCP_PLUGIN_TOKEN |
--token |
Bearer token required from the Client when authorization is token (default: unset) |
MCP_PLUGIN_IDLE_TIMEOUT_SECONDS |
--idle-timeout-seconds |
Shut down the server after this many seconds with no connections (default: 600) |
Command line args support also the option with a single
-prefix (-port) and an option without prefix at all (port).
For analytics and authorization webhook variables (
MCP_PLUGIN_WEBHOOK_*), see docs/mcp-server.md.
Choosing a transport: Use
stdiowhen the MCP client launches the server binary directly (local use — this is the most common setup). UsestreamableHttpwhen running the server as a standalone process or in Docker/cloud, and connecting over HTTP.
Plugin Variables
The Unity MCP Plugin reads the following environment variables (and command-line arguments) on startup to override values from the saved config file. Overrides are applied at runtime; on first run or when a new authentication token is generated, the overridden values are written to the config file. On subsequent runs, overrides are applied in memory but are not automatically saved. The exception is UNITY_MCP_TOOLS, which uses [JsonIgnore] and is never persisted — it is runtime-only.
| Environment Variable | Command Line Arg | Values | Description |
|---|---|---|---|
UNITY_MCP_CLOUD_URL |
-url |
URL string | Override the MCP Server URL (UNITY_MCP_HOST is a legacy alias) |
UNITY_MCP_CONNECTION_MODE |
-UNITY_MCP_CONNECTION_MODE |
Cloud / Custom |
Force the connection mode (a loopback URL implies Custom) |
UNITY_MCP_KEEP_CONNECTED |
-UNITY_MCP_KEEP_CONNECTED |
true / false |
Force enable or disable the active connection |
UNITY_MCP_AUTH_OPTION |
-auth |
none / oauth / token |
Force set the authentication mode (legacy required migrates to token) |
UNITY_MCP_TOKEN |
-token |
string | Force set the authentication token |
UNITY_MCP_TRANSPORT |
-UNITY_MCP_TRANSPORT |
stdio / streamableHttp |
Force the client transport the plugin configures |
UNITY_MCP_START_SERVER |
-UNITY_MCP_START_SERVER |
true / false |
Force whether the plugin keeps a local server process running |
UNITY_MCP_TOOLS |
-UNITY_MCP_TOOLS |
comma-separated tool IDs | Enable only the listed tools; all others are disabled. Unknown IDs are logged as errors. |
Command-line args take precedence over environment variables. Both override the saved config file value. The short flags
-url,-token, and-authare aliases; the full-UNITY_MCP_*arg names are also accepted.
Example (CI/CD batch mode):
Unity.exe -batchmode -nographics \
-UNITY_MCP_CLOUD_URL=http://localhost:8080 \
-UNITY_MCP_KEEP_CONNECTED=true \
-UNITY_MCP_AUTH_OPTION=token \
-UNITY_MCP_TOKEN=my-secret-token
Docker 📦
Make sure Docker
No comments yet
Be the first to share your take.