Skip to content

1. Fix Unity MCP and Cursor, VSCode & Windsurf

Jump to bottom
dsarno edited this page Aug 13, 2025 · 2 revisions

Install/Repair uv and Python (Unity MCP Server)

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

  • macOS: /opt/homebrew/bin/uv, /usr/local/bin/uv, ~/.local/bin/uv
  • Linux: /usr/local/bin/uv, /usr/bin/uv, ~/.local/bin/uv
  • Windows: %LOCALAPPDATA%/Programs/Python/Python3xx/Scripts/uv.exe

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
  • Windows: %USERPROFILE%/AppData/Local/Programs/UnityMCP/UnityMcpServer/src
  • Linux: ~/bin/UnityMCP/UnityMcpServer/src

Manual repair/run (optional)

cd <UnityMcpServer/src>
uv sync
uv run server.py
Clone this wiki locally