项目简介

MCP for Unity 是一个强大的桥梁，它允许 AI 助手（如 Claude、Cursor 等 LLM 客户端）直接与您的 Unity 编辑器进行交互。通过本地运行的 MCP 服务器，您可以利用自然语言指令来管理 Unity 项目中的资源、控制场景、编辑脚本和自动化重复性任务，从而革新您的游戏开发流程。

主要功能点

• 自然语言控制: 使用 AI 助手通过对话来指导 Unity 执行各种开发任务。
• 强大的工具集: LLM 可以调用一系列预定义的工具来操作 Unity。例如：
  • 管理资产: 导入、创建、修改、删除材质、预制体等。
  • 场景控制: 加载、保存场景，获取场景层级结构。
  • 游戏对象管理: 创建、修改、删除、查找游戏对象及其组件。
  • 脚本编辑: 创建、删除 C# 脚本，以及通过精确的文本编辑或结构化编辑来修改脚本内容。
  • 编辑器操作: 控制 Unity 编辑器的状态、设置，执行菜单项，运行测试等。
• 自动化工作流: 自动化重复性或复杂的 Unity 开发任务，提高生产力。
• 可扩展性: 支持注册项目自定义工具，以便根据具体需求扩展功能。
• 多传输协议支持: 默认支持 HTTP 连接，并提供传统的 Stdio (标准输入输出) 连接作为备用。
• 多实例支持: 支持同时连接和管理多个 Unity 编辑器实例，并可指定工具操作的目标实例。

安装步骤

1. 安装必要软件:

   • Python: 确保您的系统已安装 Python 3.10 或更高版本。您可以从 Python 官方网站下载。
   • Unity Hub & Editor: 确保您已安装 Unity Hub 及 Unity Editor 2021.3 LTS 或更高版本。
   • uv (Python 工具链管理器): 推荐使用 'uv' 来管理 Python 依赖，它是一个快速且高效的工具。
     • 对于 macOS / Linux，打开终端执行命令: 'curl -LsSf https://astral.sh/uv/install.sh | sh'
     • 对于 Windows，打开 PowerShell 执行命令: 'winget install --id=astral-sh.uv -e'
     • 详细安装指南请参阅 'uv' 官方文档。
   • MCP 客户端: 下载并安装您偏好的 MCP 客户端，例如 Claude Desktop、Cursor、Visual Studio Code Copilot 等。

2. 安装 Unity Package:

   • 打开您的 Unity 项目。
   • 在 Unity Editor 中，选择菜单 'Window > Package Manager'。
   • 点击 '+' 按钮，然后选择 'Add package from git URL...'。
   • 在弹出的输入框中输入以下 Git URL:

     https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity
     

   • 点击 'Add' 按钮，等待 Unity 安装包。

3. 启动本地 HTTP 服务器:

   • 在 Unity Editor 中，选择菜单 'Window > MCP for Unity'。
   • 确保窗口中的 Transport 下拉菜单设置为 'HTTP' (这是默认选项)。
   • 确认 HTTP URL 设置为您想要的地址 (例如 'http://localhost:8080')。
   • 点击 Start Local HTTP Server 按钮。Unity 将会自动启动一个运行 MCP 服务器的操作系统终端窗口。请保持此终端窗口开启，以便服务器能够持续运行并与 Unity 进行通信。如果您需要关闭服务器，可以点击 Unity 窗口中的 'Stop Session' 按钮。

服务器配置 (供 MCP 客户端使用)

MCP 客户端需要知道如何连接到 MCP for Unity 服务器。您可以选择自动配置（如果客户端支持）或手动编辑客户端的配置文件。

• 自动配置 (推荐用于 Claude/Cursor/VSC Copilot):

  1. 在 Unity 中，打开 'Window > MCP for Unity' 窗口。
  2. 点击 'Auto-Setup' 按钮。
  3. 观察状态指示器变为绿色 🟢 并显示 "Connected ✓"，表示配置成功。

• 手动配置: 如果自动配置失败或您使用其他 MCP 客户端：

  1. 找到您的 MCP 客户端配置文件。这通常是一个 JSON 文件，例如对于 Claude Desktop，macOS 上可能在 '~/Library/Application Support/Claude/claude_desktop_config.json'，Windows 上可能在 '%APPDATA%\Claude\claude_desktop_config.json'。对于 VS Code，可能在 'Code/User/mcp.json'。请查阅您客户端的文档获取具体位置。
  2. 编辑文件以添加 MCP 服务器信息：
     • 对于 HTTP 传输 (默认): 在客户端配置中，您需要声明一个 MCP 服务器，并提供其类型为 'http' 和对应的 'url'。 例如，如果您在 Unity 中将 HTTP URL 设置为 'http://localhost:8080'，则客户端配置的 'url' 应该设置为 'http://localhost:8080/mcp'。 'server name' 可以自定义，如 'UnityMCP'。
     • 对于 Stdio 传输 (可选): 如果您选择使用 'Stdio' 传输（在 Unity 'Window > MCP for Unity' 中将 Transport 设置为 'Stdio'），客户端配置的 'type' 应为 'stdio'。您还需要提供 'command' 和 'args' 参数：
       • 'command': 这是用于启动 MCP 服务器可执行文件的命令，通常是 'uv' (如果您使用 'uv' 管理) 或 'python'。
       • 'args': 这是传递给 'command' 的参数列表，用于指定服务器的启动方式，例如 '--directory' (指向服务器 'Server/src' 目录的绝对路径)、'run server.py'、'--transport stdio'。请确保路径正确，并且 '-' 或 '--' 参数格式与您的客户端要求一致。 重要提示：请根据您实际的 MCP 客户端和 MCP for Unity 服务器安装路径，替换配置中的 'url'、'command' 和 'args' 路径。

基本使用方法

1. 打开您的 Unity 项目，并确保 MCP for Unity 的本地 HTTP 服务器正在运行（通过 'Window > MCP for Unity' 窗口检查状态，显示 "Session Active" 即表示服务器已启动）。
2. 启动您的 MCP 客户端（如 Claude、Cursor 等）。客户端将自动连接到您在安装步骤 3 或配置步骤中设置的 HTTP 端点。
3. 开始互动！ 现在，Unity 的工具和资源应该在您的 MCP 客户端中可用。您可以尝试用自然语言指令来控制 Unity，例如：
   • 'Create a 3D player controller' (创建一个 3D 玩家控制器)
   • 'Create a tic-tac-toe game in 3D' (创建一个 3D 井字游戏)
   • 'Create a cool shader and apply to a cube' (创建一个炫酷的着色器并应用于一个立方体)
   • 处理多 Unity 实例: 如果您同时运行多个 Unity 编辑器实例，可以通过请求 'unity_instances' 资源来列出所有可用的实例（会显示 'Name@hash' 格式的唯一标识符）。然后，使用 'set_active_instance' 工具并提供确切的 'Name@hash' 来指定您希望操作的 Unity 实例，例如 'set active instance to MyProject@abc123'。