Unity MCP 详细部署教程

Unity MCP 是一个为 Unity 引擎设计的 AI 游戏开发助手，它通过 MCP (模型上下文协议) 将 Claude、Cursor、Windsurf 等 AI 编程工具直接连接到 Unity 编辑器。它可以让 AI 自动执行场景操作、生成代码、运行测试，甚至可以在您的游戏运行时提供动态 AI 交互。

本教程将指导您完成从安装到使用的全流程。

1. 准备工作

1.1 系统要求

  • Unity 编辑器：Unity 2021.3 LTS 或更新版本。
  • 项目路径：Unity 项目路径中不能包含空格。
    • ✅ 正确: C:/MyProjects/MyProject
    • ❌ 错误: C:/My Projects/My Project
  • AI 代理：您需要至少一个支持的 AI 工具（如 Claude Code、Cursor、GitHub Copilot 等）。
  • 可选：Node.js 和 npm (用于使用 CLI 工具)。

1.2 两种安装方式

您可以选择以下任一方式安装 Unity MCP 插件：

  1. 图形化安装：下载 .unitypackage 文件并导入 Unity。
  2. 命令行安装 (CLI)：使用 unity-mcp-cli 工具进行安装（推荐）。

2. 安装 Unity MCP 插件

2.1 方式一：图形化安装

  1. 从项目的 GitHub Releases 页面 下载最新的 AI-Game-Developer-MCP-Plugin.unitypackage 文件。
  2. 在 Unity 编辑器中，双击该文件，或通过菜单 Assets → Import Package → Custom Package 导入。
  3. 在弹出的导入窗口中，点击 Import 按钮，等待导入完成。

2.2 方式二：使用 CLI 工具安装（推荐）

CLI 工具提供了更完整的自动化流程。

  1. 安装 CLI 工具：

    1
    npm install -g unity-mcp-cli

  2. （可选）安装 Unity：

    1
    unity-mcp-cli install-unity

  3. （可选）创建新 Unity 项目：

    1
    unity-mcp-cli create-project ./MyUnityProject

  4. 将插件安装到现有项目（将路径替换为你的项目路径）：

    1
    unity-mcp-cli install-plugin ./MyUnityProject

  5. 登录 AI 服务（这会打开浏览器进行 OAuth 认证）：

    1
    unity-mcp-cli login

  6. 打开 Unity 项目（这会启动 Unity 并自动连接）：

    1
    unity-mcp-cli open ./MyUnityProject

  7. 等待 Unity 准备就绪：

    1
    unity-mcp-cli wait-for-ready ./MyUnityProject

3. 配置 AI 代理

安装插件后，需要配置您的 AI 代理（如 Claude Code、Cursor）以连接到 Unity。

3.1 自动配置（推荐）

  1. 在 Unity 编辑器中，打开菜单 Window → AI Game Developer。
  2. 在打开的窗口中，点击 Auto-generate Skills 按钮。这会自动生成并配置所需的技能文件。
  3. （如果上面的方法无效）点击 Configure MCP 按钮，在弹出的界面中复制 MCP 配置 JSON，然后按照您的 AI 客户端的说明手动粘贴。

3.2 手动配置（以 Claude Code 为例）

您也可以手动配置 AI 代理的 MCP 服务器。

  1. 在 Unity 中，通过 Window → AI Game Developer 窗口，找到您的 Port (端口，默认为 8080)。

  2. 根据您的操作系统，构建启动命令。例如 Windows x64：

    1
    "<你的Unity项目路径>/Library/mcp-server/win-x64/gamedev-mcp-server.exe" port=8080 client-transport=stdio

  3. 在您的 AI 代理中（如 Claude Code），使用以下命令添加 MCP 服务器：

    1
    claude mcp add ai-game-developer "<上一步构建的命令>"

4. 核心功能与使用示例

配置完成后，您就可以在 AI 代理的聊天窗口中与 Unity 进行交互了。

4.1 常用功能

  • 创建与修改游戏对象：
    • “Create 3 cubes in a circle with radius 2”
    • “Create a metallic golden material and attach it to a new sphere”
  • 执行代码与测试：
    • “Add a Rigidbody component to the selected cube”
    • “Run the EditMode tests and fix the failures”
  • 场景与资产管理：
    • “List all shaders in the project”
    • “Save the current scene as ‘Level1’”
    • “Create a prefab from the selected GameObject”

4.2 核心特性

  • 70+ 内置工具：覆盖了资产操作、场景管理、脚本编辑、性能分析等多个方面。
  • 反射驱动：AI 可以查找并调用您项目中的任何 C# 方法，甚至包括私有方法。
  • 动态代码执行：AI 可以使用 Roslyn 编译并执行 C# 代码片段，实现快速迭代。
  • 运行时支持：您可以在构建的游戏中使用 Unity MCP，让 AI 参与游戏逻辑（如 AI 驱动的棋类游戏机器人）。

4.3 扩展自定义工具

您可以在自己的 Unity 脚本中添加自定义工具，让 AI 使用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
using UnityEngine;
using UnityMCP;

[AiToolType]
public class MyCustomTools
{
    [AiTool("MyCustomTask", Title = "Create a new GameObject")]
    [Description("Explain to LLM what this does.")]
    public string CustomTask([Description("Explain the parameter.")] string inputData)
    {
        // 需要与Unity API交互时，使用主线程
        return MainThread.Instance.Run(() =>
        {
            // 你的逻辑代码
            return "[Success] Operation completed.";
        });
    }
}

5. 高级部署选项

5.1 Docker 部署

您可以在 Docker 中运行 MCP 服务器，适合远程或团队协作。

对于 HTTP 连接 (streamableHttp)：

1
docker run -p 8080:8080 aigamedeveloper/mcp-server

然后配置 MCP 客户端指向 http://localhost:8080。

5.2 自定义配置

您可以通过环境变量或命令行参数来定制 MCP 服务器的行为，例如：

  • MCP_PLUGIN_PORT / --port：设置端口（默认 8080）。
  • MCP_PLUGIN_CLIENT_TRANSPORT / --client-transport：选择 stdio 或 streamableHttp 传输模式。
  • MCP_AUTHORIZATION / --authorization：设置认证模式（none, oauth, token）。

6. 常见问题与提示

  • 项目路径包含空格：这是最常见的问题，请确保项目路径没有任何空格。
  • AI 代理无法连接：
    • 确保 Unity 编辑器正在运行。
    • 检查 Unity 的 Window → AI Game Developer 窗口中的端口号，并与 AI 代理配置中的端口号保持一致。
    • 检查防火墙是否阻止了端口 8080（默认）。
  • 连接模式：插件支持 Cloud（通过 ai-game.dev 云服务）和 Custom（本地直连）两种模式，您可以在 Unity 的 AI Game Developer 窗口中切换。
  • 为团队禁用更新通知：对于多人团队项目，可以在 Edit → Project Settings → AI Game Developer 中启用 “Disable update notifications for the entire team”，并将该设置文件提交到版本控制。
  • 卸载插件：通过 Window → Package Manager，找到 AI Game Developer — MCP 并移除，然后手动删除 Assets/Plugins/NuGet 文件夹。

总结

通过以上步骤，您应该能够成功将 Unity MCP 部署到您的 Unity 项目中，并将其连接到您喜欢的 AI 编程助手。Unity MCP 的核心价值在于将 AI 的能力无缝集成到 Unity 开发工作流中，让您能够通过自然语言与 Unity 编辑器交互，自动化重复任务，并探索 AI 辅助开发的新模式。

强烈建议您从 CLI 工具 开始快速上手，然后尝试在聊天中向 AI 下达一些简单的场景操作命令，体验其强大的功能。如果您对 AI 与游戏运行时结合感兴趣，可以深入研究运行时功能，探索 AI 驱动游戏逻辑的可能性。