xuunity-mcp

<div align="center"> <img src="docs/assets/xuunity-mcp-preview.png" alt="XUUnity Light Unity MCP preview banner" width="100%"> <h1>XUUnity MCP<br><small>Local-first Unity MCP for compile checks, tests, scene validation, and console evidence.</small></h1> <p> <a href="https://github.com/FoxsterDev/xuunity-mcp"><img alt="GitHub stars" src="https://img.shields.io/github/stars/FoxsterDev/xuunity-mcp?style=flat&logo=github"></a> <a href="LICENSE"><img alt="License MIT" src="https://img.shields.io/badge/license-MIT-red.svg"></a> <img alt="Unity 2021.3+" src="https://img.shields.io/badge/Unity-2021.3%2B-black.svg?logo=unity&logoColor=white"> <img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-blue.svg?logo=python&logoColor=white"> <img alt="MCP enabled" src="https://img.shields.io/badge/MCP-enabled-green.svg"> <img alt="Git UPM ready" src="https://img.shields.io/badge/Git%20UPM-ready-brightgreen.svg"> <img alt="OpenUPM planned" src="https://img.shields.io/badge/OpenUPM-planned-lightgrey.svg"><br> <img alt="Editor-only" src="https://img.shields.io/badge/-Editor--only-0f766e.svg"> <img alt="macOS" src="https://img.shields.io/badge/-macOS-111827.svg?logo=apple&amp;logoColor=white"> <img alt="Windows" src="https://img.shields.io/badge/-Windows-0078D4.svg?logo=windows11&amp;logoColor=white"> <img alt="Linux" src="https://img.shields.io/badge/-Linux-FCC624.svg?logo=linux&amp;logoColor=111827"> <img alt="Cursor" src="https://img.shields.io/badge/-Cursor-111827.svg"> <img alt="Claude" src="https://img.shields.io/badge/-Claude-D97757.svg?logo=anthropic&amp;logoColor=white"> <img alt="Codex" src="https://img.shields.io/badge/-Codex-111827.svg?logo=openai&amp;logoColor=white"> <img alt="Rider" src="https://img.shields.io/badge/-Rider-8B5CF6.svg?logo=rider&amp;logoColor=white"> <img alt="Other MCP clients" src="https://img.shields.io/badge/-other_MCP_clients-64748B.svg"><br> <a href="#agent-quick-start">Agent Quick Start</a> | <a href="#manual-install">Manual Install</a> | <a href="#verify-existing-install">Verify Existing Install</a> | <a href="#ai-agent-setup-prompt">AI Setup Prompt</a> | <a href="docs/index.html">Pages Site</a> | <a href="docs/reference/FEATURES.md">Features</a> | <a href="#supported-clients">Client Docs</a> | <a href="SECURITY.md">Security</a> | <a href="docs/reference/COMPARISON.md">Comparison</a> | <a href="docs/agents/AGENT_WORKFLOWS.md">Agent Workflows</a><br> _{Independent open-source project · Not affiliated with or endorsed by Unity Technologies · Unity Terms of Service authorization not confirmed} </p> </div>

---

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+; the current release has live validation on Unity 2021.3, 2022.3, and 6000.x. See Status.
• 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.83 from the canonical repository
https://github.com/FoxsterDev/xuunity-mcp for /path/to/UnityProject, follow
https://github.com/FoxsterDev/xuunity-mcp/blob/v0.3.83/README.md. Before executing
an existing helper, compare its version and .source_root with v0.3.83 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.83 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.83/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.83. 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