Unity Game Engine MCP server

YetAnotherUnityMcp is a system that bridges the Unity game engine with AI-driven tools using the Model Context Protocol (MCP). It enables AI agents to inspect and control a running Unity scene through a TCP server hosted directly in Unity, with a Python client that handles the AI interaction.

Installation

Unity Server Setup

1. Open your Unity project (2020.3 or later)
2. Import the YetAnotherUnityMcp plugin using one of these methods:
   • Copy the plugin/Scripts folder to your Unity project's Assets directory
   • Create a Unity package and import it
   • Create a symbolic link for development (Windows PowerShell example):

     New-Item -ItemType SymbolicLink -Target "D:\Dev\YetAnotherUnityMcp\plugin" -Path "C:\Users\azrea\My project\Assets\Plugins\YetAnotherUnityMcp"
     

3. Start the TCP server:
   • From the menu: MCP > TCP Server > Start Server
   • Or: Window > MCP Server > Start Server
4. Note the TCP server address (default: localhost:8080)

Python Client Setup

# Clone the repository
git clone https://github.com/yourusername/YetAnotherUnityMcp.git
cd YetAnotherUnityMcp

# Create and activate a virtual environment using uv
uv venv -p 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the server with development dependencies
uv pip install -e ".[dev]"

# Run the MCP client
python -m server.mcp_server

MCP Integration

# Install FastMCP and tools
uv pip install fastmcp

# Run the client with MCP inspector for debugging
fastmcp dev server/mcp_server.py

# Install in Claude Desktop
fastmcp install server/mcp_server.py --name "Unity Controller"

Usage

Available MCP Resources

The MCP server provides several resources that can be queried:

• unity://info - Basic information about the Unity environment
• unity://logs - Editor logs for debugging
• unity://scene/{scene_name} - Information about a specific scene
• unity://object/{object_id} - Details about a specific GameObject

Available MCP Tools

You can use these tools to interact with Unity:

• execute_code_in_unity - Run C# code in the Unity Editor
• unity_screenshot - Take screenshots of the Unity Editor
• unity_modify_object - Change properties of Unity GameObjects
• unity_logs - Get logs from Unity

Example Usage

Executing C# Code in Unity

You can use the MCP client to execute C# code directly in Unity:

# Example using the MCP client to execute code
from fastmcp import MCPClient

async with MCPClient() as client:
    result = await client.use_tool(
        "execute_code_in_unity", 
        {
            "code": "Debug.Log(\"Hello from MCP!\"); return GameObject.FindObjectsOfType<GameObject>().Length;"
        }
    )
    print(f"Number of GameObjects: {result}")

Taking Screenshots

To capture the current Unity scene:

async with MCPClient() as client:
    screenshot = await client.use_tool(
        "unity_screenshot",
        {
            "width": 1280,
            "height": 720,
            "camera": "Main Camera"  # Optional: specific camera name
        }
    )
    # Screenshot is returned as base64 encoded image
    with open("unity_screenshot.png", "wb") as f:
        f.write(base64.b64decode(screenshot["image_data"]))

Modifying GameObjects

To modify properties of a GameObject in Unity:

async with MCPClient() as client:
    # First get information about available objects
    scene_info = await client.get_resource("unity://scene/SampleScene")
    
    # Then modify a specific object
    result = await client.use_tool(
        "unity_modify_object",
        {
            "object_id": scene_info["objects"][0]["id"],
            "position": {"x": 0, "y": 2, "z": 0},
            "rotation": {"x": 0, "y": 45, "z": 0},
            "scale": {"x": 2, "y": 2, "z": 2}
        }
    )

Communication Protocol

All communication between the Unity server and the Python client uses a TCP socket connection with a simple framing protocol for persistent, low-latency bidirectional messaging:

• Every message has start marker (STX, 0x02), 4-byte length prefix, JSON content, and end marker (ETX, 0x03)
• Messages contain a command/response type, unique ID, and parameters/result object
• The connection is maintained with periodic ping/pong messages

This allows for real-time interaction with Unity from AI agents or other external systems.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.