realvirtual Unity MCP — with Game Creator 2 tools

Fork of game4automation/io.realvirtual.mcp that adds first-class Game Creator 2 (GC2) authoring over MCP. The upstream package is unmodified — the GC2 tools live in Editor/GameCreator2/. Upstream: MIT © realvirtual GmbH. GC2 additions: MIT © 2026 wethecom (not affiliated with realvirtual GmbH).

🎮 Game Creator 2 over MCP — the headline feature

Generic component_get/component_set can't touch most of Game Creator 2's data, because GC2 stores its visual scripting in [SerializeReference] polymorphic fields. This fork makes that data fully AI-authorable over MCP — an agent can build GC2 logic without ever opening the Inspector:

• Build Instruction lists — add / list / remove Instructions in any InstructionList (Triggers, Actions, enter/exit lists, …).
• Set polymorphic fields — point a PropertyGetGameObject at self / player / any scene object, or set any [SerializeReference] field (e.g. a Trigger's m_Event to an Event subclass, a Condition, a Property type).
• Wire Triggers, Conditions, Events, and Properties programmatically.
• Copy components & whole GameObject subtrees (values + object references, animation clips, full hierarchies) between objects.

GC2 tool	Purpose
gc2_add_instruction · gc2_list_instructions · gc2_remove_instruction	manage GC2 InstructionLists (list reads are a crash-safe alternative to component_get)
gc2_set_instruction_game_object	set an instruction's PropertyGetGameObject to self / player / a scene object
gc2_set_managed_reference	set any [SerializeReference] field by path to a named type — Events, Conditions, Properties
gc2_copy_instructions	copy whole instruction sets between lists, deep-cloning nested data (uses GC2's own copy mechanism)
gc2_add_name_variable · gc2_list_name_variables · gc2_remove_name_variable	full CRUD for Local/Global Name Variables — create/update (sets game-object / asset / string / number / bool values), read, delete
gc2_create_quest	create a GC2 Quest asset (title, description, tasks)
gc2_create_dialogue	add a GC2 Dialogue and build a conversation from text lines (optional per-line speaker Actor)
component_copy · game_object_copy	clone components / whole GameObject subtrees (values + refs)
asset_duplicate · asset_reserialize	clone an asset/folder (fresh GUIDs + ref remap); reserialize to fix cached hashes after a YAML edit
cleanup_missing_scripts	strip "missing script" slots from prefabs/scene project-wide (e.g. after removing a package)

➡️ Full Game Creator 2 docs & examples: Editor/GameCreator2/README.md

Sample: Dialogue From Text

Samples~/DialogueFromText — a runtime GC2 feature built with these tools: parses a plain-text script into a real branching, playable Dialogue, with speakers resolved by name from a Name Variables "cast" (adds a ValueActor variable type so a Name Variable can hold a Dialogue Actor). Kept as a sample because it depends on the GC2 Dialogue/Variables modules.

---

The rest of this README documents the underlying MCP server (forked from upstream).

Give AI agents full control over your Unity Editor — scenes, GameObjects, components, simulation, and more.

This open-source Unity package implements a Model Context Protocol (MCP) server that lets AI agents like Claude, Cursor, or any MCP-compatible client interact with Unity in real time. It works with any Unity project; this fork is focused on game development with Game Creator 2 (see the top of this README).

Why This MCP Server Is Different

Most MCP servers for Unity require you to edit Python code every time you add a new tool. This one doesn't. You define tools entirely in C# with a simple attribute - the Python server discovers them automatically:

[McpTool("Spawn an enemy at position")]
public static string SpawnEnemy(
    [McpParam("Prefab name")] string prefab,
    [McpParam("X position")] float x,
    [McpParam("Z position")] float z)
{
    // Your Unity code here - runs on main thread
}

That's it. No Python changes, no server restart, no tool registration. Just recompile in Unity and the AI agent sees your new tool.

Key advantages:

• Works with any Unity project - Not tied to a specific framework or asset. Install it in any project and start adding AI-controllable tools
• Zero Python knowledge needed - Define tools in C#, the language you're already using
• Auto-discovery - Tools are found via reflection, no manual registration
• 60+ built-in tools - Scene, GameObjects, components, transforms, simulation, screenshots, prefabs, and more
• Extensible in minutes - Add [McpTool] to any static method and it's available to AI agents
• Self-contained - Ships with embedded Python 3.12, no system Python required
• One-click setup - Download Python + configure Claude from the Unity toolbar
• Survives domain reloads - Auto-reconnects after Unity recompiles scripts
• Multi-instance support - Run multiple Unity instances, each with its own MCP server

Architecture

AI Agent (Claude Desktop / Claude Code / Cursor)
    |
    | MCP Protocol (stdio or SSE)
    v
Python MCP Server  -->  github.com/game4automation/realvirtual-MCP
    |
    | WebSocket (JSON, Port 18711)
    v
This Unity Package (C# WebSocket server + tool registry)

Installation

Via Unity Package Manager (Git URL)

1. Open Unity Window > Package Manager
2. Click + > Add package from git URL
3. Enter: https://github.com/wethecom/io.realvirtual.mcp.git (this fork — includes the Game Creator 2 tools)

Updating

Unity caches git packages by commit hash. To get the latest version:

1. Open Window > Package Manager
2. Select realvirtual MCP Server
3. Click Update (if available)

If no update button appears, remove the lock entry for io.realvirtual.mcp from Packages/packages-lock.json and reopen Unity.

Requirements

• Unity 6000.0+
• Newtonsoft JSON (com.unity.nuget.newtonsoft-json)
• git must be installed and available in PATH (for Python server download/update) — git-scm.com

Setup

Automated Setup (recommended)

After installing the Unity package:

1. A brain icon appears in the Unity toolbar - this is the MCP status indicator
2. Click the gear icon next to it to open the setup popup
3. Click Clone Python Server - this runs git clone to download the Python server (~70 MB) into Assets/StreamingAssets/realvirtual-MCP/
4. Click Configure Claude - this writes the MCP configuration to Claude Desktop and/or Claude Code

To update later, click Update Python Server (git pull) in the same popup.

You can also access setup via the Unity menu: Tools > realvirtual > MCP

Manual Setup

If you prefer to set up manually or the automated setup doesn't work:

1. Clone the Python server repository:

   cd <your-project>/Assets/StreamingAssets
   git clone https://github.com/game4automation/realvirtual-MCP.git

2. To update later:

   cd <your-project>/Assets/StreamingAssets/realvirtual-MCP
   git pull

3. Configure your MCP client manually (see Python MCP Server for configuration details)

The Python MCP server is available separately at github.com/game4automation/realvirtual-MCP.

How It Works

This package runs a WebSocket server inside the Unity Editor. When an AI agent sends a tool call, the Python MCP server forwards it over WebSocket to Unity, which executes it on the main thread and returns the result.

Key components:

• McpWebSocketHandler - WebSocket server (port 18711, auto-increments if busy)
• McpToolRegistry - Discovers all [McpTool] methods via reflection at startup
• McpMainThreadDispatcher - Bridges WebSocket threads to Unity's main thread
• McpEditorBridge - Auto-starts the server when Unity opens ([InitializeOnLoad])
• McpToolbarButton - Status indicator with color-coded connection state

Built-in Tools

The package includes 60+ tools organized by category:

Category	Examples
Simulation	sim_play, sim_stop, sim_pause, sim_status
Scene	scene_hierarchy, scene_find, scene_get_info
GameObjects	game_object_create, game_object_destroy, game_object_rename
Components	component_get, component_set, component_add, component_remove
Transforms	transform_set_position, transform_set_rotation, transform_set_scale
Materials	material_set_color, material_get_color
Physics	physics_add_rigidbody, physics_add_collider
Prefabs	prefab_instantiate, prefab_find, prefab_open, prefab_save
Editor	editor_recompile, editor_read_log, editor_save_scene, editor_wait_ready
Screenshots	screenshot_editor, screenshot_game, screenshot_scene
Game Creator 2	gc2_add_instruction, gc2_add_name_variable, gc2_create_dialogue, gc2_create_quest, … (see top)

Creating Custom Tools

Add [McpTool] to any public static string method. Tools are discovered automatically via reflection - no registration needed.

using realvirtual.MCP;

public static class MyTools
{
    [McpTool("Get current time")]
    public static string GetTime()
    {
        return $"{{\"time\":\"{System.DateTime.Now}\"}}";
    }

    [McpTool("Add two numbers")]
    public static string Add(
        [McpParam("First number")] float a,
        [McpParam("Second number")] float b)
    {
        return $"{{\"result\":{a + b}}}";
    }
}

Rules:

• Method must be public static and return string (JSON)
• Tool names auto-convert from PascalCase to snake_case (GetTime -> get_time)
• Use [McpParam("description")] on parameters for AI agent context
• Optional parameters need default values
• Use ToolHelpers.FindGameObject(), ToolHelpers.Ok(), ToolHelpers.Error() for common patterns

Toolbar Status

The toolbar brain icon shows connection state:

Color	Meaning
Gray	Server stopped
Yellow	Server running, no clients connected
Green	Client(s) connected
Orange	Unity compiling scripts

The activity label next to it shows the currently executing tool with elapsed time.

Troubleshooting

Server not starting

• Check Unity Console for [MCP] log entries
• Toggle debug mode via the gear popup for verbose logging

Tools not discovered

• Ensure methods are public static string with [McpTool] attribute
• Check for compile errors in Unity Console
• Click "Refresh" in the toolbar popup

Timeouts during play mode

• Unity throttles editor updates in play mode - tool calls may be slower
• Some operations (component_set) don't work during play mode

Python MCP Server

The Python server that bridges MCP clients to this Unity package is maintained separately:

github.com/game4automation/realvirtual-MCP

It ships with an embedded Python 3.12 runtime and can be downloaded directly from the Unity toolbar popup.

Support

This package is provided as-is with no support or service included.

License

MIT License — the upstream MCP server is © 2026 realvirtual GmbH; the Game Creator 2 additions in this fork are © 2026 wethecom. Not affiliated with or endorsed by realvirtual GmbH or the Game Creator team.

See LICENSE.md for full text.

Links

• This fork: https://github.com/wethecom/io.realvirtual.mcp
• Upstream MCP server: https://github.com/game4automation/io.realvirtual.mcp
• Python MCP Server (bridge): https://github.com/game4automation/realvirtual-MCP