YetAnotherUnityMcp
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Integrations
Interfaces with Unity's .NET/C# environment through a plugin that acts as the MCP client, allowing execution of C# code and manipulation of Unity objects.
Implements the MCP server in Python using FastMCP, providing a bridge between AI agents and the Unity engine.
Allows AI agents to control and interact with the Unity game engine by executing C# code, querying editor state, capturing screenshots, modifying GameObject properties, and navigating scene hierarchies in real-time via WebSockets.
YetAnotherUnityMcp
DO NOT USE THIS. THIS IS A TOY PROJECT TO SEE WHAT I CAN DO WITH CLAUDE CODE. I'M TRYING TO ASSESS IF A DEV CAN CORRECTLY WORK WITH JUST VIBE CODING SO FAR, IT SEEMS NOT TO BE THE CASE !
A Unity Master Control Protocol (MCP) implementation that allows AI agents to control and interact with Unity.
Overview
YetAnotherUnityMcp is a system that bridges the Unity game engine with AI-driven tools using the Model Context Protocol (MCP). It consists of a Unity .NET/C# plugin acting as the MCP TCP server, and a Python MCP client (built with FastMCP) that handles requests from AI agents. Communication between Unity and the client is done via a custom TCP protocol, enabling real-time, bidirectional exchange of JSON messages and image data.
This architecture cleanly separates the game engine concerns from the AI logic, improving scalability and maintainability. The goal is to allow AI agents (e.g. an LLM-based assistant) to inspect and control a running Unity scene in a structured, safe manner. The container-based approach for organizing resources and tools further improves code organization and reduces boilerplate.
Key components include:
- Unity MCP Plugin (Server) – A C# plugin integrated into the Unity Editor that hosts a TCP server
- FastMCP Python Client – A Python application that implements the MCP interface for Unity
- MCP Client (AI or External) – The external entity (such as an AI assistant or testing script) that sends MCP requests
What is MCP?
The Model Context Protocol (MCP) is a standardized way for AI models to interact with applications. It separates the concerns of providing context from the LLM interaction itself, allowing for:
- Resources: Providing data to LLMs (like Unity scene hierarchies)
- Tools: Allowing LLMs to take actions (like executing code in Unity)
- Prompts: Defining interaction templates (like how to create GameObjects)
YetAnotherUnityMcp implements the official MCP specification with full compliance, including:
- Content-array based responses
- URI-based resource descriptors
- Required parameter arrays at schema level
- MIME type specifications for resources
Features
- Execute C# code in Unity from AI agents
- Query Unity Editor state through MCP resources with dynamic parameter handling
- Organize MCP resources and tools in logical containers for better organization
- Capture screenshots with AI-driven parameters
- Get logs and debug information from Unity with real-time monitoring and incremental retrieval
- Modify GameObject properties with AI assistance
- List and navigate GameObject hierarchies
- Provide contextual templates through MCP prompts
- Real-time communication via TCP sockets
- TCP server hosted directly in Unity
- Fast, efficient JSON serialization
- Dynamic resource invocation with type-safe parameter mapping
- Schema-based input validation for tools and resources
Getting Started
Unity Server Setup
- Open your Unity project (2020.3 or later)
- 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):Copy
- Copy the
- Start the TCP server:
- From the menu: MCP > TCP Server > Start Server
- Or: Window > MCP Server > Start Server
- Note the TCP server address (default: localhost:8080)
Python Client Setup
MCP Integration
Project Structure
Architecture
Unity TCP Server
The Unity plugin hosts a TCP server that listens for connections from MCP clients. This server:
- Manages client connections and message routing with a simple framing protocol
- Supports handshake and ping/pong for connection health monitoring
- Uses a dynamic registry of tools and resources with reflection-based attribute discovery
- Provides invokers for dynamically accessing resources and tools by name
- Supports container-based organization of tools and resources
- Executes commands sent by clients (e.g., running C# code, taking screenshots)
- Returns results back to clients
- Provides a UI for monitoring connections and debugging
For detailed information about the container-based approach, see the MCP Container Documentation.
Python MCP Client
The Python client connects to the Unity TCP server and provides an MCP interface for AI tools. It:
- Translates MCP requests into framed TCP messages for Unity
- Handles connection retries and keep-alive pings
- Converts Unity responses into MCP resource data
- Uses FastMCP's lifespan management for connection lifecycle
- Provides standardized error handling and reconnection logic
- Implements a unified execution pattern for all operations
- Provides tools and resources through the FastMCP framework
MCP Resources and Tools
Resources
unity://info
- Basic information about the Unity environmentunity://logs
- Editor logs for debuggingunity://scene/{scene_name}
- Information about a specific sceneunity://object/{object_id}
- Details about a specific GameObject
Tools
execute_code_in_unity
- Run C# code in the Unity Editorunity_screenshot
- Take screenshots of the Unity Editorunity_modify_object
- Change properties of Unity GameObjectsunity_logs
- Get logs from Unity with option to retrieve only new logs
Communication Protocol
All communication between the Unity server and the Python client uses a TCP socket connection with a simple framing protocol, which allows persistent, low-latency bidirectional messaging. The connection is initiated by the Python client to the Unity server's TCP endpoint (e.g. localhost:8080
).
The protocol uses a simple framing mechanism:
- Start marker (STX, 0x02)
- 4-byte length prefix
- JSON message content
- End marker (ETX, 0x03)
Every message is a JSON object containing at least a command or response type, a unique ID (to pair requests with responses), and a parameters or result object. The connection is maintained with periodic ping/pong messages. For more details on the communication protocol, see the Technical Details document.
Development
License
This project is licensed under the MIT License - see the LICENSE file for details.
For more details on architecture, implementation, and extensibility, see the Technical Details document.
This server cannot be installed
A Unity Master Control Protocol implementation that allows AI agents to control and interact with Unity, enabling them to execute code, query editor state, modify GameObjects, and capture screenshots through a WebSocket-based communication system.
- Overview
- What is MCP?
- Features
- Getting Started
- Project Structure
- Architecture
- MCP Resources and Tools
- Communication Protocol
- Development
- License