使用 Cursor 控制 Unity —— Unity MCP 全流程实践及问题排查目录

lnsnxaq

于 2025-04-11 15:57:19 发布

阅读量968

点赞数 27

文章标签： unity 游戏引擎

本文链接：https://blog.csdn.net/lnsnxaq/article/details/147146618

版权

使用 Cursor 控制 Unity —— Unity MCP 全流程实践及问题排查

项目简介
环境准备
Unity MCP Bridge 安装与配置
MCP Server 启动与自动配置
使用 Cursor 控制 Unity —— 创建物体示例
常见问题及错误排查
- “remote origin already exists” 错误
- Cursor 配置文件路径/格式问题
- Unity MCP Bridge 与 MCP Server 端口不一致问题
总结与建议

1. 项目简介

本文主要介绍如何通过 Unity MCP 系统，实现用 Cursor直接输入指令，控制 Unity 编辑器进行游戏开发任务（如创建物体、清空控制台等）。本文内容基于 GitHub 上 unity-mcp 项目的最新版本，并结合实际调试过程中的错误信息和解决方案。

2. 环境准备

在开始之前，请确保以下软件和环境已正确安装：

Unity 编辑器（建议 2020.3 LTS 或更新版本）
Python 3.10 及以上
Git（用于克隆代码仓库）
uv 模块：在命令行中执行 pip install uv
Cursor 客户端（或 Claude Desktop，根据个人习惯选择）

3. Unity MCP Bridge 安装与配置

3.1 在 Unity 项目中导入 MCP Bridge 插件

打开 Unity 项目。
进入菜单 Window > Package Manager。
点击左上角的 “+” 按钮，选择 “Add package from git URL…”。

输入以下 Git URL：

https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge

点击 Add，等待安装完成。
安装完成后，通过 Window > MCP > MCP Editor 打开 MCP Bridge 面板，观察是否显示状态信息（如 “UnityMcpBridge started on port 6400”）。

3.2 常见错误：

出现错误信息 “remote origin already exists”
说明在安装过程中尝试执行 git remote add origin 时，发现仓库中已存在远程仓库。
解决方法：
如果代码是通过 ZIP 包下载的，不必担心；如果是克隆仓库，可在命令行进入 MCP Server 目录执行：
```
git remote remove origin
```
然后重新添加（可选）：
```
git remote add origin https://github.com/justinpbarnett/unity-mcp.git
```
该错误不会影响 MCP Bridge 的正常运行，可以忽略。

4. MCP Server 启动与自动配置

4.1 配置文件设置

Cursor 的 MCP 服务器配置文件存放在：

C:\Users\Administrator\.cursor\mcp.json

示例配置内容如下，请确保格式正确（替换为你的文件路径，注意使用正斜杠以避免转义问题）：

{
  "mcpServers": {
    "unityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "F:/_Unity/_Project/TestProject/UnityMCPTest/Packages/unity-mcp-master/UnityMcpServer/src",
        "server.py"
      ]
    }
  }
}

如果文件中显示黄灯，并提示 “Incorrect Path”，请检查 JSON 格式、路径是否存在、是否有多余的符号等。建议使用正斜杠 / 替换 Windows 路径中的 \，确保文件路径完全正确。

4.2 自动启动脚本（Windows 批处理）

为了方便启动 MCP Server，我制作了一个批处理脚本。内容如下，保存为 MCP_Server_Start.bat：

@echo off
title Unity MCP Server Launcher
echo 正在启动 Unity MCP Server...
cd /d "F:\_Unity\_Project\TestProject\UnityMCPTest\Packages\unity-mcp-master\UnityMcpServer\src"
uv run server.py
pause

使用方法：

双击运行 MCP_Server_Start.bat。
如果一切正常，命令行会显示类似：
```
INFO: Connected to Unity at localhost:6400
```
表示 MCP Server 已经与 Unity MCP Bridge 建立连接。

4.3 端口注意事项

Unity MCP Bridge 显示的端口为 6400，而 MCP Server 默认监听可能为 6500。
目前，unity-mcp 的 server.py 默认使用 transport='stdio' 方式，与客户端通信不依赖 TCP 端口。
因此，只需保证：

Unity MCP Bridge 正常启动（显示端口 6400，连接状态为 “Connected”）
Cursor MCP Server 配置正常，并在配置文件中指定正确的目录

5. 使用 Cursor 控制 Unity —— 创建物体示例

5.1 在 Cursor 中新建 .py 文件

在 Cursor 左侧的文件浏览器中，定位到 MCP Server 代码所在目录（如 UnityMcpServer/src）。
右键空白处，选择 “新建文件”，命名为 create_cube.py。

5.2 编写控制指令代码

在 create_cube.py 中输入以下内容：

from tools.manage_gameobject import create_primitive

# 创建一个立方体
create_primitive("Cube")

说明：这里的 create_primitive 函数会调用 MCP Server 的工具模块，指令 Unity 创建一个 Cube。你也可以使用类似代码创建 Sphere、Light 等。

5.3 执行代码

确保 MCP Server 已经启动并连接 Unity。
在 Cursor 中打开 create_cube.py，然后按下 Ctrl + Enter 或点击界面上的 “Run with MCP” 按钮。
观察 Unity 编辑器，应该会在场景中自动生成一个 Cube。

5.4 使用中文指令

在 Cursor 的聊天窗口中，你也可以直接输入中文指令，例如：

创建一个红色球体，位置在 (0, 1, 0)

如果 MCP 客户端支持自然语言转代码（部分工具支持），会自动转换为相应的 Python 脚本并发送给 Unity 执行。

6. 常见问题及错误排查

6.1 “remote origin already exists” 错误

原因： 在安装 MCP Server 时，Git 发现远程仓库已经存在。
解决方案： 进入服务器代码目录（如果是 Git 仓库），运行：
```
git remote remove origin
```
该错误通常不会影响实际功能。

6.2 Cursor 配置文件黄灯提示 “Incorrect Path”

原因： 配置文件格式或路径写法不规范（例如混用了对象和字符串、路径中使用了错误的斜杠）。
解决方案：
- 将路径中的反斜杠 \ 改为正斜杠 /，并确保 JSON 格式正确。
- 示例正确配置参见上文 mcp.json 文件内容。
- 保存后重启 Cursor，黄灯应变为绿灯。

6.3 Unity MCP Bridge 与 MCP Server 连接不成功

原因：
- MCP Server 未启动或运行错误
- 配置文件路径不匹配
- 端口设置不一致（如果使用端口模式）
解决方案：
- 确认已通过批处理脚本或命令行运行 uv run server.py，终端显示 “Connected to Unity…”
- 在 Unity MCP Bridge 窗口中确认状态是否为 “Connected to MCP Client”
- 检查防火墙或杀毒软件是否阻止本地通信

6.4 自动启动与关闭流程

启动流程：

打开 Unity 项目（确保 MCP Bridge 插件已加载）
运行批处理脚本 MCP_Server_Start.bat（自动启动 MCP Server）
打开 Cursor 客户端（配置文件位于 C:\Users\Administrator\.cursor\mcp.json，显示 unityMCP 为绿灯）
在 Cursor 中执行控制指令（如新建 .py 文件，执行 create_cube.py 等）