x000D DO NOT USE THIS. THIS IS A TOY PROJECT TO SEE WHAT I CAN DO WITH CLAUDE CODE.x000D I'M TRYING TO ASSESS IF A DEV CAN CORRECTLY WORK WITH JUST VIBE CODING_x000D_ SO FAR, IT SEEMS NOT TO BE THE CASE !x000D x000D x000D A Unity Master Control Protocol (MCP) implementation that allows AI agents to control and interact with Unity.x000D x000D

Overview_x000D_

x000D 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.x000D x000D 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.x000D x000D Key components include:x000D x000D 1. Unity MCP Plugin (Server) – A C# plugin integrated into the Unity Editor that hosts a TCP server_x000D_ 2. FastMCP Python Client – A Python application that implements the MCP interface for Unity_x000D_ 3. MCP Client (AI or External) – The external entity (such as an AI assistant or testing script) that sends MCP requests_x000D_ x000D

What is MCP?x000D

x000D 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:x000D x000D - Resources: Providing data to LLMs (like Unity scene hierarchies)x000D - Tools: Allowing LLMs to take actions (like executing code in Unity)x000D - Prompts: Defining interaction templates (like how to create GameObjects)x000D x000D YetAnotherUnityMcp implements the official MCP specification with full compliance, including:x000D - Content-array based responses_x000D_ - URI-based resource descriptors_x000D_ - Required parameter arrays at schema level_x000D_ - MIME type specifications for resources_x000D_ x000D

Features_x000D_

x000D - Execute C# code in Unity from AI agents_x000D_ - Query Unity Editor state through MCP resources with dynamic parameter handling_x000D_ - Organize MCP resources and tools in logical containers for better organization_x000D_ - Capture screenshots with AI-driven parameters_x000D_ - Get logs and debug information from Unity with real-time monitoring and incremental retrieval_x000D_ - Modify GameObject properties with AI assistance_x000D_ - List and navigate GameObject hierarchies_x000D_ - Provide contextual templates through MCP prompts_x000D_ - Real-time communication via TCP sockets_x000D_ - TCP server hosted directly in Unity_x000D_ - Fast, efficient JSON serialization_x000D_ - Dynamic resource invocation with type-safe parameter mapping_x000D_ - Schema-based input validation for tools and resources_x000D_ x000D

Getting Started_x000D_

x000D

Unity Server Setup_x000D_

x000D 1. Open your Unity project (2020.3 or later)x000D 2. Import the YetAnotherUnityMcp plugin using one of these methods:x000D - Copy the plugin/Scripts folder to your Unity project's Assets directory_x000D_ - Create a Unity package and import it_x000D_ - Create a symbolic link for development (Windows PowerShell example):x000D powershell_x000D_ New-Item -ItemType SymbolicLink -Target "D:DevYetAnotherUnityMcpplugin" -Path "C:UsersazreaMy projectAssetsPluginsYetAnotherUnityMcp"_x000D_x000D 3. Start the TCP server:x000D - From the menu: MCP > TCP Server > Start Server_x000D_ - Or: Window > MCP Server > Start Server_x000D_ 4. Note the TCP server address (default: localhost:8080)x000D x000D

Python Client Setup_x000D_

x000D ```bash_x000D_

Clone the repository_x000D_

git clone https://github.com/yourusername/YetAnotherUnityMcp.git_x000D_ cd YetAnotherUnityMcp_x000D_ x000D

Create and activate a virtual environment using uv_x000D_

uv venv -p 3.11_x000D_ source .venv/bin/activate # On Windows: .venvScriptsactivate_x000D_ x000D

Install the server with development dependencies_x000D_

uv pip install -e ".[dev]"x000D x000D

Run the MCP client_x000D_

python -m server.mcp_server_x000D_ ```x000D x000D

MCP Integration_x000D_

x000D ```bash_x000D_

Install FastMCP and tools_x000D_

uv pip install fastmcp_x000D_ x000D

Run the client with MCP inspector for debugging_x000D_

fastmcp dev server/mcp_server.py_x000D_ x000D

Install in Claude Desktop_x000D_

fastmcp install server/mcp_server.py --name "Unity Controller"x000D ```x000D x000D

Project Structure_x000D_

x000D _x000D_ YetAnotherUnityMcp/_x000D_ ├── server/ # Python MCP client_x000D_ │ ├── unity_client_util.py # Unity client utility functions_x000D_ │ ├── unity_tcp_client.py # High-level Unity TCP client_x000D_ │ ├── mcp_server.py # MCP server implementation_x000D_ │ ├── dynamic_tool_invoker.py # Dynamic tool invocation system_x000D_ │ ├── dynamic_tools.py # Dynamic tool manager_x000D_ │ ├── connection_manager.py # Connection lifecycle management_x000D_ │ └── websocket_client.py # Low-level TCP client (legacy name)_x000D_ ├── plugin/ # Unity C# plugin_x000D_ │ ├── Scripts/ # Plugin source code_x000D_ │ │ ├── Editor/ # Editor extensions_x000D_ │ │ │ ├── Commands/ # Editor command implementations_x000D_ │ │ │ ├── MCPWindow.cs # Server control window_x000D_ │ │ │ ├── MCPMenu.cs # Unity menu integration_x000D_ │ │ │ ├── MCPTcpServer.cs # Primary TCP server implementation_x000D_ │ │ │ ├── CommandExecutionMonitor.cs # Performance monitoring_x000D_ │ │ │ ├── Models/ # Data models for Editor_x000D_ │ │ │ └── Net/ # TCP communication implementation_x000D_ │ │ └── YetAnotherUnityMcp.asmdef # Assembly definition_x000D_ │ └── README.md # Plugin documentation_x000D_ └── tests/ # Test suite_x000D_x000D x000D

Architecture_x000D_

x000D

Unity TCP Server_x000D_

x000D The Unity plugin hosts a TCP server that listens for connections from MCP clients. This server:x000D x000D - Manages client connections and message routing with a simple framing protocol_x000D_ - Supports handshake and ping/pong for connection health monitoring_x000D_ - Uses a dynamic registry of tools and resources with reflection-based attribute discovery_x000D_ - Provides invokers for dynamically accessing resources and tools by name_x000D_ - Supports container-based organization of tools and resources_x000D_ - Executes commands sent by clients (e.g., running C# code, taking screenshots)x000D - Returns results back to clients_x000D_ - Provides a UI for monitoring connections and debugging_x000D_ x000D For detailed information about the container-based approach, see the MCP Container Documentation.x000D x000D

Python MCP Client_x000D_

x000D The Python client connects to the Unity TCP server and provides an MCP interface for AI tools. It:x000D x000D - Translates MCP requests into framed TCP messages for Unity_x000D_ - Handles connection retries and keep-alive pings_x000D_ - Converts Unity responses into MCP resource data_x000D_ - Uses FastMCP's lifespan management for connection lifecycle_x000D_ - Provides standardized error handling and reconnection logic_x000D_ - Implements a unified execution pattern for all operations_x000D_ - Provides tools and resources through the FastMCP framework_x000D_ x000D

MCP Resources and Tools_x000D_

x000D

Resources_x000D_

x000D - unity://info - Basic information about the Unity environment_x000D_ - unity://logs - Editor logs for debugging_x000D_ - unity://scene/{scene_name} - Information about a specific scene_x000D_ - unity://object/{object_id} - Details about a specific GameObject_x000D_ x000D

Tools_x000D_

x000D - execute_code_in_unity - Run C# code in the Unity Editor_x000D_ - unity_screenshot - Take screenshots of the Unity Editor_x000D_ - unity_modify_object - Change properties of Unity GameObjects_x000D_ - unity_logs - Get logs from Unity with option to retrieve only new logs_x000D_ x000D

Communication Protocol_x000D_

x000D 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).x000D x000D The protocol uses a simple framing mechanism:x000D - Start marker (STX, 0x02)x000D - 4-byte length prefix_x000D_ - JSON message content_x000D_ - End marker (ETX, 0x03)x000D x000D 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.x000D x000D

Development_x000D_

x000D ```bash_x000D_

Python client development_x000D_

python -m pytest # Run tests_x000D_ python -m black . # Format code_x000D_ python -m flake8 # Lint code_x000D_ python -m mypy . # Type check_x000D_ x000D

MCP Development_x000D_

fastmcp dev server/mcp_server.py # Run with MCP Inspector UI_x000D_ x000D

Unity server development_x000D_

Use the MCP Server window in Unity for debugging_x000D_

Monitor connections and messages in real-time_x000D_

```x000D x000D

License_x000D_

x000D This project is licensed under the MIT License - see the LICENSE file for details.x000D x000D For more details on architecture, implementation, and extensibility, see the Technical Details document.