unity-inspector-mcp
Use it to inspect, control, debug, test, and automate a running Broforce game through MCP tools.
Check connectivity and orient:
ping,wait_for_game,game_state.Inspect the scene and entities:
list_gameobjects,query_gameobjects,inspect_gameobject,inspect_component,inspect_player,list_enemies.Modify gameplay state:
modify_component,teleport_player,set_player_health,spawn_entity,set_game_speed,swap_bro,set_bro,restart_level,go_to_level.Discover options:
list_campaigns,list_bros.Drive and observe the game:
simulate_input,take_screenshot.Run custom C# in-game:
execute_code,execute_script,compile_script,list_scripts,unload_script.Test and debug:
run_test_script,list_test_scripts,read_log,watch_log.Manage game lifecycle:
launch_game,stop_game.
Provides tools to inspect and modify a running Unity game (Broforce), including GameObjects, components, player state, enemies, spawning entities, and executing C# code/scripts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@unity-inspector-mcp List all active enemies and their positions in the current level."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.shsetup.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.jsWSL
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 |
|
| TCP port the mod listens on. |
| Command line | |
|
| The r2modman profile the Steam launch loads mods from: a name, or the profile folder's absolute path. |
|
|
|
| unset | Command line |
| unset | The launcher for separate game instances. |
|
| Host your own game runs on (docs/remote-game.md). |
| searched for | Path to the token file the mod writes. |
| searched for | Path to the log |
|
| Folder |
|
| Folder files fetched from a game on another machine go under. |
|
| 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 |
| Test the connection to the mod, and whether the game's main thread answers. |
| The loaded level, game mode, players and bro type, and which game the server is pointed at. |
| List the root GameObjects of the loaded scenes. |
| Search GameObjects by name pattern and/or component type. |
| Inspect one GameObject by path or |
| Inspect a component's fields and properties, or read one member of it. |
| Write fields and properties on a component and read each back. |
| Capture the game window, optionally outlining a target or drawing only the characters on a flat colour. |
| Each player's bro, position and state. |
| Move a player (or all players) to a coordinate. |
| Set a player's health. |
| List the bros players can swap to. Requires Swap Bros Mod. |
| Swap a player's bro mid-level, or choose the bro they spawn as next. Requires Swap Bros Mod. |
| List the enemies in the loaded level. |
| Spawn a unit, villager or animal at a coordinate. |
| Record the game's spawn calls and read them back. |
| Set the time scale (1.0 is normal). |
| Press or hold game actions or a mod's key binding, alone or in sequences. |
| List campaigns with their indices. |
| Go directly to a campaign level. |
| Restart the current level. |
| Run C# statements in the game and return the result. |
| Compile and run a C# script file in the game. |
| List the C# script library. |
| Unload a running script, removing its patches and objects. |
| List the JSON test scripts. |
| Run a JSON test script and report each step. |
| Capture a bro's animation states as PNG strips and check them against a state list. |
| Read the game's log, or only the lines written since the last read. |
| Launch Broforce and wait until it answers, or point the server at a running or remote game. |
| Stop the game this server is pointed at. |
| Wait until the game answers. |
| Restart |
Scripts
C# scripts:
scripts/csharp/is a library of scripts thatexecute_scriptruns in the game, andlist_scriptslists. Writing one: scripts/csharp/README.md.Test scripts:
scripts/tests/holds JSON sequences of tool calls thatrun_test_scriptruns, 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:
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.
The mod's TCP server is stopped. The mod's panel in the overlay shows its status and has a Start Server button.
The mod is on a port other than 9999. Set
UNITY_INSPECTOR_PORTto match.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 toolscompile_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
Scored across 33 tools
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.
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.
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.
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
Related MCP Connectors
Drive a live Cinevva game session: edit game files, import CC0 assets, preview changes.
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Let your coding agent read your GameSalad projects, and edit them live in Creator on Pro and Edu.
Run your Krtuworks apps from an AI agent: setup, remote config, stats, players, bug reports.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query and control the Unity Editor, supporting scene management, GameObject manipulation, asset browsing, play mode control, and real-time editor operations through 52+ tools.1MIT
- AlicenseNot gradedqualityNot gradedmaintenanceExposes 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-
- AlicenseNot gradedqualityBmaintenanceEnables AI models to interact with Unity games at runtime by providing tools to list UI actions, inspect GameObjects, capture screenshots, and manage scenes.9MIT
- AlicenseNot gradedqualityAmaintenanceUnity Editor automation bridge for AI agents and MCP clients, enabling inspection, control, and diagnostics of the Editor.MIT