XUUnity MCP server

---

Recovery and Project Automation

Use --help for the complete command list, including required arguments. Recovery guidance should carry a literal next command; inspect its result before retrying the original operation. See Agent Workflows for evidence selection, recovery prerequisites and build-artifact handoff checks.

The bridge ticks from EditorApplication.update. Long work run inline in [InitializeOnLoad] blocks its heartbeat and request processing. Use project-hook-scaffold and project-action-invoke for project-owned actions, and supported batch/build operations for builds. Check background execution and actual progress before assuming a deferred callback cannot run.

Why Use It

Use XUUnity MCP when you want a local-first, validation-first Unity MCP for safe editor automation, not broad unrestricted editor mutation.

• compile checks without switching the active Unity build target
• EditMode and PlayMode tests with normalized result accounting
• scene snapshots, scene assertions, console tail, and Game View screenshots
• bounded scenario validation and request-journal recovery after editor reloads
• same-host multi-project routing for workstations with multiple Unity projects
• editor-only package, disabled by default, with no player-build footprint by default

Search positioning keywords for this repo:

• xuunity mcp
• unity mcp
• lightweight unity mcp
• safe unity mcp
• validation-first unity mcp
• unity mcp for compile checks and tests

---

Quick Start

Choose one path first:

• Agent Quick Start for AI-driven setup from a short prompt
• Manual Install for direct human setup
• Verify Existing Install when the helper or client wiring may already exist

Prerequisites

• Unity 2021.3 LTS+ is the package metadata minimum. Focused v0.3.90 live checks ran on macOS with Unity 6000.0.58f2 on the primary display. See Status for current scope and historical records.
• Python 3.10+
• one MCP client: Claude Code, Claude Desktop, Cursor, Rider, Windsurf, Antigravity IDE, or a Codex-style agent with the Codex visual setup guide

Before running the helper, verify which Python it will use:

command -v python3
python3 --version

If your default python3 is older than 3.10, set PYTHON explicitly before running run_installed_or_refresh_xuunity_mcp.sh, run.sh, or xuunity_light_unity_mcp.sh.

On native Windows (PowerShell or cmd.exe):

py -3 --version
# or: python --version

The .cmd and .ps1 launcher flavors probe py, then python, then python3, reject the Microsoft Store stub interpreter, and require Python 3.10+. Set PYTHON to a full python.exe path when the probe picks the wrong interpreter.

Important:

• UI auto-review, sandbox auto-approval, or tool-level approval is not the same thing as user approval of setup mutations.
• An existing host-tools directory may be reused, but its helper files must not be executed until their version and .source_root have been compared with the requested release. Refresh stale helper files from the approved release source first; file existence alone does not mean the helper is current.

Agent Quick Start

This section is the fast-path for AI agents that need to install MCP into a new repo and run the first MCP command or EditMode tests correctly.

Agent Defaults

Use this contract when the user gives a short request such as:

[!IMPORTANT] Replace /path/to/UnityProject with the absolute path to your Unity project before sending the prompt. Example shape for macOS/Linux: /absolute/path/to/MyGame. On Windows, use an absolute drive-letter or UNC path.

Set up XUUnity Light Unity MCP release v0.3.90 from the canonical repository
https://github.com/FoxsterDev/xuunity-mcp for /path/to/UnityProject, follow
https://github.com/FoxsterDev/xuunity-mcp/blob/v0.3.90/README.md. Before executing
an existing helper, compare its version and .source_root with v0.3.90 and refresh
stale files from that release. On native Windows, migrate only the XUUnity client
block to cmd.exe plus run_installed_or_refresh_xuunity_mcp.cmd. After any helper
or client-config change, restart or refresh the client, list the live MCP tools,
and run unity_status_summary. Require mcp_server_info.version=0.3.90 in that live
result. Only then run EditMode tests.

Agent defaults:

• treat the current host client that is executing the request as the default MCP wiring target unless the user explicitly names a different client
• treat the explicitly requested Unity project path as the only default setup target
• prefer Git UPM package mode unless the user explicitly asks for local package development
• reuse an existing helper install directory only after comparing its installed version and .source_root with the requested release; refresh stale files before executing the helper
• on native Windows, require cmd.exe plus run_installed_or_refresh_xuunity_mcp.cmd; an existing bash/run.sh client block requires an approved migration, not reuse

Required Sequence

1. Read the release-pinned https://github.com/FoxsterDev/xuunity-mcp/blob/v0.3.90/README.md, its INSTALL.md, and the matching docs/clients/* guide for the current host client.
2. Run a non-mutating preflight:
   • confirm Python 3.10+
   • confirm Unity project structure
   • detect whether the request targets one Unity project or an entire workspace
   • compare the requested package release with the current manifest pin
   • inspect the installed helper version, .source_root, and refresh launcher before executing any existing helper
   • on native Windows, inspect the client block for the required native .cmd launcher
   • identify whether user-level client config such as ~/.codex/config.toml or ~/.claude.json would change
3. Produce a setup plan before mutating files:
   • for one requested Unity project, use setup-plan --project-root "<UNITY_PROJECT_ROOT>"
   • for a workspace or nested hub, use setup-plan --workspace-root "<WORKSPACE_ROOT>" --recursive
4. Show a short preflight review and wait for approval before any mutation, clone, installer run, manifest change, or user-level client config update.
5. After approval, apply setup only to the approved project roots.
6. Run validate-setup.
7. Run ensure-ready --open-editor when Unity is not already ready and wait for it to finish before checking status. Record whether the result reports opened_by_host: true. ensure-ready --open-editor is the default launch path: an editor launched any other way splits the log lane for the whole session — the host default Editor.log path goes stale, and every unity_console_grep / unity_console_tail call then needs an explicit editorLogPath (use the bridge_state.editor_log_path value). unity_status_summary reports this up front as editor_launch_lane: not_opened_by_host.
8. Run the first status check:
   • use request-status-summary when the current client session cannot see newly wired MCP tools yet
   • use unity_status_summary as the first live MCP-tool smoke check after the client has loaded the server
9. After any helper or client-config change, restart or refresh the client, confirm that xuunity_light_unity appears in its MCP server list, list the live MCP tools, and run unity_status_summary; require mcp_server_info.version=0.3.90. Helper-only validation does not prove that the current MCP client session is connected.
10. When the user requested tests, run EditMode tests only after the live status summary is healthy.
11. If ensure-ready --open-editor opened Unity for this run (opened_by_host: true), restore editor state before the final report:
    • xuunity_light_unity_mcp.sh restore-editor-state --project-root "<UNITY_PROJECT_ROOT>"
    • xuunity_light_unity_mcp.sh verify-editor-closed --project-root "<UNITY_PROJECT_ROOT>" --timeout-ms 0
12. Finish with:

• files changed
• commands run
• readiness result
• first MCP command result
• EditMode test result
• whether a client restart is still required
• whether Unity was restored/closed when opened by the helper

Preflight Review Checklist

• detected current client
• intended client wiring target
• requested Unity project root
• any additional discovered Unity projects
• requested package release and current manifest pin
• installed helper version, source root, and refresh requirement
• current client launcher flavor
• whether setup will modify user-level client config
• files planned for mutation
• commands planned after approval
• whether the client must restart or refresh its MCP server list afterward

Required Preflight Review Template

Every agent should show a short review block like this before setup-apply:

Preflight review
- Current client: <detected client>
- Wiring target: <target client>
- Unity project root: <approved project root>
- Additional discovered Unity projects: <none or list>
- Existing helper directory: <present | missing>
- Requested package release: <v0.3.90>
- Current package pin: <missing | current | stale | custom>
- Helper state: <current | refresh required | missing> (<installed version and source root>)
- Client launcher: <native/current | migration required>
- Planned project file changes: <manifest, bridge config, lockfile, none>
- Planned user-level config changes: <exact file paths or none>
- Restart or refresh required after mutation: <yes/no and which client>
- Running editor without an attached bridge: <none | project root, pids, then ensure-ready --open-editor>
- Required live proof after restart: <server listed, tools listed, unity_status_summary healthy with mcp_server_info.version=0.3.90>
- Planned commands after approval: <setup-apply, validate-setup, ensure-ready, request-status-summary, unity_status_summary after reload, ...>

Do not run setup-apply, installer commands, helper sync, or client config edits
until the user explicitly approves this review.

Safe Inspect Before Approval

• reading docs
• checking Python and Unity versions
• setup-plan from this wrapper, which must not refresh or write the installed helper
• uninstall-plan from this wrapper, which must not refresh, write, or remove the installed helper
• reading manifest, lockfile, and client config
• topology inspection

Mutating Actions That Require Approval

• git clone
• installer runs
• setup-apply
• uninstall-apply
• install-test-framework
• manifest or lockfile edits
• user-level client config updates
• helper install removal
• devmode or prodmode

Guided Setup Wizard

For one explicitly requested Unity project, produce a non-mutating plan first:

bash xuunity_light_unity_mcp.sh setup-plan \
  --project-root /path/to/UnityProject > /tmp/xuunity-setup-plan.json

# Stop here. Review the plan with the user before continuing.
bash xuunity_light_unity_mcp.sh setup-apply \
  --plan-file /tmp/xuunity-setup-plan.json \
  --project-root /path/to/UnityProject \
  --yes

bash xuunity_light_unity_mcp.sh validate-setup \
  --project-root /path/to/UnityProject

Native Windows quickstart from PowerShell uses the .cmd launcher (immune to ExecutionPolicy) with .\ and $env:TEMP:

.\xuunity_light_unity_mcp.cmd setup-plan --project-root "C:\path with spaces\UnityProject" > "$env:TEMP\xuunity-setup-plan.json"

# Stop here. Review the plan with the user before continuing.
.\xuunity_light_unity_mcp.cmd setup-apply --plan-file "$env:TEMP\xuunity-setup-plan.json" --project-root "C:\path with spaces\UnityProject" --yes
.\xuunity_light_unity_mcp.cmd validate-setup --project-root "C:\path with spaces\UnityProject"
.\xuunity_light_unity_mcp.cmd ensure-ready --project-root "C:\path with spaces\UnityProject" --open-editor

The same commands from cmd.exe drop the .\ prefix and use %TEMP%:

xuunity_light_unity_mcp.cmd setup-plan --project-root "C:\path with spaces\UnityProject" > "%TEMP%\xuunity-setup-plan.json"

REM Stop here. Review the plan with the user before continuing.
xuunity_light_unity_mcp.cmd setup-apply --plan-file "%TEMP%\xuunity-setup-plan.json" --project-root "C:\path with spaces\UnityProject" --yes
xuunity_light_unity_mcp.cmd validate-setup --project-root "C:\path with spaces\UnityProject"
xuunity_light_unity_mcp.cmd ensure-ready --project-root "C:\path with spaces\UnityProject" --open-editor

On native Windows, prefer .cmd for setup commands. PowerShell .ps1 wrappers can be blocked by ExecutionPolicy — stock Windows PowerShell 5.1 defaults to Restricted, so run the .ps1 flavor as powershell -NoProfile -ExecutionPolicy Bypass -File .\xuunity_light_unity_mcp.ps1 <command> ... when you need it directly. Git Bash is not the recommended setup route because native Windows paths with spaces can cross an extra shell argument boundary before Python receives them.

For flat hubs, mixed-version hubs, or nested repositories, scan the workspace first and require an explicit target selection before setup-apply:

bash xuunity_light_unity_mcp.sh setup-plan \
  --workspace-root /path/to/workspace \
  --recursive > /tmp/xuunity-setup-plan.json

# Stop here. Review the plan. Then apply only to the intended Unity project roots.
bash xuunity_light_unity_mcp.sh setup-apply \
  --plan-file /tmp/xuunity-setup-plan.json \
  --project-root /path/to/UnityProject \
  --yes

The core MCP package works without com.unity.test-framework. Test operations are an optional capability. To enable them explicitly:

bash xuunity_light_unity_mcp.sh install-test-framework \
  --project-root /path/to/UnityProject \
  --yes

Prefer this before opening or restarting Unity. The host helper mutates Packages/manifest.json offline, then Unity resolves the package graph during normal startup.

The helper recommends com.unity.test-framework@1.1.33 for Unity 2021/2022 and @1.5.1 for Unity 6000+, while the capability gate remains >= 1.1.33.

Guided Uninstall Wizard

Use uninstall-plan before any removal. It prints structured JSON and a human-readable preferred_review_summary.

Project-only cleanup makes one Unity project look not yet set up while keeping current-user client wiring and helper installs:

bash xuunity_light_unity_mcp.sh uninstall-plan \
  --mode project-only-cleanup \
  --project-root /path/to/UnityProject > /tmp/xuunity-uninstall-plan.json

# Stop here. Review the plan with the user before continuing.
bash xuunity_light_unity_mcp.sh uninstall-apply \
  --plan-file /tmp/xuunity-uninstall-plan.json \
  --yes

Project-only mode removes only the approved project-level MCP package dependency, the matching packages-lock entry, and Library/XUUnityLightMcp bridge state from the selected Unity project. It keeps ~/.codex/config.toml, ~/.claude.json, and helper installs such as ~/.codex-tools/xuunity-mcp.

Full reset for the current user removes the selected current-user client wiring and helper install in addition to optional project cleanup:

bash xuunity_light_unity_mcp.sh uninstall-plan \
  --mode full-reset-current-user \
  --project-root /path/to/UnityProject \
  --client auto > /tmp/xuunity-uninstall-plan.json

# Stop here. Review exact project, user config, and helper removals.
bash xuunity_light_unity_mcp.sh uninstall-apply \
  --plan-file /tmp/xuunity-uninstall-plan.json \
  --yes

On native Windows run the same uninstall commands through the .cmd launcher with $env:TEMP (PowerShell) or %TEMP% (cmd.exe) plan paths:

.\xuunity_light_unity_mcp.cmd uninstall-plan --mode project-only-cleanup --project-root "C:\path with spaces\UnityProject" > "$env:TEMP\xuunity-uninstall-plan.json"

# Stop here. Review the plan with the user before continuing.
.\xuunity_light_unity_mcp.cmd uninstall-apply --plan-file "$env:TEMP\xuunity-uninstall-plan.json" --yes

Use --client codex|claude_code|cursor|windsurf|claude_desktop when the current client cannot be detected. Full reset removes only the xuunity_light_unity block from the selected user config file; it does not delete the whole config file or unrelated MCP servers. Known helper installs for other clients are kept unless the plan is created with --include-other-client-helpers.

For workspace or nested project contexts, pass --workspace-root and --recursive only to report additional discovered Unity projects. The uninstall flow mutates only explicit --project-root values and never silently removes setup from sibling Unity projects.

Suggested short prompt for agents:

Remove XUUnity Light Unity MCP from <UNITY_PROJECT_ROOT> in project-only cleanup mode.
Read README.md and INSTALL.md, run uninstall-plan --mode project-only-cleanup
--project-root "<UNITY_PROJECT_ROOT>", show the preflight review, wait for
approval, then run uninstall-apply --plan-file <reviewed plan> --yes.

For a current-user reset:

Fully reset XUUnity Light Unity MCP for the current user. Run uninstall-plan
--mode full-reset-current-user, include --project-root only if a Unity project
was named, show exact user config/helper removals, wait for approval, then run
uninstall-apply with the reviewed plan.