1. Fix Unity MCP and Cursor, VSCode, Windsurf, Rider

🚨🚨When in doubt, restart your client🚨🚨

Clients like Claude Code or JetBrains Rider can get confused if you switch from http to stdio or vice versa. If they're saying "No Unity Instances found" or similar, make sure you restart the client so it can pick up the new configuration.

The key to configuring MCP with Cursor, Windsurf, and VSCode is uv.

uv is a fast Python package manager used to install and run the Unity MCP Server (mcp-for-unity).
How it's used: your MCP client config points to command: uvx with args like --from mcpforunityserver mcp-for-unity --transport stdio. The client will invoke uvx directly to launch the Unity MCP Server.
Why it matters: if uv isn't installed or on PATH, Cursor/Windsurf/VSCode can't start the server; the Unity MCP window will show "uv Not Found" until fixed.
Detection/override: the Unity MCP window auto-detects uv in common locations and PATH; if not found, use "Choose UV Install Location" to navigate to your uv installation and save its path.

You need Python 3.12+ and the uv package manager for the Unity MCP Server to run.

Verify

python3 --version   # should be 3.12+
uv --version        # should print a version like "uv 0.x"

Install Python

macOS:

# Option A: Official installer (recommended)
# Download from https://www.python.org/downloads/

# Option B: Homebrew
brew install python@3.12

Windows:

# Official installer (recommended)
# Download from https://www.python.org/downloads/windows/

Install uv

macOS/Linux/WSL:

curl -LsSf https://astral.sh/uv/install.sh | sh
# or Homebrew on macOS
brew install uv

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# or
winget install --id=astral-sh.uv -e

Common uv locations

Unity MCP window behavior (Cursor/Windsurf)

If uv isn't found, you'll see a red status "uv Not Found" and a hint line "Make sure uv is installed! [CLICK]".
Use "Choose UV Install Location" to browse to the uv binary. This saves the path and reconfigures automatically.
On macOS, Unity launched from Finder may not inherit your PATH. Setting the uv location here is the easiest fix.

Notes and gotchas

macOS GUI apps don't inherit your shell startup files; PATH may differ from Terminal. Set uv via the MCP window to avoid PATH issues.
Windows vs WSL: if you installed uv inside WSL only, Windows-native Unity can't see it. Install uv on Windows, or use the MCP window to point to a Windows uv.exe.
Custom locations: if you installed uv somewhere non-standard, the picker path is stored in UnityMCP.UvPath and persists across sessions.

What the "Repair Python Env" button does

Deletes the server's .venv and .python-version (if present)
Runs uv sync in the Unity MCP Server src directory to rebuild a clean environment
Useful after Python upgrades or missing modules

Where is the Unity MCP Server installed?

macOS: ~/Library/Application Support/UnityMCP/UnityMcpServer/src (or ~/Library/AppSupport/UnityMCP/UnityMcpServer/src via symlink)
Windows: %USERPROFILE%/AppData/Local/UnityMCP/UnityMcpServer/src
Linux: ~/.local/share/UnityMCP/UnityMcpServer/src

Manual repair/run (optional)

cd <UnityMcpServer/src>
uv sync
uv run server.py

Provide feedback