Unity Code MCP

🚀 Unity Code MCP

Unity Code MCP is a coding focused Model Context Protocol (MCP) server. It allows AI agents to autonomously write Unity code, addressing the challenges in Unity code development and providing efficient solutions.

🚀 Quick Start

Unity Code MCP is a high - performance, coding - focused MCP server written in Rust. It can handle Unity's compilation cycles smoothly and only offers the essential tools for autonomous code development, including compilation feedback and test execution. After configuration, AI agents can develop Unity code completely autonomously.

✨ Features

• 🤖 Coding - Optimized: Streamlined tools designed for efficient AI agent coding workflows.
• ⚡ Lightweight and High Performance: Built in Rust for exceptional speed, minimal memory usage, and lightning - fast response times. Uses only 1MB memory when the workspace is not a Unity Project, and only 10MB when it is and the Unity Editor is open for the project. Also, the communication with the Unity Editor is based on UDP, so it's a minimal load for your system.
• 🎯 Efficient Communication: Minimal token usage with essential operations, only returns relevant information.
• 🧪 Test - Driven: Comprehensive test execution and reporting capabilities.
• 📦 Self - Contained: Single binary with no runtime dependencies (no Node.js, Python, or .NET required).

📦 Installation

Prerequisites

• Unity 6.0 or higher.
• Rust toolchain (for building from source).
• CMake and a C compiler (required for building dependencies).

Step 1: Install Unity Package

Install the Visual Studio Code Editor package in your Unity project.

Step 2: Get the Binary

Option A: Download Release (Recommended) (Windows Only)

• Download the latest binary from the Releases page.

Option B: Build from Source

cargo build --release

Step 3: Configure Your AI Assistant

Add the MCP server to your AI assistant configuration:

For Cursor/Trae:

{
  "mcpServers": {
    "unity - code": {
      "command": "/path/to/unity - code - mcp",
      "env": {
        "UNITY_PROJECT_PATH": "${workspaceFolder}"
      }
    }
  }
}

For VS Code with MCP Extension:

{
  "mcp.servers": {
    "unity - code": {
      "command": "/path/to/unity_code_mcp",
      "env": {
        "UNITY_PROJECT_PATH": "${workspaceFolder}"
      }
    }
  }
}

For Claude Desktop:

{
  "mcpServers": {
    "unity - code": {
      "command": "/path/to/unity_code_mcp"
    }
  }
}

⚠️ Important Note

The UNITY_PROJECT_PATH environment variable is a fallback option. If your IDE supports the MCP roots capability, the server will automatically detect Unity projects from the provided workspace roots and prioritize that over the environment variable.

💡 Usage Tip

If ${workspaceFolder} doesn't work in your IDE, try using an absolute path instead, e.g., "UNITY_PROJECT_PATH": "/absolute/path/to/your/unity/project". Alternatively, ask your IDE developer to add support for the MCP roots capability. Use absolute paths for the binary command.

💻 Usage Examples

Basic Usage

Once configured, AI agents can develop Unity code completely autonomously:

User: "Create a player controller that moves with WASD keys and has jump functionality. Make sure it's fully tested."

AI: I'll create a complete player controller with movement and jumping, then write comprehensive tests.

1. [AI writes PlayerController.cs with movement logic]
2. [AI calls: refresh_asset_database]
   → Result: "Compilation failed: CS0246: The type or namespace name 'Rigidbody' could not be found"
3. [AI fixes the missing using UnityEngine; statement]
4. [AI calls: refresh_asset_database]
   → Result: "Compilation successful, no errors"
5. [AI writes PlayerControllerTests.cs with movement and jump tests]
6. [AI calls: run_tests]
   → Result: "5 tests passed, 2 tests failed: NullReferenceException in Jump_ShouldApplyUpwardForce, ArgumentException in Move_WithInvalidInput"
7. [AI analyzes failures and fixes null reference and input validation bugs]
8. [AI calls: refresh_asset_database]
   → Result: "Compilation successful, no errors"
9. [AI calls: run_tests]
   → Result: "All 7 tests passed successfully"

AI: ✅ Complete! Created a fully functional PlayerController with WASD movement, jump mechanics, and comprehensive test coverage. All tests are passing.

🔧 Technical Details

MCP Server Tools

Unity Code MCP provides 2 tools for autonomous code development:

1. Asset Database Refresh

• Triggers Unity compilation and asset processing.
• Returns compile errors and other non - compile warnings and errors (only include the logs during the refresh).
• Handles domain reload gracefully.

Asset database refresh tool in action:

2. Test Execution

• Runs Unity tests with comprehensive reporting.
• Provides detailed stack traces and logs for failures.
• Supports both EditMode and PlayMode tests.

Test execution tool in action:

Development & Testing

Running Tests

To run the test suite:

1. Start Unity Editor with the embedded test project:

   # Open Unity Editor and load the project at:
   # ./UnityProject
   

2. Run tests (single - threaded to avoid Unity conflicts):

   cargo test -- --test - threads = 1
   

⚠️ Important Note

Tests require a running Unity Editor instance with the embedded project loaded. Tests may take 30 - 60 seconds to complete due to Unity Editor interactions.

Building from Source

Prerequisites

• C Compiler: Required for building aws - lc - rs dependency
  • Windows: MSVC (Visual Studio Build Tools)
  • macOS: Xcode Command Line Tools (xcode - select --install)
  • Linux: GCC (sudo apt - get install build - essential on Ubuntu/Debian)
• CMake: Required for building the aws - lc - rs dependency
  • Windows: Follow the [official guide](https://aws.github.io/aws - lc - rs/requirements/windows.html)
  • macOS: brew install cmake
  • Linux: sudo apt - get install cmake (Ubuntu/Debian)

Build Commands

# Debug build
cargo build

# Release build (recommended for production)
cargo build --release

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository.
2. Create a feature branch.
3. Run tests with cargo test -- --test - threads = 1.
4. Submit a pull request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• Visual Studio Code Editor for Unity - Required Unity package.
• Model Context Protocol - The protocol specification.
• [Unity Code Pro VS Code Extension](https://github.com/hackerzhuli/unity - code) - VS Code extension that is related.