Unity MCP ✨

undefinedCreate your Unity apps with LLMs!undefined

Unity MCP acts as a bridge, allowing AI assistants (like Claude, Cursor) to interact directly with your Unity Editor via a local MCP (Model Context Protocol) Client. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.

Key Features 🚀

• undefined🗣️ Natural Language Control: Instruct your LLM to perform Unity tasks.
• undefined🛠️ Powerful Tools: Manage assets, scenes, materials, scripts, and editor functions.
• undefined🤖 Automation: Automate repetitive Unity workflows.
• undefined🧩 Extensible: Designed to work with various MCP Clients.

How It Works 🤔

Unity MCP connects your tools using two components:

1. undefinedUnity MCP Bridge: A Unity package running inside the Editor. (Installed via Package Manager).
2. undefinedUnity MCP Server: A Python server that runs locally, communicating between the Unity Bridge and your MCP Client. (Installed manually).

undefinedFlow: [Your LLM via MCP Client] <-> [Unity MCP Server (Python)] <-> [Unity MCP Bridge (Unity Editor)]

Installation ⚙️

undefinedNote: The setup is constantly improving as we update the package. Check back if you randomly start to run into issues.

Prerequisites

• undefinedGit CLI: For cloning the server code. Download Git

• undefinedPython: Version 3.12 or newer. Download Python

• undefinedUnity Hub & Editor: Version 2020.3 LTS or newer. Download Unity

• undefineduv (Python package manager):undefined

  pip install uv
  # Or see: https://docs.astral.sh/uv/getting-started/installation/
  

• undefinedAn MCP Client:undefined

  • Claude Desktop
  • Claude Code
  • Cursor
  • Visual Studio Code Copilot
  • (Others may work with manual config)
• [Optional] Roslyn for Advanced Script Validation

  For Strict validation level that catches undefined namespaces, types, and methods:

  undefinedMethod 1: NuGet for Unity (Recommended)undefined

  1. Install NuGetForUnity
  2. Go to Window > NuGet Package Manager
  3. Search for Microsoft.CodeAnalysis.CSharp and install the package
  4. Go to Player Settings > Scripting Define Symbols
  5. Add USE_ROSLYN
  6. Restart Unity

  undefinedMethod 2: Manual DLL Installationundefined

  1. Download Microsoft.CodeAnalysis.CSharp.dll and dependencies from NuGet
  2. Place DLLs in Assets/Plugins/ folder
  3. Ensure .NET compatibility settings are correct
  4. Add USE_ROSLYN to Scripting Define Symbols
  5. Restart Unity

  undefinedNote: Without Roslyn, script validation falls back to basic structural checks. Roslyn enables full C# compiler diagnostics with precise error reporting.

Step 1: Install the Unity Package (Bridge)

1. Open your Unity project.
2. Go to Window > Package Manager.
3. Click + -> Add package from git URL....
4. Enter:

   https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge
   

5. Click Add.
6. The MCP Server should automatically be installed onto your machine as a result of this process.

Step 2: Configure Your MCP Client

Connect your MCP Client (Claude, Cursor, etc.) to the Python server you installed in Step 1.

undefinedOption A: Auto-Configure (Recommended for Claude/Cursor/VSC Copilot)undefined

1. In Unity, go to Window > Unity MCP.
2. Click Auto Configure on the IDE you uses.
3. Look for a green status indicator 🟢 and “Connected”. (This attempts to modify the MCP Client’s config file automatically).

undefinedOption B: Manual Configurationundefined

If Auto-Configure fails or you use a different client:

1. undefinedFind your MCP Client’s configuration file. (Check client documentation).
   • Claude Example (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Example (Windows): %APPDATA%\Claude\claude_desktop_config.json
2. undefinedEdit the file to add/update the mcpServers section, using the exact paths from Step 1.

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\UnityMCP\\UnityMcpServer\\src",
        "server.py"
      ]
    }
    // ... other servers might be here ...
  }
}

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/usr/local/bin/UnityMCP/UnityMcpServer/src",
        "server.py"
      ]
    }
    // ... other servers might be here ...
  }
}

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/YOUR_USERNAME/bin/UnityMCP/UnityMcpServer/src",
        "server.py"
      ]
    }
    // ... other servers might be here ...
  }
}

undefinedOption C: Claude Code Registrationundefined

If you’re using Claude Code, you can register the MCP server using these commands:

undefinedmacOS:undefined

claude mcp add UnityMCP -- uv --directory /[PATH_TO]/UnityMCP/UnityMcpServer/src run server.py

undefinedWindows:undefined

claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/Scripts/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/Programs/UnityMCP/UnityMcpServer/src" run server.py

Usage ▶️

1. undefinedOpen your Unity Project. The Unity MCP Bridge (package) should connect automatically. Check status via Window > Unity MCP.

2. undefinedStart your MCP Client (Claude, Cursor, etc.). It should automatically launch the Unity MCP Server (Python) using the configuration from Installation Step 3.

3. undefinedInteract! Unity tools should now be available in your MCP Client.

   Example Prompt: Create a 3D player controller, Create a yellow and bridge sun, Create a cool shader and apply it on a cube.

Future Dev Plans (Besides PR) 📝

🔴 High Priority

• Asset Generation Improvements **Asset Generation Improvements** - Enhanced server request handling and asset pipeline optimization
• Code Generation Enhancements **Code Generation Enhancements** - Improved generated code quality and error handling
• Robust Error Handling **Robust Error Handling** - Comprehensive error messages, recovery mechanisms, and graceful degradation
• Remote Connection Support **Remote Connection Support** - Enable seamless remote connection between Unity host and MCP server
• Documentation Expansion **Documentation Expansion** - Complete tutorials for custom tool creation and API reference

🟡 Medium Priority

• Custom Tool Creation GUI **Custom Tool Creation GUI** - Visual interface for users to create and configure their own MCP tools
• Advanced Logging System **Advanced Logging System** - Logging with filtering, export, and debugging capabilities

🟢 Low Priority

• Mobile Platform Support **Mobile Platform Support** - Extended toolset for mobile development workflows and platform-specific features
• Easier Tool Setup **Easier Tool Setup**
• Plugin Marketplace **Plugin Marketplace** - Community-driven tool sharing and distribution platform