MCP HubMCP Hub
Azreal42

YetAnotherUnityMcp

by: Azreal42

Yet Another Unity Mcp client / server

6created 16/03/2025
Visit
Unity
client

📌Overview

Purpose: To create a bridge between the Unity game engine and AI agents using the Model Context Protocol (MCP), enabling real-time interaction and control within a Unity environment.

Overview: YetAnotherUnityMcp is a system designed to facilitate communication between AI tools and the Unity game engine through a TCP server implemented in C#. It enables the execution of commands, retrieval of information, and manipulation of Unity scenes by AI agents via a Python client, all while maintaining a structured separation of AI logic from game engine operations.

Key Features:

  • Execute C# code in Unity: Allows AI agents to run arbitrary C# scripts, enabling dynamic interactions within the game environment.

  • Query Unity Editor state: Provides a means for AI to retrieve and utilize the current state and properties of Unity objects through dynamically managed resources.

  • Real-time communication via TCP: Establishes a persistent connection for low-latency data exchange between Unity and the client, enhancing responsiveness and reliability in AI interactions.

  • MCP compliance: Fully adheres to the Model Context Protocol standards, ensuring structured and standardized communications, including type-safe parameter mapping and resource handling.

  • Dynamic resource management: Uses a container-based approach to organize MCP resources, promoting better maintainability and reduced boilerplate code for developers.

YetAnotherUnityMcp

DO NOT USE THIS. This is a toy project created to explore capabilities with the Model Context Protocol (MCP).

Overview

YetAnotherUnityMcp is a system connecting the Unity game engine with AI-driven tools using the Model Context Protocol (MCP). It includes a Unity .NET/C# plugin functioning as the MCP TCP server and a Python MCP client that processes requests from AI agents. Communication is facilitated through a custom TCP protocol, enabling real-time exchange of JSON messages.

The design enhances scalability and maintainability by separating game engine concerns from AI logic. The aim is to allow AI agents to inspect and control a Unity scene safely.

Key Components

  1. Unity MCP Plugin (Server) – C# plugin hosting a TCP server in Unity.
  2. FastMCP Python Client – Python application implementing the MCP interface for Unity.
  3. MCP Client – External entities, such as AI assistants, that send MCP requests.

Features

  • Execute C# code in Unity from AI agents.
  • Query Unity Editor state through dynamic MCP resources.
  • Organize MCP resources in logical containers.
  • Capture screenshots.
  • Retrieve logs and debug information from Unity.
  • Modify GameObject properties with AI assistance.
  • Navigate GameObject hierarchies.
  • Provide contextual templates through MCP prompts.
  • Real-time communication via TCP sockets.

Getting Started

Unity Server Setup

  1. Open your Unity project (2020.3 or later).
  2. Import the YetAnotherUnityMcp plugin via one of the listed methods.
  3. Start the TCP server:
    • From the menu: MCP > TCP 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
uv venv -p 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e "."[dev]"

# Run the MCP client
python -m server.mcp_server

MCP Integration

# Install FastMCP
uv pip install fastmcp

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

Project Structure

YetAnotherUnityMcp/
├── server/                      # Python MCP client
│   ├── unity_client_util.py     
│   ├── unity_tcp_client.py      
│   ├── mcp_server.py            
│   ├── dynamic_tool_invoker.py  
│   ├── connection_manager.py    
│   └── websocket_client.py      
├── plugin/                      # Unity C# plugin
│   ├── Scripts/                 # Plugin source code
│   └── YetAnotherUnityMcp.asmdef 
└── tests/                       # Test suite

Architecture

Unity TCP Server

The Unity plugin hosts a TCP server managing client connections and message routing, supporting health monitoring and dynamic tool access.

Python MCP Client

The Python client connects to the Unity TCP server, handling MCP requests and responses, and ensuring a unified execution pattern.

MCP Resources and Tools

Resources

  • 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.

Tools

  • execute_code_in_unity - Run C# code in Unity.
  • unity_screenshot - Capture screenshots.
  • unity_modify_object - Change GameObject properties.

Communication Protocol

All communication utilizes a TCP socket with a simple framing protocol, enabling low-latency messaging. The connection begins with the Python client reaching out to the Unity server's TCP endpoint.

The protocol employs a straightforward framing mechanism, ensuring each JSON message identifies command types and contains parameters or results.

Development

# Python client development
python -m pytest                    # Run tests
python -m black .                   # Format code
python -m flake8                    # Lint code
python -m mypy .                    # Type check

# MCP Development
fastmcp dev server/mcp_server.py    # Run with MCP Inspector UI

License

This project is licensed under the MIT License. For further architectural details, refer to the related documents.