English | 한국어

UnityInfoMCP

Unity runtime inspection toolkit for MCP-based automation.

This repository contains two parts:

• UnityInfoMCP: an external Python MCP server
• UnityInfoBridge: an in-game Unity plugin that exposes runtime data over local JSON-RPC

The split is intentional:

• the MCP server can stay alive while games restart
• AI clients keep a stable MCP endpoint
• the game-side bridge can reconnect whenever the game launches again

Port layout

This is the part that matters most in practice:

• MCP server in default HTTP mode: http://127.0.0.1:16000/mcp
• MCP server in stdio mode: no listening socket; the MCP client launches the process directly
• Game bridge: first free port in 127.0.0.1:16001~16100

These are different connections.

• --transport streamable-http uses the HTTP endpoint above
• --transport stdio switches the client-facing transport to stdio
• --port only applies to --transport streamable-http
• UNITY_INFO_BRIDGE_PORT is only a legacy fallback for bridge connection attempts
• bridge auto-discovery still scans 16001~16100
• 16000 is the UnityInfoMCP HTTP port. The in-game UnityInfoBridge plugin itself binds the first free port in 16001~16100.

There are also two separate transport layers:

• Client -> UnityInfoMCP: Streamable HTTP or stdio
• UnityInfoMCP -> UnityInfoBridge: TCP

Repository layout

• UnityInfoMCP The Python MCP package
• UnityInfoBridge The Unity plugin project
• UnityInfoBridge/includes Reference DLLs used to build the bridge
• docs Bridge protocol and tool mapping documents

Supported bridge targets

UnityInfoBridge currently targets:

• BepInEx BE #754+ Mono
• BepInEx BE #754+ IL2CPP
• MelonLoader 0.7.2 Mono
• MelonLoader 0.7.2 IL2CPP

Running the MCP server

Create and activate a virtual environment:

python -m venv .venv
. .venv/Scripts/activate
pip install -e .

For PyInstaller or release builds, install the build extra instead:

pip install -e ".[build]"

Run the MCP server on the default transport and port:

unity-info-mcp

That starts the Streamable HTTP transport on 127.0.0.1:16000 and exposes /mcp.

If the unity-info-mcp command is not found on Windows, use:

python -m UnityInfoMCP

That usually means Python's user Scripts directory is not on PATH. In this environment, the generated launcher is installed at:

C:\Users\USER\AppData\Local\Python\pythoncore-3.12-64\Scripts\unity-info-mcp.exe

Run it on a different port:

unity-info-mcp --port 8080

Run it over stdio instead:

unity-info-mcp --transport stdio

Behavior:

• default MCP transport: Streamable HTTP
• optional MCP transport: stdio via --transport stdio
• default HTTP bind: 127.0.0.1:16000
• default HTTP MCP endpoint: http://127.0.0.1:16000/mcp
• --port is only valid when --transport streamable-http is in use
• startup failure: prints the error; interactive HTTP launches wait for Enter, stdio exits immediately

MCP client configuration

UnityInfoMCP supports both Streamable HTTP and stdio on the client-facing side.

For URL-based MCP clients, connect to:

http://127.0.0.1:16000/mcp

If you launch the server on a custom port, use the matching endpoint instead:

http://127.0.0.1:8080/mcp

For process-launching MCP clients, launch the server in stdio mode:

unity-info-mcp --transport stdio

Bridge-side environment variables are still useful in both modes:

$env:UNITY_INFO_BRIDGE_HOST = "127.0.0.1"
$env:UNITY_INFO_BRIDGE_PORT = "16000"
unity-info-mcp --transport stdio

Important notes:

• UNITY_INFO_BRIDGE_PORT=16000 is only a legacy fallback bridge port
• normal bridge discovery still probes 16001~16100
• --port only affects --transport streamable-http
• --transport stdio does not expose /mcp; the client must speak MCP over the launched process stdio

Recommended auto-launch examples:

Codex config.toml:

[mcp_servers.UnityInfoMCP]
command = "C:\\MCP\\UnityInfoMCP_v1.0.2.exe"
args = ["--transport", "stdio"]
startup_timeout_sec = 45

[mcp_servers.UnityInfoMCP.env]
UNITY_INFO_BRIDGE_HOST = "127.0.0.1"
UNITY_INFO_BRIDGE_PORT = "16000"

Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "UnityInfoMCP": {
      "command": "C:\\MCP\\UnityInfoMCP_v1.0.2.exe",
      "args": ["--transport", "stdio"],
      "env": {
        "UNITY_INFO_BRIDGE_HOST": "127.0.0.1",
        "UNITY_INFO_BRIDGE_PORT": "16000"
      }
    }
  }
}

Direct execution

You can also run UnityInfoMCP directly outside MCP client configuration.

When unity-info-mcp is available on PATH:

unity-info-mcp

When you prefer stdio transport:

unity-info-mcp --transport stdio

When you prefer to invoke the module directly:

python -m UnityInfoMCP

To run the module in stdio mode:

python -m UnityInfoMCP --transport stdio

To bind HTTP on a different port:

unity-info-mcp --port 8080

If you built the PyInstaller executable, you can launch it directly as well:

& "C:\path\to\UnityInfoMCP_v1.0.2.exe"

Or in stdio mode:

& "C:\path\to\UnityInfoMCP_v1.0.2.exe" --transport stdio

In all of these direct-launch cases, UnityInfoMCP starts the selected client-facing transport. Streamable HTTP exposes /mcp on the selected port, while stdio does not bind an HTTP port.

Environment variables

• UNITY_INFO_BRIDGE_TRANSPORT Default: tcp Transport used between UnityInfoMCP and the game-side UnityInfoBridge
• UNITY_INFO_BRIDGE_HOST Default: 127.0.0.1
• UNITY_INFO_BRIDGE_PORT Default: 16000 Legacy fallback bridge port only. Auto-discovery still probes 16001~16100.
• UNITY_INFO_BRIDGE_TIMEOUT_SEC Default: 8.0
• UNITY_INFO_MCP_NAME Default: UnityInfoMCP
• UNITY_INFO_MCP_LOG_LEVEL Default: INFO

Use .env.example as a starting point if needed.

Building UnityInfoBridge

Build inputs:

• bridge references are resolved from UnityInfoBridge/includes
• the project only uses local reference DLLs under: UnityInfoBridge/includes/bepinex/mono UnityInfoBridge/includes/bepinex/il2cpp UnityInfoBridge/includes/melonloader/mono UnityInfoBridge/includes/melonloader/il2cpp UnityInfoBridge/includes/unity/mono UnityInfoBridge/includes/unity/il2cpp
• UnityInfoBridge/build.ps1 builds all supported variants

The repository already includes the required reference DLLs, so builds do not depend on any extra sync step.

Typical build:

Set-Location UnityInfoBridge
.\build.ps1

Build specific targets:

Set-Location UnityInfoBridge
.\build.ps1 -Configurations Release_BepInEx_IL2CPP

Build outputs:

• UnityInfoBridge/Release/UnityInfoBridge.BepInEx.Mono/
• UnityInfoBridge/Release/UnityInfoBridge.BepInEx.IL2CPP/
• UnityInfoBridge/Release/UnityInfoBridge.MelonLoader.Mono/
• UnityInfoBridge/Release/UnityInfoBridge.MelonLoader.IL2CPP/

Each output now includes the bridge assembly plus Newtonsoft.Json.dll. IL2CPP outputs also include UnityInfoBridge.*.deps.json.

Release assets

The GitHub release workflow produces:

• UnityInfoMCP_vx.x.x.exe
• UnityInfoMCP-vx.x.x.tar.gz
• UnityInfoMCP-vx.x.x-py3-none-any.whl
• UnityInfoBridge_vx.x.x_MelonLoader_Mono.zip
• UnityInfoBridge_vx.x.x_MelonLoader_IL2CPP.zip
• UnityInfoBridge_vx.x.x_BepInEx_Mono.zip
• UnityInfoBridge_vx.x.x_BepInEx_IL2CPP.zip
• SHA256SUMS.txt

Package structure:

• MelonLoader Mono zip: Mods/UnityInfoBridge.dll Mods/Newtonsoft.Json.dll
• MelonLoader IL2CPP zip: Mods/UnityInfoBridge.dll Mods/Newtonsoft.Json.dll Mods/UnityInfoBridge.deps.json
• BepInEx Mono zip: BepInEx/plugins/UnityInfoBridge/UnityInfoBridge.dll BepInEx/plugins/UnityInfoBridge/Newtonsoft.Json.dll
• BepInEx IL2CPP zip: BepInEx/plugins/UnityInfoBridge/UnityInfoBridge.dll BepInEx/plugins/UnityInfoBridge/Newtonsoft.Json.dll BepInEx/plugins/UnityInfoBridge/UnityInfoBridge.deps.json

MCP tool surface

Runtime:

• bridge_status
• list_bridge_targets
• select_bridge_target
• get_runtime_summary

Scene and hierarchy:

• list_scenes
• get_scene_hierarchy
• find_gameobjects_by_name
• resolve_instance_id
• get_gameobject
• get_gameobject_by_path
• get_gameobject_children

Components and fields:

• get_components
• get_component
• get_component_fields
• search_component_fields

Text and localization discovery:

• list_text_elements
• search_text
• get_text_context

Snapshots:

• snapshot_gameobject
• snapshot_scene

Write operations:

• set_gameobject_active
• set_component_member
• set_text

Capture:

• capture_screenshot

Notes:

• text and hierarchy discovery includes persistent DontDestroyOnLoad UI when Unity exposes it as a valid runtime scene object
• capture_screenshot returns PNG image content to the MCP client
• when output_path is omitted, the bridge uses GameRoot\UnityInfoBridge\captures\capture_yy-MM-dd-HH-mm-ss-fff.png as a temporary capture path and UnityInfoMCP removes the temp file after embedding the image
• provide output_path if you want the PNG to remain on disk after the MCP response

Example workflow

Find which font a live dialogue line is using:

User prompt:

"어디까지나 이리스의 의견이니까"라는 텍스트가 어느 폰트를 사용하고 있는지 알려줘.

Primary tool call:

UnityInfoMCP.search_text({
  "query": "어디까지나 이리스의 의견이니까",
  "include_inactive": true,
  "limit": 10
})

Typical result summary:

• scene: Search
• object path: _root/Canvas2/ScreenScaler2/GameObject/messagewindow/messagearea/text_message (TMP)
• component type: TMPro.TextMeshProUGUI
• current TMP font asset: message#en-font

Move the same text up by 100px:

User prompt:

그 텍스트를 위로 100px 올려줘.

Tool flow:

UnityInfoMCP.get_components({
  "gameobject_instance_id": 480506,
  "include_fields": true,
  "include_non_public": false,
  "field_depth": 1
})

UnityInfoMCP.set_component_member({
  "component_instance_id": 485632,
  "member_name": "anchoredPosition",
  "value": { "x": 0.0, "y": -258.0 },
  "include_non_public": false
})

Verification:

UnityInfoMCP.get_component_fields({
  "component_instance_id": 485632,
  "include_non_public": false,
  "include_properties": true,
  "max_depth": 1
})

Typical result summary:

• target component: UnityEngine.RectTransform
• anchoredPosition: (0.0, -358.0) -> (0.0, -258.0)
• effective change: moved upward by 100px

Runtime object IDs such as 480506 and 485632 are example values and will differ each session. For common Unity structs, tuple-style strings such as "(0, -258)" also work.

Documentation

• Bridge protocol: docs/bridge-protocol.md
• Tool mapping: docs/tool-catalog.md