UPilot

让 Codex、Claude Code、Cursor 等 AI Agent 直接操作 Unity Editor。

UPilot 会在 Unity 中启动本地 MCP 服务，并为常见 Agent 自动写入项目级连接配置。配置完成后，你可以直接让 Agent 查看场景、检查编译错误、读取 Console、修改 GameObject、管理资源、运行测试或构建任务。

当前版本：0.2.0

Unity：2022.3 或更高

Python：3.11 或更高

默认 MCP 地址：http://127.0.0.1:8011/mcp

教程截图来自 Windows 上的 Unity 2022.3。不同 Unity 版本、操作系统或编辑器主题下，界面外观可能略有差异，但按钮名称和操作流程一致。

5 分钟快速上手

1. 确认环境

在终端中确认已安装 Python 3.11 或更高版本：

python --version

如果系统提示找不到 python，请先安装 Python，安装时勾选 Add Python to PATH。

2. 安装 Unity 包

在 Unity 中打开：

Window > Package Manager

点击左上角 +，选择 Add package from git URL...，输入：

https://github.com/codingriver/upilot.git#v0.2.0
#开发模式
https://github.com/codingriver/upilot.git#main

点击 Add，等待 Unity 完成包导入和脚本编译。

输入 UPilot Git URL 后点击右侧 Add。

3. 安装 Python 依赖

在 PowerShell 或终端中执行：

python -m pip install "git+https://github.com/codingriver/[email protected]#subdirectory=upilotserver~"

如果你已经下载或克隆了 UPilot 仓库，也可以在仓库中执行：

cd upilotserver~
python -m pip install -e .

4. 在 Unity 中配置并启动

包导入完成后，Unity 会自动打开 UPilot 设置界面。如果没有自动打开，请选择：

UPilot > UPilot

然后：

1. 选择你正在使用的 Agent：Codex、Claude 或 Cursor，支持多选。
2. 点击 配置并启动。
3. 等待界面显示 已就绪。

选择常用 Agent 后点击“配置并启动”。

UPilot 会自动选择可用端口、写入所选 Agent 的 MCP 配置，并同步所需的 Skill/规则。

5. 重启 Agent 并验证

首次写入配置后，请重新启动 Agent 客户端，或重新加载当前项目窗口，使 MCP 工具列表刷新。

然后对 Agent 说：

请调用 unity_mcp_status，确认 UPilot 已连接，并检查当前 Unity 工程路径。

成功时应满足：

• connected: true
• serverReady: true
• 返回的 Unity 工程路径与当前项目一致

现在可以开始使用 UPilot。

环境要求

项目	要求
Unity	2022.3 或更高版本
Python	3.11 或更高版本
Agent	Codex、Claude Code、Cursor，或支持 Streamable HTTP MCP 的客户端
网络	首次通过 Git 和 pip 安装时需要访问 GitHub 与 Python 包源

UPilot 默认只监听本机地址 127.0.0.1。Unity Editor 必须保持打开，Agent 才能操作当前项目。

完整安装教程

方式一：通过 Unity Package Manager 安装（推荐）

1. 打开 Unity 项目。
2. 选择 Window > Package Manager。
3. 点击左上角 +。
4. 选择 Add package from git URL...。
5. 输入以下地址并点击 Add：

点击左上角加号，然后选择“Add package from git URL...”。

https://github.com/codingriver/upilot.git#v0.2.0

安装完成后，Package Manager 中应显示包名 UPilot，包标识为：

io.github.codingriver.upilot

方式二：手动修改 manifest.json

如果 Package Manager 无法添加 Git URL，可以打开 Unity 项目的 Packages/manifest.json，在 dependencies 中加入：

{
  "dependencies": {
    "io.github.codingriver.upilot": "https://github.com/codingriver/upilot.git#v0.2.0"
  }
}

如果文件中已有其他依赖，请只增加这一项，并注意上一项末尾的逗号。保存后返回 Unity，等待包解析和脚本编译完成。

安装 Python 服务依赖

Unity 包内已经包含 UPilot 服务启动脚本，但运行它仍需要 Python 依赖。推荐直接安装与 Unity 包相同版本的 Python 包：

python -m pip install "git+https://github.com/codingriver/[email protected]#subdirectory=upilotserver~"

安装完成后可以执行以下命令进行检查：

python -c "import mcp, websockets, yaml, PIL; print('UPilot Python dependencies OK')"

看到 UPilot Python dependencies OK 即表示依赖可用。

如果电脑安装了多个 Python，请确保执行安装命令的 Python 版本为 3.11 或更高，并且可以从系统 PATH 中找到。

首次配置教程

使用简化设置（推荐）

首次导入 UPilot 后，主界面会提示“完成一次简单设置”。

1. 选择常用 Agent。
2. 点击 配置并启动。
3. 等待状态从“正在启动”变为“已就绪”。

Codex、Claude 和 Cursor 可以单选或多选。

选择多个 Agent 时，UPilot 会同时写入这些 Agent 的项目级 MCP 配置。之后也可以在主界面的 Agent 配置 区域单独添加其他 Agent。

配置过程中会发生什么

UPilot 会自动处理以下内容：

• 为当前 Unity 项目选择可用的本地端口。
• 启动 Unity Bridge 和 MCP 服务。
• 写入所选 Agent 的项目级 MCP 连接。
• 写入或更新 UPilot 管理的 Agent 规则。
• 为 Codex 同步 UPilot Skill。

已有配置文件中的其他 MCP 服务和用户内容会尽量保留。UPilot 管理的内容使用独立标记或独立配置项进行更新。

MCP 地址

默认地址是：

http://127.0.0.1:8011/mcp

实际地址会显示在 UPilot 主界面的 MCP 地址 区域，点击 复制 即可复制。

请始终使用界面显示的实际地址。多项目或端口冲突时，UPilot 可能会选择其他 HTTP 端