UnityRuntimeMCP
pokelege/UnityRuntimeMCP
UnityRuntimeMCP is an implementation of the Model Context Protocol (MCP) as a BepInEx 6 plugin for Unity IL2CPP games. It enables external AI agents to interact with the game runtime via reflection-based tools.
Instalação
npx convez-ai pokelege/UnityRuntimeMCP1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
UnityRuntimeMCP
UnityRuntimeMCP is an implementation of the Model Context Protocol (MCP) as a BepInEx 6 plugin for Unity IL2CPP games. It enables external AI agents to interact with the game runtime via reflection-based tools.
Features
- Live Inspection & Object Caching: Discovery and inspection of Unity
GameObject/Componentinstances, as well as non-Unity reference types (classes and arrays). - Stable Identity Mapping: Maintains a weak-reference cache of all encountered Unity Objects and non-Unity reference types. Non-Unity objects are assigned dynamic IDs starting at
1,000,000,000to guarantee reference stability across frames. - Deep Reflection & Serialization: Access to fields, properties, and methods on derived types in IL2CPP environments. Automatically serializes collections and arrays up to 20 elements, caching nested non-Unity objects for further inspection.
- Runtime Modification: Reading and writing values to object fields and properties with support for nested dot-notation paths.
- Visual Feedback: Capture of game view screenshots in Base64 PNG format or saved to a cross-platform temporary directory.
- Thread Safety: Automatic dispatching of Unity API calls to the main thread.
- Lifecycle Management: Protection against scene cleanup and IL2CPP-specific object destruction.
Provided Tools
The server registers the following MCP tools:
| Tool | Description |
|---|---|
find_objects | Finds active GameObjects by class name. Returns identity objects with instance_id. Returns an empty list if the class is missing. |
get_hierarchy | Returns immediate parent and children IDs for Unity GameObjects/Components. Restricted to Unity objects. |
inspect_object | Detailed member view. Supports Unity and cached non-Unity objects. include_methods defaults to false for efficiency. |
read_field | Reads a value. Supports dot-notation paths (e.g., transform.parent.name). Returns null for broken paths. |
write_field | Writes a value. Supports nested paths. Suggests preferring property setters over private backing fields to ensure side-effects execute. |
invoke_method | Executes a method on Unity or cached non-Unity objects. Supports generic methods via type_args. |
take_screenshot | Captures the game screen. Supports scale (0.1 to 1.0, default 0.5) and save_to_file (boolean). Uses a stable custom pipeline to avoid IL2CPP native JPG crash. |
Feature Highlights
- Identity Mapping & Cache: The server maintains a weak-reference cache of all encountered Unity Objects and non-Unity reference types (assigned dynamic IDs >= 1,000,000,000). This ensures that
instance_idreferences remain stable across frames, even for objects that are inactive or difficult to locate via standard searches. - Robust Path Traversal: Dot-notation support in
read_fieldandwrite_fieldallows for deep inspection in a single call. The system handles null segments gracefully, returning standard JSONnullinstead of errors. - Generic Method Resolution: Agents can invoke generic Unity methods by providing
type_args(a list of full type names), enabling advanced operations likeGetComponent<TextMeshProUGUI>(). - Custom Screenshot Engine: Avoids native IL2CPP
AccessViolationExceptioncrashes by bypassing the nativeEncodeToJPGdelegate. Instead, it blits the native screen buffer to a scaledRenderTextureand encodes it to a PNG. Scaled output reduces payload size, and settingsave_to_filesaves directly to the system temp directory (C:\Users\Public\UnityRuntimeMCP_Tempon Windows,/tmp/UnityRuntimeMCP_Tempon macOS/Linux).
Installation
- Install BepInEx 6 (IL2CPP) in the target game.
- Place
UnityRuntimeMCP.dllin theBepInEx/pluginsdirectory. - Launch the game; the MCP server initializes on the configured port.
Configuration
Configuration is managed via BepInEx/config/me.pokelege.unityruntimemcp.cfg:
Port: Server listening port (Default: 3000).Host: Server binding address (Default: 127.0.0.1).
Building
If you are not using a pre-built release, you can build the plugin from source:
Prerequisites
- .NET 6.0 SDK
- Unity game assemblies placed in the
libs/directory (these are already included in the repository for reference).
Build Commands
To build the project, run one of the following commands in the project root:
-
Debug Build:
dotnet buildThe compiled DLL will be located at
bin/Debug/net6.0/UnityRuntimeMCP.dll. -
Release Build:
dotnet build -c ReleaseThe compiled DLL will be located at
bin/Release/net6.0/UnityRuntimeMCP.dll.
Connection
The server utilizes HTTP/SSE transport.
Client Configuration
MCP clients should connect to the following endpoint:
http://127.0.0.1:3000/mcp
Technical Specifications
- Protocol: JSON-RPC 2.0 over Server-Sent Events (SSE).
- Initialization: Requires standard MCP initialize handshake.
- Session Management: Supports request ID tracking for JSON-RPC compliance.
Technical Architecture
- Main Thread Dispatcher: A persistent MonoBehaviour managing a thread-safe execution queue.
- IL2CPP Bridge: Custom type resolution mapping IL2CPP internal types to managed System.Type for reflection accuracy.
- Modular Design: Tool implementations are decoupled for extensibility.
Prohibited Use
This software is provided for research and development purposes. Use of this software to facilitate cheating in multiplayer or online games is strictly prohibited. Users assume all risk regarding detection by anti-cheat systems and subsequent account actions.
License
This project is licensed under the GNU Lesser General Public License v2.1. See the LICENSE file for the full license text and disclaimer.