DOCSEARCHbyAlgolia
Submit Docs

Unity MCP

repository·main·Indexed 25 days ago

https://github.com/ivanmurzak/unity-mcp

An AI-powered game development assistant that connects AI agents (such as Claude, Cursor, and Windsurf) to the Unity Editor and Runtime via the Model Context Protocol (MCP). It includes the unity-mcp-cli tool for managing projects, installing the com.ivanmurzak.unity.mcp plugin, configuring MCP tools, and automating the development and test loop. It enables automated workflows, real-time AI debugging, and dynamic NPC behavior within compiled games.

Tokens
68.5K
Snippets
109
Records
389
Agent score
80%

What's inside unity-mcp

  1. Overview of Unity MCP Features

    main

    Unity MCP is an AI-driven game development assistant for both the Unity Editor and Runtime. It allows you to connect AI clients (like Claude, Cursor, or Windsurf) to Unity via the Model Context Protocol (MCP).

    Key Capabilities:

    • AI Agents: Use providers like Anthropic, OpenAI, or Microsoft.
    • MCP Tools: Access a wide range of default tools for Editor workflows.
    • Automatic Skills: Skills are automatically generated based on your OS, Unity version, and installed plugins.
    • Runtime Support: Use LLMs directly within a compiled game for dynamic NPC behavior or real-time debugging.
    • Debugging: Allow AI to identify and fix project issues.
    • Extensibility: Build custom tools directly in your project code.

  2. Extend Unity MCP with Tools, Resources, and Prompts

    main

    Unity MCP is extensible. You can define custom capabilities directly in your Unity project codebase to expose them to LLMs:

    • MCP Tool: Executable functions with typed parameters that perform actions (e.g., creating GameObjects, batch processing assets). They can be thread-aware (running on the main thread for Unity API calls or background threads for processing).
    • MCP Resource: Provides read-only access to project data (e.g., scene hierarchy, asset lists, script dependencies). These act as 'sensors' for the AI to understand the project state.
    • MCP Prompt: Smart templates used to inject context, instructions, or domain knowledge (e.g., coding standards, project-specific architectural patterns) into the LLM conversation.

  3. Understand Unity-MCP Architecture

    main

    Deterministic Port

    The CLI generates a deterministic port for each Unity project based on its directory path (SHA256 hash mapped to port range 20000–29999). This ensures the server and plugin automatically agree on the same port.

    Plugin Installation

    The install-plugin command modifies Packages/manifest.json to add the OpenUPM scoped registry (package.openupm.com), register required scopes (com.ivanmurzak, extensions.unity), and add the com.ivanmurzak.unity.mcp dependency.

    Configuration File

    The configure command manages UserSettings/AI-Game-Developer-Config.json, which controls Tools, Prompts, Resources, and Connection settings (host URL, auth token, transport method, timeouts).

    Unity Hub Integration

    Commands managing editors use the Unity Hub CLI. If Unity Hub is not installed, the CLI automatically downloads and installs it for Windows, macOS, or Linux.

  4. Understand the Unity MCP System Architecture

    main

    The Unity MCP system operates through a multi-layered communication stack:

    1. MCP Client (e.g., Claude, Cursor): Communicates via stdio or streamableHttp.
    2. GameDev-MCP-Server: An ASP.NET Core server (binary gamedev-mcp-server) that acts as the bridge. It communicates with Unity via SignalR.
    3. Unity-MCP-Plugin: Resides in the Unity Editor/Runtime and communicates with the Unity Engine via the Unity API.

    Key architectural constraints:

    • The MCP Server is a standalone binary downloaded automatically by the plugin to Library/mcp-server/{platform}/.
    • The Unity-MCP-Plugin auto-starts the server binary when the Unity Editor loads.
    • All communication within Unity is executed on the main thread using MainThread.Instance.Run() to ensure compatibility with the Unity API.

  5. Understand MCP Concepts: Tools, Resources, and Prompts

    main

    The Unity MCP project utilizes the Model Context Protocol (MCP) to bridge LLMs with the Unity engine through three primary primitives:

    MCP Tool

    Tools are executable functions that allow an LLM to perform actions within Unity. They act as the bridge between natural language requests and actual Unity operations.

    • Capabilities: Executable functions, typed parameters/descriptions, return values, and thread awareness (can run on the Main Thread for Unity API calls or background threads for heavy processing).
    • Use Cases: Automating repetitive tasks, bundling complex API calls, project-specific workflows, and exposing custom game logic to the AI.
    • Examples: Creating/configuring GameObjects, batch processing assets, setting lighting, or generating level geometry.

    MCP Resource

    Resources provide read-only access to Unity project data. They act as "sensors" that provide the LLM with project context.

    • Capabilities: Read-only access, structured information in LLM-understandable formats, and real-time data reflecting the current project state.
    • Use Cases: Project analysis (structure/assets), debugging assistance, providing context for intelligent suggestions, and asset management.
    • Examples: Exposing scene hierarchy, listing available materials/textures, showing script dependencies, or displaying rendering pipeline configurations.

    MCP Prompt

    Prompts are intelligent templates used to inject predefined context, instructions, or knowledge into the LLM conversation.

    • Capabilities: Context guidance, role-based simulation, dynamic content (using real-time project data), and reusable templates.
    • Use Cases: Providing domain knowledge (best practices), setting coding conventions (naming styles), explaining project structure, and sharing workflow instructions.
    • Examples: Defining naming conventions (e.g., PascalCase for public methods), explaining custom event systems, or enforcing architectural principles like SOLID.

  6. Understand Unity-MCP Deterministic Port Allocation

    main
    The CLI and the Unity plugin use a deterministic port allocation strategy to ensure they automatically connect without manual configuration. The CLI generates a deterministic port by applying a SHA256 hash to the Unity project's directory path, mapping it to the port range 20000-29999. This ensures the server and the plugin always use the same port for a specific project.

  7. Understand MCP Concepts in Unity MCP

    main

    The Unity MCP project implements the Model Context Protocol (MCP) to bridge Large Language Models (LLMs) with the Unity Engine. Key concepts include:

    • MCP Server: The interface between the MCP Client and the Unity Engine. This project acts as the server.
    • MCP Tool: Executable functions or methods that an LLM can call to perform actions in Unity (e.g., "create a cube", "change material color"). Tools are type-parameterized, return success/failure results, and are thread-aware (can run on the main Unity thread or background threads).
    • MCP Resource: Read-only access to Unity project data. Resources allow the LLM to inspect the current state, assets, and configurations (e.g., scene hierarchy, material lists, script dependencies) to provide context for better decision-making.
    • MCP Prompt: Pre-defined instruction templates injected into the LLM conversation. These can be static or dynamic, providing project-specific coding standards, architectural patterns, or workflow guides (e.g., "Always use PascalCase for public methods").

  8. Unity-MCP-Plugin Editor Capabilities

    main

    The Editor component provides Unity Editor integration and manages the GameDev-MCP-Server lifecycle.

    Key Features:

    • Plugin Lifecycle Management: Automatically initializes on Editor load via [InitializeOnLoad] and manages connections across assembly reloads and Play mode transitions.
    • MCP Server Binary Management: Automatically downloads and manages the GameDev-MCP-Server executable from GitHub releases based on the ServerVersion constant. It handles cross-platform selection (Windows/macOS/Linux) and version compatibility.
    • MCP API Implementation: Provides over 50 tools covering GameObjects, Scenes, Assets, Prefabs, Scripts, Components, and more. All operations are executed on the Unity main thread for safety.
    • Editor UI: Access configuration via Window > AI Game Developer. You can also manage server binaries and view logs via Unity menu items.

  9. Unity-MCP Project Architecture

    main

    The project consists of four main components:

    • AI Agent: External interfaces like Claude, Copilot, or Cursor (not part of this repo).
    • GameDev-MCP-Server: A shared C# ASP.NET Core application that implements the Model Context Protocol. It acts as a bridge between the AI Agent and Unity. It communicates via SignalR and can run locally or in the cloud. (Located in the GameDev-MCP-Server repository).
    • Unity-MCP-Plugin: A C# plugin integrated into Unity that has access to the Unity API. It communicates with the GameDev-MCP-Server via SignalR to execute commands.
    • Unity: The Unity Engine game engine.

  10. Architecture Overview of Unity-MCP

    main

    The Unity-MCP ecosystem consists of four main components:

    1. AI Agent: External interfaces like Claude, Copilot, or Cursor that interact with the system.
    2. GameDev-MCP-Server: A shared C# ASP.NET Core application (located in the GameDev-MCP-Server repo) that implements the Model Context Protocol. It acts as a bridge between the AI Agent and the Unity Plugin using SignalR.
    3. Unity-MCP-Plugin: A Unity-integrated plugin that executes commands from the server and has access to the Unity API.
    4. Unity Engine: The target game engine where the plugin operates.

  11. Understand the Unity-MCP Architecture

    main

    The Unity-MCP ecosystem consists of four main components interacting in a specific flow:

    1. AI Agent (e.g., Claude, Copilot, Cursor): The interface used by the developer to interact with the system.
    2. GameDev-MCP-Server: A shared C# ASP.NET Core application (located in a separate repository: GameDev-MCP-Server). It acts as the bridge between the AI Agent and Unity, communicating via SignalR. It can run locally or in the cloud.
    3. Unity-MCP-Plugin: The Unity integration that accesses Unity APIs and executes commands received from the server via SignalR.
    4. Unity: The game engine where the plugin resides and commands are executed.

    Communication Flow: AI Agent <--> GameDev-MCP-Server <--> Unity-MCP-Plugin <--> Unity

  12. Understand Unity-MCP-Plugin Architecture

    main

    The Unity-MCP-Plugin is a UPM package (com.ivanmurzak.unity.mcp) that integrates MCP capabilities into Unity. It consists of two main parts:

    Editor

    Located in .../Editor, it manages the plugin lifecycle and the GameDev-MCP-Server binary.

    • Lifecycle Management: Uses [InitializeOnLoad] to auto-initialize and manages connections during assembly reloads or play mode transitions.
    • Server Management: Downloads and manages the GameDev-MCP-Server executable (Windows/macOS/Linux) and ensures version compatibility.
    • UI: Access configuration via Window > AI Game Developer.

    Runtime

    Located in .../Runtime, it handles the core communication infrastructure.

    • SignalR Connection: Managed by UnityMcpPlugin.cs using the R3 library for reactive state monitoring.
    • Main Thread Dispatcher: Uses MainThreadDispatcher.cs to queue Unity API calls from SignalR background threads onto the Unity main thread.
    • Serialization: Provides custom JSON converters for Unity types (e.g., GameObject, Transform, Vector3) using reference formats like GameObjectRef and ComponentRef.