Unity MCP 工具参考完全指南基于 Python 工具注册表自动生成的 48 个 MCP 工具全景目录【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp本文以 Unity MCP 工具参考目录website/docs/reference/tools/index.md为核心骨架结合仓库中的工具注册表源码、文档生成器与相关测试系统梳理 Unity MCP 对外暴露的全部工具分组、每个工具的能力边界、分组可见性管理机制以及这套参考文档的自动生成流水线。读完本文你将能熟练按分组检索 Unity MCP 的任一工具理解核心组默认开启、其余分组按需激活的会话级可见性模型并能用manage_tools元工具动态控制当前会话的工具清单。Unity MCP 是 AI 助手与 Unity Editor 之间的桥梁它把所有能力抽象为一组 MCP 工具Tools管理资产、控制场景、编辑脚本、执行构建、运行测试等。这些工具并非手写文档维护而是直接由 Python 侧的mcp_for_unity_tool注册表自动生成参考文档。本文介绍的就是这份工具总目录本身它包含多少个工具分组、每个分组下有哪些工具、每个工具能做什么、以及这套目录是如何被自动维护的。一、文档的生成机制Python 注册表是唯一事实来源打开 website/docs/reference/tools/index.md 的顶部会看到一段醒目标注Auto-generated from the Python tool registry. Do not hand-edit...自动生成自 Python 工具注册表请勿手工编辑。这揭示了一个关键架构决策唯一事实来源Single Source of Truth是Server/src/services/tools/目录下所有 Python 模块中的mcp_for_unity_tool装饰器注册表C# 侧属性只携带Name/Group/Description等基础元数据而 Python 装饰器持有最丰富的类型信息通过Annotated[...]描述参数文档并且这正是 MCP 客户端在网络上实际看到的内容生成的产物包括每个工具的独立页面website/docs/reference/tools/group/tool-name.md每个分组的地页面website/docs/reference/tools/group/index.md分组总目录website/docs/reference/tools/index.md以及资源目录website/docs/reference/resources/index.md。生成器的工作模式生成器脚本是 tools/generate_docs_reference.py支持两种模式模式行为--write默认就地重新生成全部参考页面--check生成到临时目录并与已提交文件 diff一旦出现漂移即非零退出供 CI / pre-commit 钩子使用生成过程的核心步骤在load_registries()中脚本将Server/src加入sys.path然后利用 module_discovery.py 中的discover_modules()遍历并导入services.tools与services.resources包下所有模块——装饰器的副作用向全局注册表追加条目在这一过程中被触发注册表随即被填满。值得注意的细节--check模式main()中的--check分支仍会从已提交的规范位置读取手工编写的 examples 块因此 CI 校验不会破坏示例内容。若校验失败脚本会提示python tools/generate_docs_reference.py然后提交改动。仓库中的 CI 运行方式见脚本 docstringcd Server uv sync cd .. uv --project Server run python tools/generate_docs_reference.py --check手工示例的保留机制生成器通过!-- examples:start --与!-- examples:end --标记对来保护手工编写的示例生成时会从既有文件中抽取这两个标记之间的内容并在重写后原样保留未添加示例的页面则会写入占位提示。例如 manage_tools 工具页 当前的 Examples 段就是占位符!-- examples:start -- *No examples yet. Add usage examples here — they will be preserved across regenerations.* !-- examples:end --这意味着任何工具页的 Examples 区域都允许社区手工补充且不会被自动生成覆盖。参数表如何生成生成器通过inspect.signature与typing.get_type_hints(include_extrasTrue)对每个工具函数做内省introspect_params()从Annotated[T, 描述文本]中提取参数说明渲染为 Markdown 参数表NameTypeRequiredDescriptionactionLiteral[list_groups, activate, deactivate, sync, reset]yesAction to perform.groupstr \| None—Group name (required for activate / deactivate). Valid groups: animation, asset_gen, core, docs, probuilder, profiling, scripting_ext, testing, ui, vfx同时_render_type()负责把复杂注解Annotated、Union、Literal、list[...]、dict[...]渲染成简洁、Markdown 安全的类型字符串——这正是每个工具页参数表里类型列的来源。二、分组总览10 个领域分组、48 个工具根据 总目录Unity MCP 当前暴露10 个工具分组、共 48 个工具。分组的权威定义在 tool_registry.py 的TOOL_GROUPS字典中与文档中逐个##小节一一对应分组工具数领域说明core30场景、脚本、资产与编辑器核心工具默认开启asset_gen5AI 资产生成3D 模型生成/导入、2D 图像与音频生成自带 API Keydocs2Unity API 反射与文档查询vfx3视觉特效VFX Graph、Shader、程序化纹理animation1Animator 控制与 AnimationClip 创建ui1UI ToolkitUXML、USS、UIDocumentscripting_ext2ScriptableObject 管理testing2测试运行器与异步测试任务probuilder1ProBuilder 3D 建模需com.unity.probuilder包profiling1Profiler 会话控制、计数器、内存快照与 Frame DebuggerTOOL_GROUPS中每个分组还带有供文档与manage_tools展示的 blurb一句话描述。此外注册表接受特殊分组值None表示该工具始终可见、不受分组开关影响——用于set_active_instance、manage_tools这类服务器元工具。三、逐组工具清单与能力速查3.1core核心组30 个默认开启这是最重要的分组覆盖 AI 助手操作 Unity 的日常高频能力见 core 分组页脚本编辑类apply_text_edits按 URI 对 C# 脚本做小范围文本编辑、script_apply_edits结构化 C# 编辑支持方法/类级的安全边界官方建议优先于裸文本编辑、create_script、delete_script、get_sha返回脚本 SHA256 与元数据但不返回文件内容、validate_script校验并返回诊断、find_in_file正则搜文件并返回行号与片段场景与对象类find_gameobjects按名称、标签、层级、组件类型或路径搜索、manage_gameobjectGameObject CRUD、manage_components增删组件与设置属性、manage_scene场景 CRUD、manage_prefabs、manage_cameraUnity Camera Cinemachine资产与资源类manage_asset导入/创建/修改/删除等资产操作、manage_material、manage_texture、manage_packages查询/安装/移除/嵌入包与配置源、manage_build触发构建、切换平台、配置设置、管理构建场景与配置档、跨平台批量构建编辑器控制类manage_editor控制并查询编辑器状态与设置、execute_menu_item按路径执行 Unity 菜单项、read_console读取或清空编辑器控制台、refresh_unity请求资源数据库刷新并可附带脚本编译、debug_request_context返回当前 FastMCP 请求上下文client_id、session_id 与 meta dump、batch_execute单批执行多条 MCP 命令显著提升性能会话与兼容类manage_tools控制本会话可见的工具分组、set_active_instance设置本客户端/会话的活跃 Unity 实例、execute_custom_tool执行 Unity 注册的项目级自定义工具、manage_script旧版脚本操作的兼容路由、manage_script_capabilities查询 manage_script 支持的操作、限制与保护、manage_graphics体积雾、后处理、光照烘焙、渲染统计、渲染管线设置与 URP Renderer Feature、manage_physics物理设置、碰撞矩阵、材质、关节、查询与校验。3.2asset_genAI 资产生成组5 个自带 API Keybring-your-own-key的 AI 生成能力详见 asset_gen 分组页generate_model— 用 AI 供应商Tripo、Meshy生成 3D 模型并导入 Unity 项目generate_image— 用 AI 供应商fal.ai、OpenRouter生成 2D 图像并作为纹理/Sprite 导入generate_audio— 用 fal.ai 模型生成音效与背景音乐并导入为 AudioClipimport_model— 从 Sketchfab 市场导入 3D 模型import_model_file— 导入磁盘上已有的本地 3D 模型文件如从 Blender 或其他 DCC 工具导出的 FBX/OBJ/glTF。3.3docs文档与反射组2 个unity_docs— 从 docs.unity3d.com 获取官方 Unity 文档unity_reflect— 通过反射检视 Unity 实时的 C# API。3.4vfx视觉特效组3 个manage_shader— 管理 Unity 中的 Shader 脚本创建、读取、更新、删除manage_texture— Unity 程序化纹理生成manage_vfx— 管理 VFX 组件ParticleSystem、VisualEffect、LineRenderer、TrailRenderer。3.5scripting_ext脚本扩展组2 个execute_code— 在 Unity 编辑器内执行任意 C# 代码manage_scriptable_object— 使用 UnitySerializedObject属性路径创建与修改 ScriptableObject 资产。3.6testing测试组2 个异步模型run_tests— 异步启动 Unity 测试运行立即返回job_idget_test_job— 用job_id轮询异步测试任务的进度与结果。3.7 其余单工具分组animation/manage_animation— Animator 控制与 AnimationClip 创建ui/manage_ui— 管理 UI Toolkit 元素UXML 文档、USS 样式表、UIDocument 组件probuilder/manage_probuilder— ProBuilder 网格编辑实现编辑器内 3D 建模需安装com.unity.probuilder包profiling/manage_profiler— Profiler 会话控制、计数器读取、内存快照与 Frame Debugger。四、分组可见性模型为什么 core 默认开启、其余按需激活目录页会告诉你核心工具默认开启但底层机制是什么答案在 tool_registry.py 与 tools/init.py 的register_all_tools()中装饰器打标签mcp_for_unity_tool(..., groupvfx)会把tags{group:vfx}合并进该工具传递给 FastMCP 的 kwargs。注册表维护DEFAULT_ENABLED_GROUPS {core}即仅 core 分组默认启用。HTTP 模式启动即瘦身register_all_tools()在 transport 为 HTTP 时会把TOOL_GROUPS.keys() - DEFAULT_ENABLED_GROUPS中所有分组的 tool 组件disable掉让新会话从精简的 core 工具集开始Unity 连接后通过PluginHub._sync_server_tool_visibility重新按需启用。Stdio 模式全量开启后同步由于旧版 TCP 桥没有register_tools消息stdio 模式启动时会话内全部分组可见随后由sync_tool_visibility_from_unity()通过get_tool_states资源查询 Unity 的开关状态并回填可见性。groupNone豁免set_active_instance与manage_tools属于服务器元工具unity_targetNone, groupNone永远可见、不受分组系统影响。对验证该模型感兴趣的读者可在仓库测试中看到相应断言例如 Server/tests/test_tool_registry_metadata.py 与 Server/tests/test_tool_annotations.py。五、实战用manage_tools动态控制会话工具清单manage_tools是理解分组模型后最值得立即上手的工具其源码位于 manage_tools.py工具页见 manage_tools.md。它支持五种actionaction作用list_groups列出所有分组及其当前状态、默认是否启用、包含哪些工具activate启用某个分组需传group其工具立刻出现在工具列表中deactivate隐藏某个分组sync从 Unity 编辑器的工具开关状态刷新可见性reset恢复服务器默认即只保留 core 组典型对话式用法manage_tools(actionlist_groups) manage_tools(actionactivate, groupprofiling) # 激活 Profiler 相关工具 manage_tools(actiondeactivate, groupvfx) # 隐藏 VFX 工具 manage_tools(actionreset) # 恢复默认从源码看activate/deactivate分别调用 FastMCP 的ctx.enable_components/ctx.disable_components按group:name标签作用于 tool 组件基于 FastMCP 3.x 的会话级可见性因此在 stdio、HTTP、SSE 所有传输上都生效sync会调用上一节提到的sync_tool_visibility_from_unity(notifyTrue)并在 Unity 包版本过旧不支持get_tool_states时给出明确的升级提示与降级建议。六、配套使用实例路由与批量执行掌握目录后有两个工具值得配套理解set_active_instance源码见 set_active_instance.py在多开 Unity 实例的场景下通过Namehash、哈希前缀stdio 下还支持端口号选定当前会话路由的目标实例HTTP 远程托管模式下端口号定位不可用需用Namehash或哈希前缀可先读取mcpforunity://instances资源确认可用实例。batch_execute把多条 MCP 命令打包成一次调用执行是 AI 助手连续操作场景下戏剧性提升性能的关键手段适合脚本批量调整、批量资产操作等任务。七、如何继续深入文档分层与维护闭环整个参考体系是分层、可追溯的总目录本文主题→ 2.分组页website/docs/reference/tools/group/index.md→ 3.单工具页website/docs/reference/tools/group/tool.md含描述、参数表、返回说明与 Examples 区→ 4.Python 源码Server/src/services/tools/*.py中的装饰器函数。每一层都有对应的 Docusaurus 侧边栏配置各分组目录下的_category_.json使侧边栏以可折叠分类呈现。若你在浏览中发现问题或想补充某工具的示例正确做法是修改或补充对应工具 Python 模块中的描述与Annotated[...]参数注释或向工具页的 examples 标记块内添加示例然后重新运行生成器——切勿手工编辑自动生成区否则会在 CI 的--check阶段产生漂移告警。总结这份工具参考目录是 Unity MCP 能力地图的入口。通过它你可以按领域快速定位 48 个工具中的任意一个理解core 常驻、其他分组按需激活的会话模型并借助manage_tools、set_active_instance、batch_execute等元工具构建高效、可路由、可裁剪的 AI 驱动 Unity 工作流。【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考