Skip to main content

Install or Repair uv + Python

The key to configuring MCP with Cursor, VS Code, Windsurf, and Rider 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 invokes uvx directly to launch the server.
  • Why it matters: if uv isn't installed or on PATH, Cursor / Windsurf / VS Code can't start the server. The MCP for Unity window will show "uv Not Found" until fixed.
  • Detection / override: the MCP for Unity window auto-detects uv in common locations and on PATH. If not found, use "Choose UV Install Location" to navigate to your uv binary and save the path.
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 say "No Unity Instances found", restart the client so it picks up the new configuration.

Requirements​

You need Python 3.10+ and the uv package manager.

Verify​

python3 --version   # should be 3.10+
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 (3.12 is the latest LTS as of writing; 3.10 also works)
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​

OSPath
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

MCP for Unity window behavior​

  • If uv isn't found, the status panel shows a red "uv Not Found" with a hint "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 the Unity MCP Server is installed​

OSPath
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​

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