DOCSEARCHbyAlgolia
Submit Docs

MCP Unity

repository·main·Indexed 23 days ago

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

A Model Context Protocol (MCP) implementation for the Unity Editor (version 6 or later) that enables AI agents to interact with Unity projects via a Node.js server bridge. It provides tools for manipulating GameObjects, managing scenes and assets, executing menu items, and running tests. Additionally, it improves IDE intelligence for tools like VS Code, Cursor, and Windsurf by integrating the Unity Library/PackedCache folder into the workspace.

Tokens
15.2K
Snippets
12
Records
78
Agent score
82%

What's inside mcp-unity

  1. Overview of MCP Unity Editor

    main

    MCP Unity is an implementation of the Model Context Protocol (MCP) for the Unity Editor. It acts as a bridge between Unity and Node.js-based MCP servers, enabling AI agents (such as Claude, Windsurf, and Cursor) to interact directly with your Unity project.

    Key capabilities include:

    • IDE Integration: Automatically integrates Unity's Library/PackedCache into your workspace (e.g., VSCode, Cursor) to improve code intelligence, autocomplete, and type information for Unity packages.
    • AI-Driven Automation: Allows AI assistants to execute Unity menu items, manipulate GameObjects, manage assets, run tests, and modify materials via MCP tools and resources.

  2. What is MCP Unity and how does it work?

    main

    MCP Unity is a bridge that connects the Unity Editor environment to AI assistant LLM tools using the Model Context Protocol (MCP).

    It functions by:

    1. Exposing Unity functionality: It turns Unity Editor capabilities (like creating objects, modifying components, or running tests) into "tools" and "resources" that an AI can understand.
    2. Establishing a communication bridge: It runs a WebSocket server inside Unity and a Node.js server (acting as a WebSocket client) that implements the MCP protocol. This allows an AI assistant to send commands to Unity and receive information back.
    3. Enabling natural language workflows: Developers can use natural language prompts to execute complex tasks within a Unity project, accelerating development workflows.

  3. Extend MCP Unity with Custom Tools

    main

    You can extend MCP Unity by defining new tools in both Unity (C#) and the Node.js server (TypeScript).

    In Unity (C#)

    Create a class that inherits from McpToolBase and register it in McpUnityServer.cs.

    In Node.js (TypeScript)

    1. Define the tool in Server/src/tools/ (including Zod schemas for input/output).
    2. Register the tool in Server/src/index.ts.

    The Node.js side will then forward requests to the corresponding C# tool in Unity.

  4. Improve IDE intelligence with Package Cache Access

    main
    MCP Unity automatically integrates with VSCode-like IDEs (Visual Studio Code, Cursor, Windsurf, Google Antigravity) by adding the Unity Library/PackedCache folder to your workspace. This improves code intelligence, enables better autocompletion and type information for Unity packages, and helps AI coding assistants understand project dependencies.

  5. How to extend MCP Unity with custom tools

    main

    MCP Unity is extensible, allowing you to define new tools and resources tailored to your project's specific needs. Extension happens in two parts:

    1. In Unity (C#): Create a new C# class that inherits from McpToolBase (or a similar base for resources) to expose custom Unity Editor functionality. These tools are registered in McpUnityServer.cs.
    2. In the Node.js Server (TypeScript): Define a corresponding TypeScript tool handler in the Server/src/tools/ directory, including input/output Zod schemas, and register it in Server/src/index.ts. This part handles forwarding requests from the AI to the new C# tools in Unity.

  6. Run tests for MCP Unity

    main

    C# Tests (Unity)

    1. Open Unity Editor.
    2. Navigate to Window > General > Test Runner.
    3. Select the EditMode tab.
    4. Click Run All.

    TypeScript Tests (Server)

    Run tests using Jest from the Server~ directory:

    cd Server~
npm test

    To run tests in watch mode:

    npm run test:watch
    # TypeScript tests
cd Server~
npm test

# Watch mode
npm run test:watch

  8. Start the Unity Editor MCP Server

    main

    To begin using MCP Unity with your AI assistant:

    1. Open the Unity Editor.
    2. Navigate to Tools > MCP Unity > Server Window.
    3. Click the "Start Server" button to launch the WebSocket server.
    4. Open your AI client (e.g., Claude Desktop, Cursor, or Windsurf). The connection will be indicated by a green box in the Unity Server Window once the AI client connects to the WebSocket server.

  9. Install MCP Unity Server

    main

    Installing the MCP Unity server is a multi-step process involving Node.js installation, the Unity Package Manager, and AI client configuration.

    1. Install Node.js

    You must have Node.js 18 or higher installed.

    • Windows: Download the LTS .msi from nodejs.org.
    • macOS: Download the LTS .pkg from nodejs.org or use Homebrew: brew install node@18.
    • Verify: Run node --version in your terminal.

    2. Install via Unity Package Manager

    1. Open Unity and go to Window > Package Manager.
    2. Click the "+" button and select "Add package from git URL...".
    3. Enter: https://github.com/CoderGamester/mcp-unity.git.
    4. Click "Add".

    3. Configure AI LLM Client

    Option 1: Using Unity Editor Configuration

    1. In Unity, navigate to Tools > MCP Unity > Server Window.
    2. Click the "Configure" button to generate configuration for your AI LLM client.
    3. Follow the popup instructions to confirm the installation.

    Option 2: Manual Configuration

    Open your AI client's MCP configuration file (e.g., claude_desktop_config.json for Claude Desktop) and add the following entry. Replace ABSOLUTE/PATH/TO with the actual absolute path to your MCP Unity installation:

    {
  "mcpServers": {
    "mcp-unity": {
      "command": "node",
      "args": [
        "ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"
      ]
    }
  }
}

  10. Configure networking for WSL2 (Windows 11)

    main

    If running the Node.js server in WSL2 and Unity on Windows 11, ws://localhost:8090/McpUnity may fail with ECONNREFUSED because they reside in different network namespaces.

    Option 1: Enable Mirrored Mode (Recommended)

    Enable "Mirrored mode networking" in Windows 11 settings (Settings > System > For developers > WSL) or via .wslconfig:

    [wsl2]
networkingMode=mirrored

    Option 2: Point Node client to Windows Host

    Set the UNITY_HOST environment variable in your WSL shell to the Windows host IP:

    export UNITY_HOST=$(grep -m1 nameserver /etc/resolv.conf | awk '{print $2}')

    Option 3: Allow Remote Connections in Unity

    1. In Unity, go to Tools > MCP Unity > Server Window and enable "Allow Remote Connections" (this binds Unity to 0.0.0.0).
    2. Ensure Windows Firewall allows inbound TCP on the configured port (default 8090).
    3. Connect from WSL2 using the Windows host IP or localhost if mirrored mode is active.

  11. Requirements for MCP Unity

    main

    To use MCP Unity, ensure your environment meets the following requirements:

    • Unity: Version 6 or higher (required for server installation).
    • Node.js: Version 18 or higher (required to run the server).
    • npm: Version 9 or higher (required for debugging).
    IMPORTANT

    Project path must not contain spaces. Your Unity project file path must not contain any spaces. If it does, MCP clients (like Cursor, Claude, or Windsurf) will fail to connect to the MCP Unity server.

    Valid Example: C:\Users\YourUser\Documents\UnityProjects\MyAwesomeGame
    Invalid Example: C:\Users\Your User\Documents\Unity Projects\My Awesome Game

  12. Enable IDE integration via Package Cache Access

    main
    To improve code intelligence, autocomplete, and type information for Unity packages in VSCode-based IDEs (Visual Studio Code, Cursor, Windsurf), add the Unity Library/PackedCache folder to your workspace. This helps AI coding assistants understand project dependencies more effectively.