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>

---

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.57 from the canonical repository
https://github.com/FoxsterDev/xuunity-mcp for /path/to/UnityProject, follow
https://github.com/FoxsterDev/xuunity-mcp/blob/v0.3.57/README.md. Before executing
an existing helper, compare its version and .source_root with v0.3.57 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.57 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.57/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.
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.57. 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.57>
- 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>
- Required live proof after restart: <server listed, tools listed, unity_status_summary healthy with mcp_server_info.version=0.3.57>
- 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, w