Unity MCP v10 完整解析从 29 到 47 个工具入口的资产生成、密钥安全与升级指南【免费下载链接】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导读本文基于仓库内 docs/wiki/V10.mdv10 Release Notes展开系统梳理 MCP for Unity 从 v9.0.0 到 v10 的主版本跃迁工具目录从 29 个 MCP 工具入口扩展至 47 个并划分为 10 个功能组、新增asset_genAI 资产生成/导入工具组、引入基于操作系统安全存储的 Provider 密钥管理、Blender 等 DCC 工具的本地文件交接流程以及文档、品牌与安全模型的整体刷新。读完本文你将掌握 v10 的工具分组与 opt-in 机制、四个资产生成工具的完整用法与异步任务模型、密钥安全边界以及从 v9 升级到 v10 的完整步骤与排障方法。一、v10 版本全景从 29 到 47 个工具入口v10 是 MCP for Unity 的完整主版本升级。以 v9.0.0 为基线对比v9.7.3 标签更适合做逐版本 changelog但它已经包含大量 v9 时期的工具扩展v10 的核心变化如下领域v9.0.0基线v10 版本工具目录29 个 MCP 工具入口多数工具直接注册在单一可见表面47 个 MCP 工具入口按领域分组工具可见性无装饰器级分组元数据无manage_tools工作流工具注册表具备命名分组core默认启用非 core 分组 opt-in编辑器自动化领域场景/对象/组件/脚本/资源/预制体/材质/着色器/VFX/测试/编辑器等核心操作新增构建编排、相机/Cinemachine 控制、渲染管线与图形操作、包管理、物理、动画、UI Toolkit、性能分析、ProBuilder、程序化纹理生成资产生成/导入已有资源管理与 VFX/着色器/脚本工具但外部生成服务不在产品表面内新增asset_gen分组Tripo/Meshy 模型生成、fal.ai/OpenRouter 图像生成、Sketchfab 导入、本地 FBX/OBJ/glTF 交接如 BlenderAPI 查询与文档依赖外部文档或本地项目检查新增unity_docs与unity_reflect并生成工具/资源参考文档安全模型已有核心工具执行、自定义工具、异步测试轮询、实例路由新增分组门控的高权限工具、Unity 内安全的 Provider 密钥存储、项目作用域导入加固、归档/路径校验以及围绕传输、工具注册表、Provider 适配器与 Unity 兼容性的更多测试覆盖编辑器 UI 与文档窗口聚焦连接/客户端配置文档随功能累积新增工具/资源可见性流程、Asset Gen 设置、glTFast 依赖指引、README/文档导航刷新、图标/社交素材统一 MCP for Unity 产品命名自v9.0.0起新增的 MCP 工具入口共 17 个execute_code、generate_image、generate_model、import_model、import_model_file、manage_animation、manage_build、manage_camera、manage_graphics、manage_packages、manage_physics、manage_probuilder、manage_profiler、manage_texture、manage_tools、manage_ui、unity_docs、unity_reflect。二、工具分组机制core 默认启用其余分组 opt-inv10 引入了装饰器级的分组元数据。在 C# 侧每个工具类通过[McpForUnityTool]特性声明其分组核心实现在 McpForUnityToolAttribute.csGroup属性默认值为core即 core 工具默认可见非 core 分组vfx、animation、ui、scripting_ext、testing、menu以及 v10 新增的asset_gen等默认隐藏可通过manage_tools元工具按会话激活RequiresPolling、PollAction、MaxPollSeconds用于声明长耗时工具使服务端按指定 action 轮询直至完成。Python 侧的分组注册与可见性逻辑位于 tool_groups.py 与 tool_registry.py。因此 v10 的 10 个工具组为core、animation、asset_gen、docs、probuilder、profiling、scripting_ext、testing、ui、vfx。注意非 core 分组始终默认关闭这一规则在 v10 中没有变化这是本版本明确的「不做什么」清单之一。三、AI 资产生成asset_gen 工具组详解asset_gen是 v10 的招牌功能与其他非 core 工具组一样默认关闭需通过manage_tools显式启用。3.1 四个核心工具工具用途generate_model通过 Tripo、Meshy 等提供商根据文本或图像提示生成 3D 模型generate_image通过 fal.ai、OpenRouter 等提供商生成 2D 图像import_model搜索并导入可下载的 Sketchfab 模型import_model_file导入磁盘上已有的本地模型文件如 Blender 导出的 FBX/OBJ/glTF在仓库源码中这四个工具的 C# 实现分别位于 GenerateModel.cs、GenerateImage.cs、ImportModel.cs 与 ImportModelFile.cs均标注[McpForUnityTool(..., AutoRegister false, Group asset_gen)]。对应地Python 服务端工具实现位于 Server/src/services/tools/CLI 命令入口为 asset_gen.py。3.2 异步任务模型job_id status 轮询生成与导入任务都是异步的。请求返回一个job_id客户端以actionstatus配合该job_id轮询直到任务完成或失败。从源码看generate_model与generate_image支持generate、status、cancel、list_providers四种 actionimport_model支持search、preview、import、status、cancel、list_providers其中搜索/预览是只读调用直接以异步方式等待UnityWebRequest完成避免在编辑器主线程阻塞同步.GetResult()会导致死锁见 ImportModel.cs 中注释生成与导入通过AssetGenJobManager启动后台任务任务状态pending→ 进行中 →done/failed/canceled与进度百分比通过status返回。3.3 使用示例生成/导入操作通过 MCP 工具或asset-genCLI 触发而非 Unity GUI。长任务返回job_id后用actionstatus轮询generate_model actiongenerate providertripo modetext prompta low-poly oak tree formatfbx generate_model actiongenerate providermeshy modeimage image_pathAssets/refs/chair.png generate_image actiongenerate providerfal modetext prompta pixel-art coin import_model actionsearch querywooden chair import_model actionimport uiduid from searchgenerate_model的常见参数对照 GenerateModel.cs 实现actiongenerate/status/cancel/list_providers必填provider默认tripo可选meshymode默认text文本生 3Dimage为图生 3Dprompttext 模式必填image_path/image_urlimage 模式的输入注意 Tripo 只接受image_url见下文format默认glb可选fbx等targetSize默认 1f 的目标尺寸texture默认 true 是否生成纹理tier、model、name、outputFolder模型档位/模型选择、产物命名与输出目录。generate_image的常见参数对照 GenerateImage.csprovider默认fal可选openroutermode默认textimage为图生图transparent默认 false见下方注意事项、asSprite默认 true导入为 Sprite、width/height转发给 fal、name、outputFolder。import_model_file支持的扩展名见 ImportModelFile.cs 中SupportedExt.fbx、.obj、.glb、.gltf、.zipsource_path必填既可以是项目内Assets/相对路径也可以是磁盘绝对路径文件会被复制到项目Assets/下默认AssetGenPrefs.OutputRoot/Imported并走统一的ModelImportPipelineglTFast/FBX/OBJ/zip 处理、尺度归一化、材质设置场景内的摆放则由调用方自行完成。3.4 Provider 清单与注意事项3D 生成Tripo默认与 Meshy3D 导入Sketchfab2D 图像生成fal.ai默认与 OpenRouter。使用注意事项原文档明确列出image_url指向托管hosted图片image_path指向本地文件通常位于Assets/下Meshy 图生 3D 与 fal/OpenRouter 图生图支持本地image_path输入图片以内联 base64 data URI 发送Tripo 图生 3D 当前需要托管的image_url代码中对此有专门校验Tripo 拒绝本地image_path提示改用 Meshy见 GenerateModel.cstransparent仅设置 Unity 纹理导入标记fal/FLUX 并不提供透明背景生成能力width/height会转发给 falOpenRouter 的 chat API 不支持尺寸控制。四、Provider 密钥放在 Unity 的安全存储里资产生成服务全部采用「自带密钥」bring-your-own-key模式。密钥在 Unity 编辑器的 Asset Gen 标签页中录入并存储于操作系统安全存储macOSKeychainWindowsCredential ManagerLinuxlibsecret / Secret Service 兼容工具仓库中的实现位于 SecureKeyStore 目录包括统一的 SecureKeyStore.cs、平台实现 MacKeychainKeyStore.cs、WindowsCredentialKeyStore.cs、LinuxSecretToolKeyStore.cs以及 EncryptedFileKeyStore.cs加密文件兜底与 SecretRedactor.cs错误信息脱敏。安全边界原文档明确承诺密钥不会写入项目资源project assets、EditorPrefs、生成的文档或 MCP 工具参数MCP 客户端可以请求生成任务但不会收到 Provider 凭据——密钥在 C# 侧从安全存储读取后直接注入请求见 GenerateModel.cs 中SecureKeyStore.Current.Has(provider)校验与 ImportModel.cs 中「provider key ... never transits the bridge」的注释任何工具抛出的异常消息都会经过SecretRedactor.Scrub脱敏后再返回给客户端避免密钥随错误信息泄露。五、本地图片输入与 Blender 交接5.1 托管图与本地图的区分v10 明确区分两类图片输入image_url外部托管图片与image_path本地项目图片通常在Assets/下。Meshy 图生 3D、fal/OpenRouter 图生图可以把本地图片以内联 base64 data URI 发送Tripo 图生 3D 在接入上传流程前仍要求托管image_url。本地图片解析实现位于 LocalImage.cs。5.2 Blender 交接工作流import_model_file在 DCC数字内容创作生成与 Unity 导入之间建立了清晰的边界建模工具创建或导出资源MCP for Unity 通过import_model_file导入该文件Unity Agent 使用既有的场景、材质、预制体、构建工具把资源装配进项目。当 BlenderMCP 已连接时建模工作流可以把当前 Blender 模型导出再通过import_model_file默认 FBX导入。BlenderMCP 负责建模/生成MCP for Unity 负责导入与场景摆放。Asset Gen 标签页会显示尽力而为的「Blender app detected」状态但 BlenderMCP 本身配置在 AI 客户端侧Unity 无法探测到它。需要强调的是这是交接handoff不是 MCP for Unity 直接控制 Blender。六、安全模型opt-in 分组、项目作用域导入与零隐藏支出6.1 Opt-in 工具组asset_gen不属于默认 core 工具集必须通过manage_tools显式启用manage_tools actionactivate groupasset_gen6.2 项目作用域的导入加固生成与导入的资源会解析到 Unity 项目的Assets/目录下路径穿越traversal与不安全路径会被拒绝。以 Sketchfab 等市场导入的 zip 归档为例解压由 SafeZipExtractor.cs 完成其防护机制包括前置拒绝包含..或根路径的条目并校验每个条目的解析目标必须落在目标目录内防 Zip-Slip当传入扩展名白名单时白名单之外的条目直接跳过不写入——调用方解压不可信归档时必须传白名单确保.cs/.dll/.asmdef等可执行内容永远不会落到Assets/下被编辑器编译加载输出目录参数必须解析到项目Assets/文件夹内见 ImportModelFile.cs 与 ImportModel.cs 中output_folder must resolve under the projects Assets folder.的校验。6.3 无隐藏支出生成调用使用用户自己的 API 密钥调用第三方 ProviderMCP for Unity 不捆绑 Provider 额度creditsProvider 的定价、速率限制与内容政策由 Provider 自身控制只在确实要调用生成/导入服务时才启用该工具组。七、文档与品牌刷新、兼容性承诺v10 同时更新了项目门面README 精简为更清晰的入口文档站围绕 Getting Started、Guides、Reference、Architecture、Contributing、Migrations、Releases 重组本仓库内对应 website/docs/ 目录其中 工具参考 页面从工具注册表生成并细分出 asset_gen、animation 等分组页分发与分析文档明确说明「测量什么、不测量什么」品牌在用户可见 UI 与文档中统一使用MCP for Unity。兼容性承诺在 v10 延续不变Unity2021.3 LTS仍为包体最低版本Unity 6.x 仍在支持矩阵中已知的 Unity API 差异通过 Runtime/Helpers/ 下的兼容辅助层路由包括UnityCompatShims、UnityPhysicsCompat、UnityFindObjectsCompat等贡献者修改 shim 或版本门控 API 时需对已安装的 Unity Hub 编辑器运行 tools/check-unity-versions.sh。八、从 v9 升级到 v10将 Unity 包更新到 v10使用main分支获取最新稳定版需要精确到本版本时固定v10.0.0beta仅供 v10 之后的预览构建使用。若包提示重新配置 MCP 客户端请重新配置。仅在需要时安装可选依赖GLB 导入依赖 glTFastFBX 导入不需要该包。调用资产生成工具前先用manage_tools显式启用asset_gen分组。在 Unity 中添加 Provider 密钥不要写在 MCP 客户端配置文件中。提交前人工检查生成/导入的资源。九、v10 明确不包含的内容不提供托管的 MCP for Unity 资产生成额度不保证每个 Provider 支持每种输入模式不从 Unity 自动配置 BlenderMCP不承诺 Provider 生成的资源未经美术审核即可直接用于生产非 core 工具组默认关闭的规则没有改变。十、常见问题排查asset_gen工具不出现asset_gen分组默认关闭先用manage_tools启用manage_tools actionactivate groupasset_gen若仍未出现请在客户端刷新/重连 MCP 服务器——部分客户端会缓存工具列表直到服务器重启或刷新。Provider 密钥缺失生成服务均为自带密钥。请在 Unity 的Asset Gen标签页添加密钥不要把 Provider 密钥放进 MCP 客户端配置文件、提示词、项目资源或生成的文档中。GLB 导入失败或几何体/材质缺失GLB/glTF 导入依赖glTFast。请在 Dependencies 标签页或 Package Manager 中安装后再导入 GLB 资源FBX 导入不需要 glTFast。Tripo 图生 3D 拒绝image_pathTripo 图生 3D 目前需要托管image_url。本地image_path输入由 Meshy 图生 3D 与 fal/OpenRouter 图生图支持图片以内联 base64 data URI 发送。生成或导入的文件比预期大Provider 输出可能包含大型二进制资源。提交前请检查生成的文件尽量把生成产物放在Assets/Generated/下避免提交项目不需要的实验性 Provider 输出。归档导入被拒绝归档解压是刻意受限的。Provider 归档若包含不支持的扩展名、路径穿越、脚本或白名单之外的文件可能被拒绝。请改用受支持的格式重新导入模型或先检查归档内容再带入 Unity 项目。延伸阅读v10 发布说明原文工具分组指南asset_gen 工具参考v10 迁移指南Unity 兼容性架构文档SecureKeyStore 实现SafeZipExtractor 安全解压实现【免费下载链接】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），仅供参考