AI导哈

Unity开发工具

Unity MCP提供了一系列工具，通过Model Context Protocol桥接Unity Editor和MCP客户端（如Claude、Codex等），以提高开发效率。

  • by doyasu24
  • C#
  • 本地部署
  • 更新于
在 GitHub 查看 doyasu24/unity-mcp

使用说明

Unity MCP

Unity MCP通过以下方式连接Unity编辑器和MCP客户端（Claude、Codex等） 模型上下文协议. 它提供了实用的工具，使开发周期更加高效。

graph LR
    A["MCP Client<br/>(Claude Code / Codex)"] -->|"MCP<br/>(HTTP)"| B["Unity MCP Server"]
    B <-->|"WebSocket"| C["Unity Editor"]

可用工具

工具 它做什么
编辑器控件
get_editor_state 返回当前服务器/编辑器连接状态。
get_play_mode_state 只读：获取当前Unity编辑器播放模式状态。
control_play_mode 编辑：控制Unity编辑器播放模式（开始、停止、暂停）。
read_console 读取Unity控制台条目。
clear_console 清除Unity控制台日志条目。
refresh_assets 刷新Unity编辑器资源。如果脚本更改，则等待重新编译。出现错误时返回。
run_tests 运行Unity测试并返回结果。
场景管理
list_scenes 列出Unity项目中的所有场景文件。
open_scene 在Unity编辑器中打开场景。
save_scene 保存当前场景或特定的打开场景。
create_scene 创建新场景并将其保存到指定路径。
unload_scenes 快照打开的场景设置并卸载所有场景（打开一个空场景），以便打开的场景 .unity 文件可以在磁盘上编辑，而不会触发Unity的“外部修改场景”对话框。返回的设置 restore_scenes.
restore_scenes 恢复由捕获的场景设置 unload_scenes，从磁盘重新打开原始场景（拾取外部编辑）。
场景/预制层次和组件
get_hierarchy 返回包含组件类型名称的场景或预制资源的游戏对象树。支持分页 offset.通行证 prefab_path 用于预制模式。
get_component_info 返回场景或预制游戏对象上特定组件的序列化字段值。
manage_component 添加、更新、删除或重新排序场景或预制游戏对象上的组件。
manage_game_object 在活动场景或预制资源中创建、更新、删除或重新修复游戏对象。
find_game_objects 按名称、标记或组件类型在活动场景或预制资源中搜索游戏对象。支持分页 offset.
instantiate_prefab 将预制资源实例化到活动场景中，并保持预制链接。
资产搜索和信息
find_assets 使用AssetDatabase筛选器语法在项目中搜索资产。支持分页 offset.
get_asset_info 返回指定路径上Unity资源的详细元数据。
manage_asset 创建或删除Unity资源，并管理材质属性：获取/设置着色器属性、更改着色器和控制着色器关键字。
manage_prefab 创建、应用或恢复预制资源。
构建
manage_build 管理Unity构建管道：获取/设置构建设置，添加/删除/重新排序场景，并执行构建。
截图
capture_screenshot 从游戏视图或场景视图中捕获屏幕截图。内联返回图像（base64 PNG），以便LLM可以直接看到它，并将副本保存到 <project>/Screenshots/.
运行时UI交互
tap_ui_element 点击正在运行的游戏（播放模式）中的uGUI元素以触发其点击处理程序（例如屏幕转换）。通过EventSystem分派真实指针事件。按层次结构路径定位(target_path)或屏幕坐标(x/y).
编辑器菜单
execute_menu_item 按路径执行编辑器菜单项（例如。 GameObject/Create Empty).阻塞菜单（模式/退出）也会运行并被标记 blocking=true一个真正的模态可以冻结桥梁，直到被解雇。仅在编译/导入时被拒绝。
list_menu_items 列出编辑器菜单项。每份报告 source （项目/包/内置）和 blocked.筛选条件 pattern （正则表达式）或 source；set include_blocked 包括屏蔽菜单。

分页

返回大型结果集的工具支持通过可选的基于偏移量的分页 offset 参数。当响应被截断时(truncated: true)，它包括a next_offset 可以作为传递的值 offset 在下次调用中获取下一页。

支持的工具： get_hierarchy, find_assets, find_game_objects

示例流程：

  1. 呼叫 find_assets 和 filter: "t:Material", max_results: 5 → 响应包括 next_offset: 5, total_count: 42
  2. 呼叫 find_assets 和 filter: "t:Material", max_results: 5, offset: 5 → 下一页结果

为了 get_hierarchy，当 offset > 0 响应返回一个平面 game_objects 数组而不是嵌套树格式，每个节点都包含其 path 用于识别。当 offset 是 0 （默认），响应格式不变。

先决条件

  • Unity编辑器（推荐Unity 6+）
  • .NET SDK 8+

快速开始

  1. 安装Unity软件包。
  2. 在本地设置项目 dotnet tool 版本（按项目固定）：
    dotnet new tool-manifest
dotnet tool install --local Doyasu24.UnityMcp.Tool --version 0.1.7
  3. 启动Unity MCP服务器（默认端口： 48091):
    dotnet tool run unity-mcp
  4. 在MCP客户端中注册服务器：
    • 克劳德代码：遵循 Claude Code Setup.
    • 食品法典：遵循 Codex Setup.
  5. 打开Unity项目，确保Unity MCP插件已启用。
  6. 在您的MCP客户端中，呼叫 get_editor_state 以验证连接。
  7. 开始使用以下工具 read_console 和 run_tests.

安装Unity软件包

添加到包管理器：

https://github.com/doyasu24/unity-mcp.git?path=UnityMCPPlugin/Assets/Plugins/UnityMCP#v0.1.7

Claude代码设置

运行：

claude mcp add -s project --transport http unity-mcp http://127.0.0.1:48091/mcp

然后重新启动Claude Code会话（或打开一个新会话）并确认 unity-mcp 服务器可用。

Codex设置

运行：

codex mcp add unity-mcp --url http://127.0.0.1:48091/mcp

然后验证服务器是否已注册：

codex mcp list

配置

仅当您需要自定义端口时，才使用此部分。

服务器端口

  • 默认端口： 48091.
  • 使用 --port 仅当您需要非默认端口时。
  • 例子：
    dotnet tool run unity-mcp --port 48092

Unity插件设置

从Unity编辑器窗口更改端口：

Unity MCP Settings

设置存储在：

ProjectSettings/UnityMcpPluginSettings.asset

规则：

  • port Unity设置中的端口必须与服务器端口匹配。
  • 服务器运行在 127.0.0.1 （本地机器）。
  • 此设置资产是项目范围的，应提交给版本控制。

工具版本管理（项目范围）

  • 提交 .config/dotnet-tools.json 到版本控制以固定每个项目的服务器版本。
  • 团队成员应该运行：
    dotnet tool restore
  • 要更新到新的固定版本，请执行以下操作：
    dotnet tool update --local Doyasu24.UnityMcp.Tool --version <NEXT_VERSION>

使用多个Unity编辑器

在多编辑器工作流中，使用 1个编辑器=1个MCP服务器.

这意味着：

  • 每个Unity Editor实例都使用自己的服务器实例。
  • 每个服务器/编辑器对必须使用唯一的端口。
  • 您的MCP客户端必须为每个Unity项目/编辑器注册一个服务器条目。

例子：

Unity项目 服务器端口 Claude/Codex服务器名称 MCP URL
项目A 48091 unity-a http://127.0.0.1:48091/mcp
项目B 48092 unity-b http://127.0.0.1:48092/mcp

CLI示例：

克劳德代码

claude mcp add -s project --transport http unity-a http://127.0.0.1:48091/mcp
claude mcp add -s project --transport http unity-b http://127.0.0.1:48092/mcp

法典

codex mcp add unity-a --url http://127.0.0.1:48091/mcp
codex mcp add unity-b --url http://127.0.0.1:48092/mcp

故障排除

MCP客户端无法连接

  • 确认服务器正在运行。
  • 确认客户端URL与服务器端口匹配。
  • 检查其他端口是否正在使用同一端口。

Unity和服务器未链接

  • 确认Unity插件 port 等于服务器 --port.
  • 更改端口后重新启动Unity和服务器。

Unity项目在多编辑器设置中响应错误

  • 验证每个项目是否使用不同的端口。
  • 验证您的MCP客户端是否以预期的服务器条目为目标(unity-a, unity-b等等）。

截图

capture_screenshot 将PNG文件保存到 <your-unity-project>/Screenshots/。将此目录添加到您的 .gitignore:

/Screenshots/

相关 MCP