✨ AI Game Developer — Unity MCP 中文 | 日本語 | Español 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. - ✔️ Runtime AI - Use LL
Add this skill
npx mdskills install IvanMurzak/unity-mcpComprehensive Unity MCP server enabling AI agents to control Unity Editor and runtime with extensive tool coverage
1<div align="center" width="100%">2 <h1>✨ AI Game Developer — <i>Unity MCP</i></h1>34[](https://modelcontextprotocol.io/introduction)5[](https://openupm.com/packages/com.ivanmurzak.unity.mcp/)6[](https://hub.docker.com/r/ivanmurzakdev/unity-mcp-server)7[](https://unity.com/releases/editor/archive)8[](https://unity.com/releases/editor/archive)9[](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml)</br>10[](https://discord.gg/cfbdMZX99G)11[](https://openupm.com/packages/com.ivanmurzak.unity.mcp/)12[](https://github.com/IvanMurzak/Unity-MCP/stargazers)13[](https://github.com/IvanMurzak/Unity-MCP/blob/main/LICENSE)14[](https://stand-with-ukraine.pp.ua)1516 <img src="https://github.com/IvanMurzak/Unity-MCP/raw/main/docs/img/promo/ai-developer-banner.jpg" alt="AI work" title="Level building" width="100%">1718 <b>[中文](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/README.zh-CN.md) | [日本語](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/README.ja.md) | [Español](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/README.es.md)</b>1920</div>2122`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**.2324Unlike other tools, this plugin works **inside your compiled game**, allowing for real-time AI debugging and player-AI interaction.2526> **[💬 Join our Discord Server](https://discord.gg/cfbdMZX99G)** - Ask questions, showcase your work, and connect with other developers!2728## Features2930- ✔️ **Runtime AI** - Use LLMs directly inside your compiled game for dynamic NPC behavior or debugging31- ✔️ **Natural conversation** - Chat with AI like you would with a human32- ✔️ **Code assistance** - Ask AI to write code and run tests33- ✔️ **Debug support** - Ask AI to get logs and fix errors34- ✔️ **Multiple LLM providers** - Use agents from **Anthropic**, **OpenAI**, **DeepSeek**, Microsoft, or any other provider with no limits35- ✔️ **Flexible deployment** - Works locally (stdio) and remotely (http) by configuration36- ✔️ **Rich toolset** - Wide range of default [MCP Tools](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/default-mcp-tools.md)37- ✔️ **Extensible** - Create [custom MCP Tools in your project code](#add-custom-mcp-tool)3839[](https://github.com/IvanMurzak/Unity-MCP/releases/download/0.48.1/AI-Game-Dev-Installer.unitypackage)40414243### Tools4445<details>46 <summary>Assets</summary>4748- `copy` - Copy the asset at path and stores it at newPath49- `create-folder` - Creates a new folder in the specified parent folder50- `delete` - Delete the assets at paths from the project51- `find` - Search the asset database using the search filter string52- `get-data` - Get asset data from the asset file including all serializable fields and properties53- `modify` - Modify asset file in the project54- `move` - Move the assets at paths in the project (also used for rename)55- `refresh` - Refreshes the AssetDatabase5657</details>5859<details>60 <summary>Assets / Material</summary>6162- `create` - Create new material asset with default parameters6364</details>6566<details>67 <summary>Assets / Shader</summary>6869- `list-all` - List all available shaders in the project assets and packages7071</details>7273<details>74 <summary>Assets / Prefab</summary>7576- `create` - Create a prefab from a GameObject in the current active scene77- `instantiate` - Instantiates prefab in the current active scene78- `open` - Open prefab edit mode for a specific GameObject79- `close` - Close currently opened prefab80- `save` - Save a prefab in prefab editing mode8182</details>8384<details>85 <summary>GameObject</summary>8687- `create` - Create a new GameObject in opened Prefab or in a Scene88- `destroy` - Destroy GameObject and all nested GameObjects recursively89- `duplicate` - Duplicate GameObjects in opened Prefab or in a Scene90- `find` - Finds specific GameObject by provided information91- `modify` - Modify GameObjects and/or attached component's fields and properties92- `set-parent` - Set parent GameObject to list of GameObjects9394</details>9596<details>97 <summary>GameObject / Component</summary>9899- `add` - Add Component to GameObject100- `destroy` - Destroy one or many components from target GameObject101- `get` - Get detailed information about a specific Component on a GameObject102- `modify` - Modify a specific Component on a GameObject103104</details>105106<details>107 <summary>Component</summary>108109- `list` - List C# class names extended from UnityEngine.Component110111</details>112113<details>114 <summary>Scene</summary>115116- `create` - Create new scene in the project assets117- `get-data` - Retrieves the list of root GameObjects in the specified scene118- `list-opened` - Returns the list of currently opened scenes in Unity Editor119- `open` - Open scene from the project asset file120- `save` - Save opened scene to the asset file121- `set-active` - Set the specified opened scene as the active scene122- `unload` - Unload scene from the opened scenes in Unity Editor123124</details>125126<details>127 <summary>Script</summary>128129- `delete` - Delete the script file(s)130- `execute` - Compiles and executes C# code dynamically using Roslyn131- `read` - Reads the content of a script file132- `update-or-create` - Updates or creates script file with the provided C# code133134</details>135136<details>137 <summary>Console</summary>138139- `get-logs` - Retrieves Unity Editor logs with filtering options140141</details>142143<details>144 <summary>Editor / Application</summary>145146- `get-state` - Returns information about the Unity Editor application state (playmode, paused, compilation)147- `set-state` - Control the Unity Editor application state (start/stop/pause playmode)148149</details>150151<details>152 <summary>Editor / Selection</summary>153154- `get` - Get information about the current Selection in the Unity Editor155- `set` - Set the current Selection in the Unity Editor156157</details>158159<details>160 <summary>Reflection</summary>161162- `method-find` - Find method in the project using C# Reflection (even private methods)163- `method-call` - Call any C# method with input parameters and return results164165</details>166167<details>168 <summary>Tests</summary>169170- `run` - Execute Unity tests (EditMode/PlayMode) with filtering and detailed results171172</details>173174<details>175 <summary>Package Manager</summary>176177- `add` - Install a package from the Unity Package Manager registry, Git URL, or local path178- `remove` - Remove (uninstall) a package from the Unity project179- `list` - List all packages installed in the Unity project (UPM packages)180- `search` - Search for packages in both Unity Package Manager registry and installed packages181182</details>183184#### Additional tools185186- [Animation](https://github.com/IvanMurzak/Unity-AI-Animation/)187- [ParticleSystem](https://github.com/IvanMurzak/Unity-AI-ParticleSystem/)188- [ProBuilder](https://github.com/IvanMurzak/Unity-AI-ProBuilder/)189190### Stability status191192| Unity Version | Editmode | Playmode | Standalone |193| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |194| 2022.3.62f3 | [](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml) | [](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml) | [](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml) |195| 2023.2.22f1 | [](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml) | [](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml) | [](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml) |196| 6000.3.1f1 | [](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml) | [](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml) | [](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml) |197198## Content199200- [Installation](#installation)201 - [Step 1: Install `Unity MCP Plugin`](#step-1-install-unity-mcp-plugin)202 - [Option 1 - Installer](#option-1---installer)203 - [Option 2 - OpenUPM-CLI](#option-2---openupm-cli)204 - [Step 2: Install `MCP Client`](#step-2-install-mcp-client)205 - [Step 3: Configure `MCP Client`](#step-3-configure-mcp-client)206 - [Automatic configuration](#automatic-configuration)207 - [Manual configuration](#manual-configuration)208 - [Command line configuration](#command-line-configuration)209- [AI Workflow Examples: Claude \& Gemini](#ai-workflow-examples-claude--gemini)210 - [Advanced Features for LLM](#advanced-features-for-llm)211 - [Core Capabilities](#core-capabilities)212 - [Reflection-Powered Features](#reflection-powered-features)213- [Customize MCP](#customize-mcp)214 - [Add custom `MCP Tool`](#add-custom-mcp-tool)215 - [Add custom `MCP Prompt`](#add-custom-mcp-prompt)216- [Runtime usage (in-game)](#runtime-usage-in-game)217 - [Sample: AI powered Chess game bot](#sample-ai-powered-chess-game-bot)218 - [Why runtime usage is needed?](#why-runtime-usage-is-needed)219- [Unity `MCP Server` setup](#unity-mcp-server-setup)220 - [Variables](#variables)221 - [Docker 📦](#docker-)222 - [`streamableHttp` Transport](#streamablehttp-transport)223 - [`stdio` Transport](#stdio-transport)224 - [Custom `port`](#custom-port)225 - [Binary executable](#binary-executable)226- [How Unity MCP Architecture Works](#how-unity-mcp-architecture-works)227 - [What is `MCP`](#what-is-mcp)228 - [What is `MCP Client`](#what-is-mcp-client)229 - [What is `MCP Server`](#what-is-mcp-server)230 - [What is `MCP Tool`](#what-is-mcp-tool)231 - [When to use `MCP Tool`](#when-to-use-mcp-tool)232 - [What is `MCP Resource`](#what-is-mcp-resource)233 - [When to use `MCP Resource`](#when-to-use-mcp-resource)234 - [What is `MCP Prompt`](#what-is-mcp-prompt)235 - [When to use `MCP Prompt`](#when-to-use-mcp-prompt)236- [Contribution 💙💛](#contribution-)237238# Installation239240## Step 1: Install `Unity MCP Plugin`241242<details>243 <summary><b>⚠️ Requirements (click)</b></summary>244245> [!IMPORTANT]246> **Project path cannot contain spaces**247>248> - ✅ `C:/MyProjects/Project`249> - ❌ `C:/My Projects/Project`250251</details>252253### Option 1 - Installer254255- **[⬇️ Download Installer](https://github.com/IvanMurzak/Unity-MCP/releases/download/0.48.1/AI-Game-Dev-Installer.unitypackage)**256- **📂 Import installer into Unity project**257 > - You can double-click on the file - Unity will open it automatically258 > - OR: Open Unity Editor first, then click on `Assets/Import Package/Custom Package`, and choose the file259260### Option 2 - OpenUPM-CLI261262- [⬇️ Install OpenUPM-CLI](https://github.com/openupm/openupm-cli#installation)263- 📟 Open the command line in your Unity project folder264265```bash266openupm add com.ivanmurzak.unity.mcp267```268269## Step 2: Install `MCP Client`270271Choose a single `MCP Client` you prefer - you don't need to install all of them. This will be your main chat window to communicate with the LLM.272273- [Claude Code](https://github.com/anthropics/claude-code) (highly recommended)274- [Claude Desktop](https://claude.ai/download)275- [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview)276- [Antigravity](https://antigravity.google/)277- [Cursor](https://www.cursor.com/)278- [Windsurf](https://windsurf.com)279- Any other supported280281> The MCP protocol is quite universal, which is why you may use any MCP client you prefer - it will work as smoothly as any other. The only important requirement is that the MCP client must support dynamic MCP Tool updates.282283## Step 3: Configure `MCP Client`284285### Automatic configuration286287- Open Unity project288- Open `Window/AI Game Developer (Unity-MCP)`289- Click `Configure` at your MCP client290291292293> 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.294295### Manual configuration296297If 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.298299#### Command line configuration300301<details>302 <summary><b>Create <code>command</code></b></summary>303304**1. Choose your `<command>` for your environment**305306| Platform | `<command>` |307| ------------------- | ----------------------------------------------------------------------------------------------------------- |308| Windows x64 | `"<unityProjectPath>/Library/mcp-server/win-x64/unity-mcp-server.exe" port=<port> client-transport=stdio` |309| Windows x86 | `"<unityProjectPath>/Library/mcp-server/win-x86/unity-mcp-server.exe" port=<port> client-transport=stdio` |310| Windows arm64 | `"<unityProjectPath>/Library/mcp-server/win-arm64/unity-mcp-server.exe" port=<port> client-transport=stdio` |311| MacOS Apple-Silicon | `"<unityProjectPath>/Library/mcp-server/osx-arm64/unity-mcp-server" port=<port> client-transport=stdio` |312| MacOS Apple-Intel | `"<unityProjectPath>/Library/mcp-server/osx-x64/unity-mcp-server" port=<port> client-transport=stdio` |313| Linux x64 | `"<unityProjectPath>/Library/mcp-server/linux-x64/unity-mcp-server" port=<port> client-transport=stdio` |314| Linux arm64 | `"<unityProjectPath>/Library/mcp-server/linux-arm64/unity-mcp-server" port=<port> client-transport=stdio` |315316**2. Replace `<unityProjectPath>` with the full path to Unity project**317318**3. Replace `<port>` with your port from AI Game Developer configuration**319320**4. Add MCP server using command line**321322</details>323324<details>325 <summary><img src="https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/mcp-clients/gemini-64.png?raw=true" width="16" height="16" alt="Gemini CLI"> Gemini CLI</summary>326327 ```bash328 gemini mcp add ai-game-developer <command>329 ```330 > Replace `<command>` from the table above331</details>332333<details>334 <summary><img src="https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/mcp-clients/claude-64.png?raw=true" width="16" height="16" alt="Claude Code CLI"> Claude Code CLI</summary>335336 ```bash337 claude mcp add ai-game-developer <command>338 ```339 > Replace `<command>` from the table above340</details>341342<details>343 <summary><img src="https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/mcp-clients/github-copilot-64.png?raw=true" width="16" height="16" alt="GitHub Copilot CLI"> GitHub Copilot CLI</summary>344345 ```bash346 copilot347 ```348349 ```bash350 /mcp add351 ```352353 Server name: `ai-game-developer`354 Server type: `local`355 Command: `<command>`356 > Replace `<command>` from the table above357</details>358359---360361# AI Workflow Examples: Claude & Gemini362363Communicate with the AI (LLM) in your `MCP Client`. Ask it to do anything you want. The better you describe your task or idea, the better it will perform the job.364365Some `MCP Clients` allow you to choose different LLM models. Pay attention to this feature, as some models may work much better than others.366367**Example commands:**368369```text370Explain my scene hierarchy371```372373```text374Create 3 cubes in a circle with radius 2375```376377```text378Create metallic golden material and attach it to a sphere gameObject379```380381> Make sure `Agent` mode is turned on in your MCP client382383## Advanced Features for LLM384385Unity 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.386387### Core Capabilities388389- ✔️ **Agent-ready tools** - Find anything you need in 1-2 steps390- ✔️ **Instant compilation** - C# code compilation & execution using `Roslyn` for faster iteration391- ✔️ **Full asset access** - Read/write access to assets and C# scripts392- ✔️ **Intelligent feedback** - Well-described positive and negative feedback for proper issue understanding393394### Reflection-Powered Features395396- ✔️ **Object references** - Provide references to existing objects for instant C# code397- ✔️ **Project data access** - Get full access to entire project data in a readable format398- ✔️ **Granular modifications** - Populate & modify any piece of data in the project399- ✔️ **Method discovery** - Find any method in the entire codebase, including compiled DLL files400- ✔️ **Method execution** - Call any method in the entire codebase401- ✔️ **Advanced parameters** - Provide any property for method calls, even references to existing objects in memory402- ✔️ **Live Unity API** - Unity API instantly available - even when Unity changes, you get the fresh API403- ✔️ **Self-documenting** - Access human-readable descriptions of any `class`, `method`, or `property` via `Description` attributes404405---406407# Customize MCP408409**[Unity MCP](https://github.com/IvanMurzak/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.410411## Add custom `MCP Tool`412413To add a custom `MCP Tool`, you need:4144151. A class with the `McpPluginToolType` attribute4162. A method in the class with the `McpPluginTool` attribute4173. *Optional:* Add a `Description` attribute to each method argument to help the LLM understand it4184. *Optional:* Use `string? optional = null` properties with `?` and default values to mark them as `optional` for the LLM419420> 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.421422```csharp423[McpPluginToolType]424public class Tool_GameObject425{426 [McpPluginTool427 (428 "MyCustomTask",429 Title = "Create a new GameObject"430 )]431 [Description("Explain here to LLM what is this, when it should be called.")]432 public string CustomTask433 (434 [Description("Explain to LLM what is this.")]435 string inputData436 )437 {438 // do anything in background thread439440 return MainThread.Instance.Run(() =>441 {442 // do something in main thread if needed443444 return $"[Success] Operation completed.";445 });446 }447}448```449450## Add custom `MCP Prompt`451452`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.453454```csharp455[McpPluginPromptType]456public static class Prompt_ScriptingCode457{458 [McpPluginPrompt(Name = "add-event-system", Role = Role.User)]459 [Description("Implement UnityEvent-based communication system between GameObjects.")]460 public string AddEventSystem()461 {462 return "Create event system using UnityEvents, UnityActions, or custom event delegates for decoupled communication between game systems and components.";463 }464}465```466467---468469# Runtime usage (in-game)470471Use **[Unity MCP](https://github.com/IvanMurzak/Unity-MCP)** in your game/app. Use Tools, Resources or Prompts. By default there are no tools, you would need to implement your custom.472473```csharp474UnityMcpPlugin.BuildAndStart(); // Build and start Unity-MCP-Plugin, it is required475UnityMcpPlugin.Connect(); // Start active connection with retry to Unity-MCP-Server476UnityMcpPlugin.Disconnect(); // Stop active connection and close existed connection477```478479## Sample: AI powered Chess game bot480481There is a classic Chess game. Lets outsource to LLM the bot logic. Bot should do the turn using game rules.482483```csharp484[McpPluginToolType]485public static class ChessGameAI486{487 [McpPluginTool("chess-do-turn", Title = "Do the turn")]488 [Description("Do the turn in the chess game. Returns true if the turn was accepted, false otherwise.")]489 public static Task<bool> DoTurn(int figureId, Vector2Int position)490 {491 return MainThread.Instance.RunAsync(() => ChessGameController.Instance.DoTurn(figureId, position));492 }493494 [McpPluginTool("chess-get-board", Title = "Get the board")]495 [Description("Get the current state of the chess board.")]496 public static Task<BoardData> GetBoard()497 {498 return MainThread.Instance.RunAsync(() => ChessGameController.Instance.GetBoardData());499 }500}501```502503## Why runtime usage is needed?504505There 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.506507---508509# Unity `MCP Server` setup510511**[Unity MCP](https://github.com/IvanMurzak/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...](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/mcp-server.md)512513## Variables514515Doesn'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.516517| Environment Variable | Command Line Args | Description |518| ---------------------------- | -------------------- | ---------------------------------------------------------------------------- |519| `MCP_PLUGIN_PORT` | `--port` | **Client** -> **Server** <- **Plugin** connection port (default: 8080) |520| `MCP_PLUGIN_CLIENT_TIMEOUT` | `--plugin-timeout` | **Plugin** -> **Server** connection timeout (ms) (default: 10000) |521| `MCP_PLUGIN_CLIENT_TRANSPORT` | `--client-transport` | **Client** -> **Server** transport type: `stdio` or `streamableHttp` (default: `streamableHttp`) |522523> Command line args support also the option with a single `-` prefix (`-port`) and an option without prefix at all (`port`).524525## Docker 📦526527[](https://hub.docker.com/r/ivanmurzakdev/unity-mcp-server)528529Make sure Docker is installed. And please make sure Docker Desktop is launched if you are at Windows operation system.530531### `streamableHttp` Transport532533```bash534docker run -p 8080:8080 ivanmurzakdev/unity-mcp-server535```536537<details>538 <summary><code>MCP Client</code> config:</summary>539540```json541{542 "mcpServers": {543 "ai-game-developer": {544 "url": "http://localhost:8080"545 }546 }547}548```549550> Replace `url` with your real endpoint if it is hosted in cloud.551552</details>553554### `stdio` Transport555556For using this variant, `MCP Client` should launch the `MCP Server` in the docker. It is achievable through the modified `MCP Client` configuration.557558```bash559docker run -t -e MCP_PLUGIN_CLIENT_TRANSPORT=stdio -p 8080:8080 ivanmurzakdev/unity-mcp-server560```561562<details>563 <summary><code>MCP Client</code> config:</summary>564565```json566{567 "mcpServers": {568 "ai-game-developer": {569 "command": "docker",570 "args": [571 "run",572 "-t",573 "-e",574 "MCP_PLUGIN_CLIENT_TRANSPORT=stdio",575 "-p",576 "8080:8080",577 "ivanmurzakdev/unity-mcp-server"578 ]579 }580 }581}582```583584</details>585586### Custom `port`587588```bash589docker run -e MCP_PLUGIN_PORT=123 -p 123:123 ivanmurzakdev/unity-mcp-server590```591592<details>593 <summary><code>MCP Client</code> config:</summary>594595```json596{597 "mcpServers": {598 "ai-game-developer": {599 "url": "http://localhost:123"600 }601 }602}603```604605> Replace `url` with your real endpoint if it is hosted in cloud606</details>607608## Binary executable609610You may launch Unity `MCP Server` directly from a binary file. You would need to have a binary compiled specifically for your CPU architecture. Check [GitHub Release Page](https://github.com/IvanMurzak/Unity-MCP/releases), it contains pre-compiled binaries for all CPU architectures.611612```bash613./unity-mcp-server --port 8080 --plugin-timeout 10000 --client-transport stdio614```615616<details>617 <summary><code>MCP Client</code> config:</summary>618619> Replace `<project>` with your Unity project path.620621```json622{623 "mcpServers": {624 "ai-game-developer": {625 "command": "<project>/Library/mcp-server/win-x64/unity-mcp-server.exe",626 "args": [627 "--port=8080",628 "--plugin-timeout=10000",629 "--client-transport=stdio"630 ]631 }632 }633}634```635636</details>637638---639640# How Unity MCP Architecture Works641642**[Unity MCP](https://github.com/IvanMurzak/Unity-MCP)** serves as a bridge between LLMs and Unity. It exposes and explains Unity's tools to the LLM, which then understands the interface and utilizes the tools according to user requests.643644Connect **[Unity MCP](https://github.com/IvanMurzak/Unity-MCP)** to LLM clients such as [Claude](https://claude.ai/download) or [Cursor](https://www.cursor.com/) using the integrated `AI Connector` window. Custom clients are also supported.645646The system is highly extensible - you can define custom `MCP Tools`, `MCP Resource` or `MCP Prompt` directly in your Unity project codebase, exposing new capabilities to AI or automation clients. This makes Unity MCP a flexible foundation for building advanced workflows, rapid prototyping, and integrating AI-driven features into your development process.647648## What is `MCP`649650MCP - Model Context Protocol. In a few words, that is `USB Type-C` for AI, specifically for LLM (Large Language Model). It teaches LLM how to use external features. Such as Unity Engine in this case, or even your custom C# method in your code. [Official documentation](https://modelcontextprotocol.io/).651652## What is `MCP Client`653654It is an application with a chat window. It may have smart agents to operate better, it may have embedded advanced MCP Tools. In general well done MCP Client is 50% of the AI success of executing a task. That is why it is very important to choose the best one for usage.655656## What is `MCP Server`657658It is a bridge between `MCP Client` and "something else", in this particular case it is Unity Engine. This project includes `MCP Server`.659660## What is `MCP Tool`661662`MCP Tool` is a function or method that the LLM can call to interact with Unity. These tools act as the bridge between natural language requests and actual Unity operations. When you ask the AI to "create a cube" or "change material color," it uses MCP Tools to execute these actions.663664**Key characteristics:**665666- **Executable functions** that perform specific operations667- **Typed parameters** with descriptions to help the LLM understand what data to provide668- **Return values** that give feedback about the operation's success or failure669- **Thread-aware** - can run on main thread for Unity API calls or background thread for heavy processing670671### When to use `MCP Tool`672673- **Automate repetitive tasks** - Create tools for common operations you do frequently674- **Complex operations** - Bundle multiple Unity API calls into a single, easy-to-use tool675- **Project-specific workflows** - Build tools that understand your project's specific structure and conventions676- **Error-prone tasks** - Create tools that include validation and error handling677- **Custom game logic** - Expose your game's systems to AI for dynamic content creation678679**Examples:**680681- Creating and configuring GameObjects with specific components682- Batch processing assets (textures, materials, prefabs)683- Setting up lighting and post-processing effects684- Generating level geometry or placing objects procedurally685- Configuring physics settings or collision layers686687## What is `MCP Resource`688689`MCP Resource` provides read-only access to data within your Unity project. Unlike MCP Tools that perform actions, Resources allow the LLM to inspect and understand your project's current state, assets, and configuration. Think of them as "sensors" that give the AI context about your project.690691**Key characteristics:**692693- **Read-only access** to project data and Unity objects694- **Structured information** presented in a format the LLM can understand695- **Real-time data** that reflects the current state of your project696- **Contextual awareness** helping the AI make informed decisions697698### When to use `MCP Resource`699700- **Project analysis** - Let AI understand your project structure, assets, and organization701- **Debugging assistance** - Provide current state information for troubleshooting702- **Intelligent suggestions** - Give AI context to make better recommendations703- **Documentation generation** - Automatically create documentation based on project state704- **Asset management** - Help AI understand what assets are available and their properties705706**Examples:**707708- Exposing scene hierarchy and GameObject properties709- Listing available materials, textures, and their settings710- Showing script dependencies and component relationships711- Displaying current lighting setup and render pipeline configuration712- Providing information about audio sources, animations, and particle systems713714## What is `MCP Prompt`715716`MCP Prompt` allows you to inject pre-defined prompts into the conversation with the LLM. These are smart templates that can provide context, instructions, or knowledge to guide the AI's behavior. Prompts can be static text or dynamically generated based on your project's current state.717718**Key characteristics:**719720- **Contextual guidance** that influences how the AI responds721- **Role-based** - can simulate different personas (User requests or Assistant knowledge)722- **Dynamic content** - can include real-time project data723- **Reusable templates** for common scenarios and workflows724725### When to use `MCP Prompt`726727- **Provide domain knowledge** - Share best practices and coding standards specific to your project728- **Set coding conventions** - Establish naming conventions, architecture patterns, and code style729- **Give context about project structure** - Explain how your project is organized and why730- **Share workflow instructions** - Provide step-by-step procedures for common tasks731- **Inject specialized knowledge** - Add information about specific Unity features, third-party assets, or custom systems732733**Examples:**734735- "Always use PascalCase for public methods and camelCase for private fields"736- "This project uses a custom event system located in Scripts/Events/"737- "When creating UI elements, always add them to the Canvas in Scene/UI/MainCanvas"738- "Performance is critical - prefer object pooling for frequently instantiated objects"739- "This project follows SOLID principles - explain any architecture decisions"740741---742743# Contribution 💙💛744745Contributions are highly appreciated. Bring your ideas and let's make game development simpler than ever before! Do you have an idea for a new `MCP Tool` or feature, or did you spot a bug and know how to fix it?746747**Please give this project a star 🌟 if you find it useful!**7487491. 👉 [Read Development documentation](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/dev/Development.md)7502. 👉 [Fork the project](https://github.com/IvanMurzak/Unity-MCP/fork)7513. Clone the fork and open the `./Unity-MCP-Plugin` folder in Unity7524. Implement new things in the project, commit, push it to GitHub7535. Create Pull Request targeting original [Unity-MCP](https://github.com/IvanMurzak/Unity-MCP/compare) repository, `main` branch.754
Full transparency — inspect the skill content before installing.