Skip to main content
Glama
unity-inspector-mcp

unity-inspector-mcp

unity-inspector-mcp

The Unity Inspector Mod isn't released yet. Until it is, its source is in the Unity Inspector Mod folder of BroforceMods.

This lets an MCP client inspect and change things in Broforce while the game is running. It's mainly for modding and debugging. It works with the Unity Inspector Mod, a C# mod loaded by Unity Mod Manager, and the two talk over TCP on localhost, port 9999 by default. The server runs on Linux, Windows and macOS.

Requirements

  • Node.js 18 or newer. I've tested on 22, and the MCP SDK is the only npm dependency.

  • Broforce with Unity Mod Manager, RocketLib and the Unity Inspector Mod.

  • An MCP client, such as Claude Code, Claude Desktop, Codex CLI, Cursor, VS Code or Windsurf.

Related MCP server: Unity MCP Server

Installing the mod

Install the mod first. It's on Thunderstore as AlexN-Unity_Inspector_Mod, and installing it with r2modman pulls in RocketLib too. You can also install it by hand by putting its folder in Unity Mod Manager's Mods folder. Here's a guide for installing Unity Mod Manager and mods if you haven't done that before.

Update the mod and the server together, since a mismatched pair refuses to connect and the error says which one to update.

Installing the server

git clone https://github.com/alexneargarder/unity-inspector-mcp
cd unity-inspector-mcp
./setup.sh

setup.sh checks for Node, installs the dependencies and prints the client config with the absolute path already filled in. A plain npm install works too, you just don't get the printed config.

Client configuration

The config has to point at wrapper.js, not index.js. The wrapper provides the restart_server tool and respawns the server if it crashes.

{
  "mcpServers": {
    "unity-inspector": {
      "command": "node",
      "args": ["/absolute/path/to/unity-inspector-mcp/wrapper.js"],
      "env": {
        "UNITY_INSPECTOR_PORT": "9999"
      }
    }
  }
}

The env block is optional. Claude Desktop, Cursor, Windsurf and Cline take this as is in their MCP config file. VS Code's .vscode/mcp.json calls the top level key servers instead, and each server there needs "type": "stdio". Claude Code takes a command, with any settings as --env KEY=value before the --, and Codex CLI the same with codex mcp add:

claude mcp add unity-inspector -- node /absolute/path/to/unity-inspector-mcp/wrapper.js

WSL

If the game is on Windows and your MCP client is in WSL, run the server in WSL:

{
  "mcpServers": {
    "unity-inspector": {
      "command": "wsl",
      "args": ["node", "/home/you/unity-inspector-mcp/wrapper.js"]
    }
  }
}

Under WSL2's default NAT networking, turn on the mod's "Allow remote connections (LAN)" setting and allow Broforce through the Windows firewall. That opens the mod's port to your network while it's on. launch_game and stop_game can't manage a game on Windows from WSL, so start and stop it there yourself.

Environment variables

All of these are optional and go in the env block. ~/.local/state below means $XDG_STATE_HOME when that is set.

Variable

Default

Effect

UNITY_INSPECTOR_PORT

9999

TCP port the mod listens on.

BROFORCE_LAUNCH_CMD

the Steam launch

Command line launch_game runs to start your own game (docs/launcher-contract.md).

BROFORCE_PROFILE

Default

The r2modman profile the Steam launch loads mods from: a name, or the profile folder's absolute path.

BROFORCE_LAUNCH_TYPE

auto

native or proton: how the Steam launch runs the game on Linux.

BROFORCE_STOP_CMD

unset

Command line stop_game runs to stop your own game. Unset, the server signals the game's process.

BROFORCE_INSTANCE_CMD

unset

The launcher for separate game instances.

UNITY_INSPECTOR_HOST

127.0.0.1

Host your own game runs on (docs/remote-game.md).

UNITY_INSPECTOR_TOKEN_FILE

searched for

Path to the token file the mod writes.

UNITY_INSPECTOR_LOG

searched for

Path to the log read_log reads.

UNITY_INSPECTOR_TEST_RESULTS_DIR

~/.local/state/unity-inspector-mcp/test-results

Folder run_test_script writes full results under.

UNITY_INSPECTOR_REMOTE_DIR

~/.local/state/unity-inspector-mcp/remote

Folder files fetched from a game on another machine go under.

UNITY_INSPECTOR_LAUNCHES_DIR

~/.local/state/unity-inspector-mcp/launches

Folder each session's record of its last launch goes in.

Launching your game through Steam

When BROFORCE_LAUNCH_CMD isn't set, launch_game starts your own game with mods through Steam, from the r2modman profile BROFORCE_PROFILE names. On Linux, Broforce's Launch Options in Steam need the line r2modman's Linux setup screen gives you, except under Proton with the regular r2modman, which needs none. The details for each platform are in docs/steam-launch.md.

Separate game instances

On Linux, each Claude Code session can get its own game instance: a second copy of the game with its own profile, saves, logs, port and virtual display, so an agent can play its own game while you play yours. BROFORCE_INSTANCE_CMD turns this on by naming the launcher that creates and runs instances. launch_game then starts the session's instance, and launch_game { steam: true } points the server at your own game instead. docs/launcher-contract.md is what a launcher has to implement.

Remote game

launch_game can also point the server at a game on another machine, through an ssh tunnel or over the LAN: see docs/remote-game.md.

Tools

There are 33, 32 from the server and restart_server from the wrapper.

Tool

Description

ping

Test the connection to the mod, and whether the game's main thread answers.

game_state

The loaded level, game mode, players and bro type, and which game the server is pointed at.

list_gameobjects

List the root GameObjects of the loaded scenes.

query_gameobjects

Search GameObjects by name pattern and/or component type.

inspect_gameobject

Inspect one GameObject by path or instanceId.

inspect_component

Inspect a component's fields and properties, or read one member of it.

modify_component

Write fields and properties on a component and read each back.

take_screenshot

Capture the game window, optionally outlining a target or drawing only the characters on a flat colour.

inspect_player

Each player's bro, position and state.

teleport_player

Move a player (or all players) to a coordinate.

set_player_health

Set a player's health.

list_bros

List the bros players can swap to. Requires Swap Bros Mod.

swap_bro

Swap a player's bro mid-level, or choose the bro they spawn as next. Requires Swap Bros Mod.

list_enemies

List the enemies in the loaded level.

spawn_entity

Spawn a unit, villager or animal at a coordinate.

trace_spawns

Record the game's spawn calls and read them back.

set_game_speed

Set the time scale (1.0 is normal).

simulate_input

Press or hold game actions or a mod's key binding, alone or in sequences.

list_campaigns

List campaigns with their indices.

go_to_level

Go directly to a campaign level.

restart_level

Restart the current level.

execute_code

Run C# statements in the game and return the result.

execute_script

Compile and run a C# script file in the game.

list_scripts

List the C# script library.

unload_script

Unload a running script, removing its patches and objects.

list_test_scripts

List the JSON test scripts.

run_test_script

Run a JSON test script and report each step.

capture_animations

Capture a bro's animation states as PNG strips and check them against a state list.

read_log

Read the game's log, or only the lines written since the last read.

launch_game

Launch Broforce and wait until it answers, or point the server at a running or remote game.

stop_game

Stop the game this server is pointed at.

wait_for_game

Wait until the game answers.

restart_server

Restart index.js in place to pick up code changes. Provided by wrapper.js.

Scripts

  • C# scripts: scripts/csharp/ is a library of scripts that execute_script runs in the game, and list_scripts lists. Writing one: scripts/csharp/README.md.

  • Test scripts: scripts/tests/ holds JSON sequences of tool calls that run_test_script runs, for reproducing a scenario the same way every time. The format: scripts/README.md.

Troubleshooting

"Game is not running. Use launch_game to start it." means the server couldn't open the TCP connection. Most likely causes, in order:

  1. The game isn't running, or the mod didn't load. Check that the Unity Mod Manager overlay (Ctrl+F10) lists the mod and that it's enabled.

  2. The mod's TCP server is stopped. The mod's panel in the overlay shows its status and has a Start Server button.

  3. The mod is on a port other than 9999. Set UNITY_INSPECTOR_PORT to match.

  4. On WSL2, "Allow remote connections (LAN)" is off or the Windows firewall blocks Broforce.

If the mod refuses the connection, the error says why. If the mod's token file or the game's log is somewhere the server doesn't look, set UNITY_INSPECTOR_TOKEN_FILE or UNITY_INSPECTOR_LOG; the error lists the paths it tried.

If the game process is there but doesn't answer, the mod most likely failed to load, and read_log will have the reason.

If the server crashes three times inside 30 seconds, the wrapper stops restarting it until you call restart_server. The wrapper's log, with everything the server wrote to stderr, is mcp-wrapper-<pid>.log in ~/.local/state/unity-inspector-mcp/ (the system temp folder on Windows).

Development

The tests are npm test, with Node's built in runner and no test dependencies, and none of them need the game. AGENTS.md covers the architecture, adding a tool and the repo's conventions.

Available Tools

33 tools
compile_scriptA

Compile a C# script without running it. Returns compilation success/failure and any compiler errors. Useful for validating scripts before execution.

Inputs: path (required).

execute_codeB

Execute C# expressions in the Unity context. Uses Mono.CSharp.Evaluator - expects expressions, not statements

Inputs: code (required).

execute_scriptA

Compile and run a C# script file in the Unity runtime. Supports full class definitions, MonoBehaviours, Harmony patches, and private member access. Scripts can define Main() for execution and Unload() for cleanup. Use ScriptContext for Harmony instances, logging, and arguments.

Available library scripts:

  • Dump Harmony Patches: List all Harmony patches on a specified method, showing patch owner, type, and priority [args: typeName, methodName]

  • Find Objects By Type: Find all active instances of a type in the scene with key state info [args: typeName, maxResults]

  • Inspect Private Fields: Dump all field values (including private) of a component on a named GameObject [args: gameObjectName, componentType]

  • Menu Tweaker: Live-edit FlexMenu element properties without rebuilding. Target by name, type, or wildcard pattern. [args: elementName]

  • Rogueforce Runner: Test harness for the Rogueforce mod. Start a run, skip levels, log state, auto-run a full campaign, or trigger game over. [args: action]

  • Trace Method Calls: Harmony-patch a method to log every call with arguments for a specified number of frames [args: typeName, methodName, maxCalls]

  • Watch Field: Monitor a field on a component and log whenever its value changes. Runs until unloaded. [args: gameObjectName, componentType, fieldName]

Inputs: path (required), args.

game_stateA

Get a high-level summary of the current game state: scene, game mode, level info, player status, and bro type. Single call to orient yourself.

Inputs: no named parameters.

go_to_levelB

Go directly to a specific campaign level

Inputs: levelIndex (required), campaignIndex (required).

inspect_componentB

Inspect a specific component on a GameObject

Inputs: path (required), componentType (required).

inspect_gameobjectA

Inspect a specific GameObject by path

Inputs: path (required), detailed.

inspect_playerB

Get detailed information about the player(s)

Inputs: no named parameters.

launch_gameA

Launch Broforce and wait for it to become responsive. Uses the BROFORCE_LAUNCH_CMD environment variable when set, otherwise launches Steam app 274190. Returns a warning if the game is already running unless restart is true.

Inputs: restart, vanilla.

list_brosA

List all available bros that can be used with swap_bro and set_bro. Reports the selected bro for the given player (currentBro) and for all active players (currentBros array).

Inputs: playerNum.

list_campaignsA

List all available campaigns with their indices

Inputs: no named parameters.

list_enemiesA

List all enemies in the scene

Inputs: no named parameters.

list_gameobjectsC

List all GameObjects in the scene

Inputs: maxResults, includeInactive.

list_scriptsA

List available C# scripts in the script library with their metadata (name, description, tags, arguments).

Inputs: no named parameters.

list_test_scriptsA

List all available test scripts in scripts/ and scripts/examples/

Inputs: no named parameters.

modify_componentB

Modify properties of a component on a GameObject

Inputs: path (required), component (required), properties (required).

pingB

Test connection to Unity Inspector

Inputs: no named parameters.

query_gameobjectsB

Search for GameObjects by name or component

Inputs: maxResults, namePattern, componentType, includeInactive.

read_logB

Read the UMM mod manager log file. Returns the last N lines by default, or filter by pattern.

Inputs: lines, filter.

restart_levelA

Restart the current level from the beginning. Clears checkpoints and trigger state for a full reset.

Inputs: no named parameters.

run_test_scriptA

Execute a test script containing a sequence of commands. Scripts are JSON files with command sequences that can include wait delays. Steps run directly against the game, so only game-side commands work — server-side tools (read_log, watch_log, list_scripts, launch_game, stop_game, wait_for_game, ...) cannot be used as steps.

Inputs: script (required).

set_broA

Set which bro the player will spawn as next (on death/respawn/next level). Does NOT change the current bro mid-level.

Inputs: broName (required), playerNum.

set_game_speedA

Set the game speed (time scale)

Inputs: speed (required).

set_player_healthC

Set a player's health

Inputs: health (required), playerNum.

simulate_inputC

Simulate keyboard/controller input

Inputs: action (required), count, player, duration, +1 more.

spawn_entityC

Spawn an entity at a specific position (limited implementation)

Inputs: x (required), y (required), type (required).

stop_gameA

Stop the running Broforce process.

Inputs: no named parameters.

swap_broA

Swap the current player's bro mid-level. Kills the current bro and spawns the new one at the same position. Integrates with Swap Bros Mod when available, falls back to direct game manipulation.

Inputs: broName (required), playerNum.

take_screenshotA

Take a screenshot of the game. Returns the path to the saved screenshot.

Inputs: no named parameters.

teleport_playerB

Teleport a player to a specific position

Inputs: x (required), y (required), z, playerNum.

unload_scriptA

Unload an active C# script, cleaning up its Harmony patches, GameObjects, and calling its Unload() method if defined.

Inputs: name (required).

wait_for_gameA

Wait for the game to start up and the Unity Inspector TCP server to become responsive. Polls the connection until a ping succeeds or timeout is reached.

Inputs: timeout, interval.

watch_logA

Return log entries that appeared since the last call to watch_log. First call returns the last 20 lines as a baseline. Use this for iterative debug loops.

Inputs: reset.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 33 tools

    Disambiguation4/5

    Tools generally target distinct resources/actions: scene inspection, component editing, player manipulation, and script execution. The main confusion risk is among execute_code, execute_script, and run_test_script, but their descriptions clearly distinguish C# expressions, C# script files, and JSON command sequences.

    Naming Consistency4/5

    Names consistently use snake_case and mostly follow a verb_noun pattern like list_gameobjects, set_player_health, and restart_level. Minor deviations such as game_state being noun-only, the bare ping, and mixing execute/run verbs prevent a perfect score.

    Tool Count2/5

    33 tools is well beyond the 25+ threshold and feels over-scoped for a single server. Many specialized tools like list_bros, swap_bro, set_bro, list_campaigns, and go_to_level could be grouped into broader commands or consolidated.

    Completeness4/5

    The surface covers scene inspection, component modification, player and level manipulation, input simulation, logging, screenshots, and script lifecycle management. Minor gaps like adding/removing components or destroying GameObjects exist, but execute_script can largely cover those cases.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Exposes Unity Editor project context and manipulation tools to AI coding agents, enabling automated scene hierarchy analysis, script inspection, and asset management. It supports both read and write operations including GameObject editing, component configuration, and animation authoring within the Unity environment.
      2
      -