Unity MCP

An MCP server and plugin for connecting the Unity Editor and games to MCP clients like Claude Desktop.

View on GitHub →

MCP OpenUPM Docker Image Unity Editor Unity Runtime r Discord Stars License Stand With Ukraine

中文 | 日本語 | Español

Unity MCP is an AI-powered game development assistant that serves as a bridge between MCP Client and Unity. Simply type a message in chat and get work done using any advanced LLM model of your choice. Have an issue to fix? Ask the AI to fix it. Watch demo videos.

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

Features

  • ✔️ Natural conversation - Chat with AI like you would with a human
  • ✔️ Code assistance - Ask AI to write code and run tests
  • ✔️ Debug support - Ask AI to get logs and fix errors
  • ✔️ Multiple LLM providers - Use agents from Anthropic, OpenAI, Microsoft, or any other provider with no limits
  • ✔️ Flexible deployment - Works locally (stdio) and remotely (http) by configuration
  • ✔️ Rich toolset - Wide range of default MCP Tools
  • ✔️ Extensible - Create custom MCP Tools in your project code

Stability status

Unity VersionEditmodePlaymodeStandalone
2022.3.61f1rrr
2023.2.20f1rrr
6000.2.3f1rrr

Content

Installation

Step 1: Install Unity MCP Plugin

[!IMPORTANT] Project path cannot contain spaces

  • ✅ C:/MyProjects/Project
  • ❌ C:/My Projects/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 - OpenUPM-CLI

openupm add com.ivanmurzak.unity.mcp

Step 2: Install MCP Client

Choose 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.

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.

Step 3: Configure MCP Client

Automatic configuration

  • Open Unity project
  • Open Window/AI Game Developer (Unity-MCP)
  • Click Configure at your MCP client

Unity_AI

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.

Replace unityProjectPath with your real project path

claude mcp add Unity-MCP "<unityProjectPath>/Library/mcp-server/win-x64/unity-mcp-server.exe" client-transport=stdio

Replace unityProjectPath with your real project path

claude mcp add Unity-MCP "<unityProjectPath>/Library/mcp-server/osx-arm64/unity-mcp-server" client-transport=stdio

Replace unityProjectPath with your real project path

claude mcp add Unity-MCP "<unityProjectPath>/Library/mcp-server/osx-x64/unity-mcp-server" client-transport=stdio

Replace unityProjectPath with your real project path

claude mcp add Unity-MCP "<unityProjectPath>/Library/mcp-server/linux-x64/unity-mcp-server" client-transport=stdio

Replace unityProjectPath with your real project path

claude mcp add Unity-MCP "<unityProjectPath>/Library/mcp-server/linux-arm64/unity-mcp-server" client-transport=stdio

Use AI

Communicate 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.

Some MCP Clients allow you to choose different LLM models. Pay attention to this feature, as some models may work much better than others.

Example commands:

Explain my scene hierarchy

Create 3 cubes in a circle with radius 2

Create metallic golden material and attach it to a sphere gameObject

Make sure Agent mode is turned on in your MCP client

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 Roslyn for 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, field, or property via Description attributes

Customize MCP

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 MCP Tool

To add a custom MCP Tool, you need:

  1. A class with the McpPluginToolType attribute
  2. A method in the class with the McpPluginTool attribute
  3. Optional: Add a Description attribute to each method argument to help the LLM understand it
  4. Optional: Use string? optional = null properties with ? and default values to mark them as optional for 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.

[McpPluginToolType]
public class Tool_GameObject
{
    [McpPluginTool
    (
        "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 runtime (in-game) MCP Tool

⚠️ Not yet supported. The work is in progress

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.

[McpPluginPromptType]
public static class Prompt_ScriptingCode
{
    [McpPluginPrompt(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.";
    }
}

Unity MCP Server setup

Unity MCP Server supports many different launch options and Docker deployment. Both transport protocols are supported: http 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 VariableCommand Line ArgsDescription
UNITY_MCP_PORT--portClient -> Server <- Plugin connection port (default: 8080)
UNITY_MCP_PLUGIN_TIMEOUT--plugin-timeoutPlugin -> Server connection timeout (ms) (default: 10000)
UNITY_MCP_CLIENT_TRANSPORT--client-transportClient -> Server transport type: stdio or http (default: http)

Command line args support also the option with a single - prefix (-port) and an option without prefix at all (port).

Docker 📦

Docker Image

Make sure Docker is installed. And please make sure Docker Desktop is launched if you are at Windows operation system.

HTTP Transport

docker run -p 8080:8080 ivanmurzakdev/unity-mcp-server

{
  "mcpServers": {
    "Unity-MCP": {
      "url": "http://localhost:8080"
    }
  }
}

Replace url with your real endpoint if it is hosted in cloud

STDIO Transport

For using this variant, MCP Client should launch the MCP Server in the docker. It is achievable through the modified MCP Client configuration.

docker run -t -e UNITY_MCP_CLIENT_TRANSPORT=stdio -p 8080:8080 ivanmurzakdev/unity-mcp-server

{
  "mcpServers": {
    "Unity-MCP": {
      "command": "docker",
      "args": [
        "run",
        "-t",
        "-e",
        "UNITY_MCP_CLIENT_TRANSPORT=stdio",
        "-p",
        "8080:8080",
        "ivanmurzakdev/unity-mcp-server"
      ]
    }
  }
}

Custom port

docker run -e UNITY_MCP_PORT=123 -p 123:123 ivanmurzakdev/unity-mcp-server

{
  "mcpServers": {
    "Unity-MCP": {
      "url": "http://localhost:123"
    }
  }
}

Replace url with your real endpoint if it is hosted in cloud

Binary executable

You 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, it contains pre-compiled binaries for all CPU architectures.

./unity-mcp-server --port 8080 --plugin-timeout 10000 --client-transport stdio

Replace <project> with your Unity project path.

{
  "mcpServers": {
    "Unity-MCP": {
      "command": "<project>/Library/mcp-server/win-x64/unity-mcp-server.exe",
      "args": [
        "--port=8080",
        "--plugin-timeout=10000",
        "--client-transport=stdio"
      ]
    }
  }
}

How it works

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.

Connect Unity MCP to LLM clients such as Claude or Cursor using the integrated AI Connector window. Custom clients are also supported.

The 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.

What is MCP

MCP - 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.

What is MCP Client

It 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.

What is MCP Server

It is a bridge between MCP Client and "something else", in this particular case it is Unity Engine. This project includes MCP Server.

What is MCP Tool

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.

Key characteristics:

  • Executable functions that perform specific operations
  • Typed parameters with descriptions to help the LLM understand what data to provide
  • Return values that give feedback about the operation's success or failure
  • Thread-aware - can run on main thread for Unity API calls or background thread for heavy processing

When to use MCP Tool

  • Automate repetitive tasks - Create tools for common operations you do frequently
  • Complex operations - Bundle multiple Unity API calls into a single, easy-to-use tool
  • Project-specific workflows - Build tools that understand your project's specific structure and conventions
  • Error-prone tasks - Create tools that include validation and error handling
  • Custom game logic - Expose your game's systems to AI for dynamic content creation

Examples:

  • Creating and configuring GameObjects with specific components
  • Batch processing assets (textures, materials, prefabs)
  • Setting up lighting and post-processing effects
  • Generating level geometry or placing objects procedurally
  • Configuring physics settings or collision layers

What is MCP Resource

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.

Key characteristics:

  • Read-only access to project data and Unity objects
  • Structured information presented in a format the LLM can understand
  • Real-time data that reflects the current state of your project
  • Contextual awareness helping the AI make informed decisions

When to use MCP Resource

  • Project analysis - Let AI understand your project structure, assets, and organization
  • Debugging assistance - Provide current state information for troubleshooting
  • Intelligent suggestions - Give AI context to make better recommendations
  • Documentation generation - Automatically create documentation based on project state
  • Asset management - Help AI understand what assets are available and their properties

Examples:

  • Exposing scene hierarchy and GameObject properties
  • Listing available materials, textures, and their settings
  • Showing script dependencies and component relationships
  • Displaying current lighting setup and render pipeline configuration
  • Providing information about audio sources, animations, and particle systems

What is MCP Prompt

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.

Key characteristics:

  • Contextual guidance that influences how the AI responds
  • Role-based - can simulate different personas (User requests or Assistant knowledge)
  • Dynamic content - can include real-time project data
  • Reusable templates for common scenarios and workflows

When to use MCP Prompt

  • Provide domain knowledge - Share best practices and coding standards specific to your project
  • Set coding conventions - Establish naming conventions, architecture patterns, and code style
  • Give context about project structure - Explain how your project is organized and why
  • Share workflow instructions - Provide step-by-step procedures for common tasks
  • Inject specialized knowledge - Add information about specific Unity features, third-party assets, or custom systems

Examples:

  • "Always use PascalCase for public methods and camelCase for private fields"
  • "This project uses a custom event system located in Scripts/Events/"
  • "When creating UI elements, always add them to the Canvas in Scene/UI/MainCanvas"
  • "Performance is critical - prefer object pooling for frequently instantiated objects"
  • "This project follows SOLID principles - explain any architecture decisions"

Contribution 💙💛

Contributions 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?

  1. 👉 Fork the project
  2. Clone the fork and open the ./Unity-MCP-Plugin folder in Unity
  3. Implement new things in the project, commit, push it to GitHub
  4. Create Pull Request targeting original Unity-MCP repository, main branch.

Related Servers