1. Fix Unity MCP and Cursor, VSCode & Windsurf

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

uv is a fast Python package manager we use to create a self-sufficient python server for the MCP, which runs server.py.
How it's used: your MCP client config points to command: uv with args like --directory <UnityMcpServer/src> run server.py. The client will invoke uv 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 [email protected]

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