MCP for Unity 提示 uv Not Found：uvx 启动不了服务器怎么修？
【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp
在 Unity 里装好 MCP for Unity 后，MCP for Unity 窗口状态面板显示红色"uv Not Found"，配文"Make sure uv is installed! [CLICK]"，客户端（Cursor、VS Code、Windsurf、Rider 等基于 uv 的客户端）也启动不了服务器。原因是：客户端配置里写的是command: uvx（参数形如--from mcpforunityserver mcp-for-unity --transport stdio），由客户端直接调用uvx拉起 Python 服务器mcp-for-unity；只要uv没安装、不在 PATH 上，或者 GUI 启动的 Unity 读不到终端里的 PATH，服务器就起不来，状态面板会一直停在 "uv Not Found"。
官方针对这个场景有专门的 uv + Python 安装/修复指南，本文按该文档给出一条完整的修复路径：先验证、再安装、装不上就手动指定路径，最后验证状态面板回到Connected。
先验证：uv 到底装没装
在终端运行两条命令：
python3 --version # should be 3.10+ uv --version # should print a version like "uv 0.x"前置要求是Python 3.10+和uv包管理器，两者缺一不可。
- 两条都正常输出 → 说明
uv本身没问题，跳到 手动指定 uv 路径。 uv报错找不到命令 → 继续下面的安装步骤。- 只有
uv正常但python3版本低于 3.10 → 先装 Python 3.10+：macOS 可用官方安装包或brew install python@3.12（3.12 为最新 LTS，3.10 也可以）；Windows 用 python.org 官方安装包。
安装 uv
按系统选择文档给出的安装方式。这些命令都会修改你本机的环境（安装程序到用户目录或系统目录），安装前确认你有对应权限。
macOS / Linux / WSL：
curl -LsSf https://astral.sh/uv/install.sh | sh # or Homebrew on macOS brew install uvWindows PowerShell：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # or winget install --id=astral-sh.uv -e装完回到终端重新跑一次uv --version，能输出版本号才算装好。
uv 装了但 Unity 找不到：手动指定路径
如果终端里uv --version正常，但状态面板仍是 "uv Not Found"，通常是 PATH 问题，文档列了两类典型原因：
- macOS 从 Finder / Hub 启动的 GUI 应用不会继承你的 shell 启动文件，终端里的 PATH 和 Unity 看到的 PATH 可能不一样。文档明确说这种情况下通过 MCP 窗口设置 uv 路径是最简单的修法。
- Windows vs WSL：只在 WSL 里装了
uv的话，Windows 原生的 Unity 看不到它。要么在 Windows 侧装一份uv，要么用 MCP 窗口指向 Windows 的uv.exe。
操作路径：打开Window → MCP for Unity，用"Choose UV Install Location"浏览到uv可执行文件，保存后路径会被自动记录并重新配置。文档给出的常见安装位置供参考：
| OS | Path |
|---|---|
| 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 |
手动选择的路径存在UnityMCP.UvPath里，跨会话持久有效。
Windows 特别注意：固定 WinGet Links 的 uvx 路径
在 troubleshooting 文档 的 FAQ 里有一条针对 Cursor / Windsurf / VS Code 的问题：uv明明装着，MCP 客户端还是启动不了服务器。原因是部分 Windows 机器上存在多个uv.exe，自动配置有时会挑到一个不太稳定的路径，导致每次重启都启动失败或自动重写配置。文档给出的修法是：在 MCP for Unity 窗口用"Choose UV Install Location"固定到WinGet Links shim路径%LOCALAPPDATA%\Microsoft\WinGet\Links\uv.exe——这个路径在 uv 升级过程中保持稳定。
修完环境后的重建：Repair Python Env
uv找到了之后，如果服务器仍然异常（例如 Python 升级过、依赖模块缺失），MCP 窗口里的Repair Python Env按钮会做三件事：
- 删除服务器目录下的
.venv和.python-version（如果存在）； - 在 Unity MCP Server 的
src目录里运行uv sync，重建一个干净的环境； - 适用于 Python 升级后或缺少模块的场景。
注意这个动作会删掉现有的虚拟环境，重建前确认你不需要保留其中内容。
服务器安装位置（需要手动操作时用到）：
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/UnityMCP/UnityMcpServer/src（或~/Library/AppSupport/UnityMCP/UnityMcpServer/src，symlink） |
| Windows | %USERPROFILE%/AppData/Local/UnityMCP/UnityMcpServer/src |
| Linux | ~/.local/share/UnityMCP/UnityMcpServer/src |
文档同时给出了手动修复/运行的方式（<UnityMcpServer/src>替换为上一表中对应系统的路径）：
cd <UnityMcpServer/src> uv sync uv run server.py结果验证
按顺序核对：
- 终端
uv --version有输出，且 MCP for Unity 窗口的 "uv Not Found" 红字消失； - 状态面板显示
Connected（安装文档中写明：一切就绪时状态面板读作Connected）； - 在 MCP 客户端里发一条最简单的验证指令，例如安装文档给的 first prompt："Create a red, blue, and yellow cube in the current scene."，能操作场景即说明服务器已被
uvx正常拉起。
另外文档提醒：如果你在http和stdio之间切换过传输方式，客户端（Claude Code、JetBrains Rider 等）可能会混乱并报"No Unity Instances found"——重启客户端让它重新读取配置即可。
限制与边界
- 本路径只解决 "uv Not Found / uvx 启动不了服务器"。如果状态是"Claude Not Found"（Claude Code 的
claudeCLI 没找到），那是另一个问题，对应文档的修法是 "Choose Claude Location" 指定claude二进制路径。 - WSL2 中只装 uv 对 Windows 原生 Unity 无效，这条限制在 Windows 上尤其常见，见上文"手动指定 uv 路径"一节。
- 更细的窗口行为（各客户端的 Auto Configure、Manual Setup）可参考 MCPForUnity/README.md；客户端选型与手动 JSON 配置见 选择 MCP 客户端 与 安装指南。
【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
