# Unity MCP — AI Game Developer Wiki

Unity MCP 将 Claude Code、Cursor、Copilot 等 AI 智能体连接到 Unity 编辑器。从这里开始了解安装、配置、工具、扩展与 CLI。

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/unity)。

Unity MCP 是 AI Game Developer 的 Unity 插件。它把 AI 放进 Unity 编辑器：Claude Code、Cursor、GitHub Copilot、Codex 或 Gemini 这样的智能体可以读取并修改你的场景、GameObject、组件、预制体和资源，编写 C# 脚本，运行 C# 代码片段，运行你的 EditMode 和 PlayMode 测试，读取 Console 并截取它能查看的屏幕截图。本 wiki 说明如何安装该插件、连接 AI 客户端以及日常使用。

## Unity MCP 是什么

Unity MCP 是一个 Unity 包，`com.ivanmurzak.unity.mcp`，在 Package Manager 中显示为 **AI Game Developer — MCP**。它运行在 Unity 编辑器内部（如果你愿意，也可以运行在构建好的游戏中）。它通过 Model Context Protocol (MCP) 暴露一组工具，这是 AI 客户端调用外部工具所使用的开放标准。与你对话的智能体会看到这些工具，并调用它们来完成你要求的任务。

该插件基于 Apache-2.0 许可证开源，托管在 [Unity-MCP 仓库](https://github.com/IvanMurzak/Unity-MCP)中。它与 Unreal MCP 和 Godot MCP 共用 MCP 与反射库，因此三个引擎插件的工作方式相同，并使用同一个 ai-game.dev 账号。

从 1.0.0 版本起，大多数编辑器操作都通过 **RQL** 完成，这是一种面向编辑器数据的查询语言：一个 `rql-query` 工具负责读取，一个 `rql-mutate` 工具负责修改，`rql-schema` 描述可用的内容。另有少量专用工具覆盖截图、脚本、测试和包。参见 [工具与 RQL](https://ai-game.dev/zh-hans/docs/wiki/unity/tools-and-rql)。

## 各部分如何协同工作

| 组成部分 | 作用 |
| --- | --- |
| Unity MCP 插件 | 在 Unity 编辑器中运行，暴露 AI 工具并连接到 MCP 服务器。 |
| MCP 服务器 | 位于 ai-game.dev 的托管服务器（Cloud 模式，默认），或插件为你下载并启动的本地 `gamedev-mcp-server`（Custom 模式）。 |
| AI 客户端 | Claude Code、Claude Desktop、Cursor、VS Code Copilot、Codex、Gemini、Rider 等。它连接到同一个服务器。 |
| `unity-mcp-cli` | npm 命令行工具，用于安装插件、登录、写入 AI 客户端配置、打开 Unity 以及在终端中调用工具。 |
| AI Game Dev 应用 | 桌面应用，为你安装插件、打开编辑器并运行 AI 智能体。 |

在 **Cloud** 模式下，编辑器和你的 AI 客户端都连接到 `https://ai-game.dev/mcp`，你只需用 ai-game.dev 账号登录一次。在 **Custom** 模式下，插件会在你的机器上运行本地 MCP 服务器，因此一切都留在你的电脑上。[配置](https://ai-game.dev/zh-hans/docs/wiki/unity/configuration)对两者都有说明。

## 要求一览

- Unity **2022.3** 或更新版本，包括 Unity 6。
- 项目路径**不含空格**（如果路径包含空格，插件会在启动时记录错误）。
- 首次使用时需要互联网访问：插件从 NuGet 下载其 .NET 依赖项，在 Custom 模式下还会下载其 MCP 服务器二进制文件。
- 支持 MCP 的 AI 客户端，或 [AI Game Dev 应用](https://ai-game.dev/docs/app)。

## 快速开始

最简便的方式是使用桌面应用：[下载它](https://ai-game.dev/zh-hans/download)，登录并打开你的 Unity 项目。它会为你安装插件并完成连接。[应用 wiki](https://ai-game.dev/zh-hans/docs/wiki/app)介绍了该流程。

如果你更喜欢使用终端和自己的 AI 客户端，以下命令可将 Unity 项目连接到智能体：

```bash
npm install -g unity-mcp-cli
unity-mcp-cli install-plugin ./MyUnityProject
unity-mcp-cli login
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli open ./MyUnityProject
```

然后向你的智能体提出类似“Create 3 cubes in a circle with radius 2”的要求。[入门指南](https://ai-game.dev/zh-hans/docs/wiki/unity/getting-started)会带着说明走一遍相同的步骤。

## 本节页面

- [安装](https://ai-game.dev/zh-hans/docs/wiki/unity/installation)：安装插件的所有方式（应用、`unity-mcp-cli`、OpenUPM、`.unitypackage` 安装器）以及如何卸载。
- [入门指南](https://ai-game.dev/zh-hans/docs/wiki/unity/getting-started)：你的首次连接和首次提示。
- [连接 AI 客户端](https://ai-game.dev/zh-hans/docs/wiki/unity/connecting-ai-clients)：Cloud 与本地端点、登录、固定 URL 以及每个智能体的配置器。
- [配置](https://ai-game.dev/zh-hans/docs/wiki/unity/configuration)：AI Game Developer 窗口、连接模式、端口、配置文件、环境变量覆盖以及构建版本。
- [工具与 RQL](https://ai-game.dev/zh-hans/docs/wiki/unity/tools-and-rql)：智能体在编辑器中能做什么。
- [自定义工具](https://ai-game.dev/zh-hans/docs/wiki/unity/custom-tools)：把你自己的 C# 方法变成 AI 工具、提示和技能，包括在运行中的游戏里。
- [扩展](https://ai-game.dev/zh-hans/docs/wiki/unity/extensions)：针对 Animation、Cinemachine、Input System、Navigation、ProBuilder、Terrain、Tilemap、Timeline 等的可选包。
- [unity-mcp-cli 参考](https://ai-game.dev/zh-hans/docs/wiki/unity/cli)：每个命令和参数。
- [故障排除](https://ai-game.dev/zh-hans/docs/wiki/unity/troubleshooting)：常见问题的解决方法。
- [FAQ](https://ai-game.dev/zh-hans/docs/wiki/unity/faq)：常见问题的简短回答。

## 站点上的更多内容

- [Unity 工具目录](https://ai-game.dev/docs/tools/unity)和 [RQL 参考](https://ai-game.dev/docs/rql)。
- [Unity 扩展目录](https://ai-game.dev/docs/extensions/unity)。
- [Unity 最佳实践](https://ai-game.dev/docs/best-practices/unity)，用于提示词编写和项目设置。
- [MCP 端点](https://ai-game.dev/zh-hans/mcp-endpoint-info)，包含每个受支持客户端的配置片段。
- [身份验证](https://ai-game.dev/docs/auth)、[快速入门](https://ai-game.dev/zh-hans/docs/quickstart)和 [Unity 引擎页面](https://ai-game.dev/zh-hans/engines/unity)。
- 其他引擎：[Unreal MCP](https://ai-game.dev/zh-hans/docs/wiki/unreal)和 [Godot MCP](https://ai-game.dev/zh-hans/docs/wiki/godot)。

- [**安装** 通过桌面应用、unity-mcp-cli、OpenUPM 或 .unitypackage 安装器，在 Unity 项目中安装 Unity MCP（AI Game Developer）。](https://ai-game.dev/zh-hans/docs/wiki/unity/installation)
- [**快速开始** 使用 Unity MCP 将你的第一个 AI 智能体连接到 Unity 编辑器，检查连接状态，并在 Claude Code、Cursor 或 Copilot 中尝试你的第一批提示词。](https://ai-game.dev/zh-hans/docs/wiki/unity/getting-started)
- [**连接 AI 客户端** 通过 ai-game.dev 云端端点或本地服务器，将 Claude Code、Cursor、Copilot、Codex、Gemini 等 MCP 客户端连接到 Unity MCP。](https://ai-game.dev/zh-hans/docs/wiki/unity/connecting-ai-clients)
- [**配置** 在 AI Game Developer 窗口中配置 Unity MCP——Cloud 与 Custom 模式、本地服务器、端口、传输方式、授权、工具、覆盖项以及 CI。](https://ai-game.dev/zh-hans/docs/wiki/unity/configuration)
- [**工具与 RQL** AI 智能体在 Unity 编辑器中借助 Unity MCP 能做什么——RQL 查询与变更、截图、C# 脚本、测试、包管理与性能分析。](https://ai-game.dev/zh-hans/docs/wiki/unity/tools-and-rql)
- [**自定义工具** 使用 AiTool 特性以 C# 编写自己的 Unity MCP 工具、提示词、资源和技能，在主线程上运行，并在构建后的游戏中加以使用。](https://ai-game.dev/zh-hans/docs/wiki/unity/custom-tools)
- [**扩展** Unity MCP 扩展为 Animation、Cinemachine、Input System、Navigation、ProBuilder、Splines、Terrain、Tilemap、Timeline 和粒子系统添加 AI 支持。](https://ai-game.dev/zh-hans/docs/wiki/unity/extensions)
- [**unity-mcp-cli 参考** unity-mcp-cli 命令参考——安装 Unity MCP、登录、写入 AI 代理配置、无界面打开 Unity、从终端运行工具和 C#。](https://ai-game.dev/zh-hans/docs/wiki/unity/cli)
- [**故障排查** 解决常见的 Unity MCP 问题——AI 客户端中无工具、登录与连接错误、服务器下载失败、NuGet DLL 错误以及端口冲突。](https://ai-game.dev/zh-hans/docs/wiki/unity/troubleshooting)
- [**常见问题** 关于 Unity MCP 的常见问题解答——支持的 Unity 版本与 AI 客户端、Cloud 与本地模式、费用、隐私、构建、CI 与 RQL。](https://ai-game.dev/zh-hans/docs/wiki/unity/faq)

---

Source (HTML): https://ai-game.dev/zh-hans/docs/wiki/unity

Machine-translated (zh-Hans) from the English page: https://ai-game.dev/docs/wiki/unity