AI导哈

Unity3D自动化服务器

一个全面的Unity3D自动化工具，支持VRM头像管道、VRChat集成和多平台社交VR开发。

  • by sandraschi
  • Python
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 sandraschi/unity3d-mcp

使用说明

Unity3D MCP服务器

📖 安装指南 --快速启动、手动设置和故障排除

符合FastMCP 3.2.0+标准 -通过VRM头像管道和VRChat集成实现全面的Unity 3D自动化。

工具表面（已验证 src/unity3d_mcp/server.py, 2026-07-18)

此表是此服务器工具的唯一真实来源。 任何 您在此处下方的README中看到的其他工具名称，或 推断出 src/unity3d_mcp/app.py （未使用的死代码--未由导入 __main__.py 或引用于 pyproject.toml真正的切入点是 server.py)，都是陈腐的。请参阅本页底部的客房服务说明 部分。

15个合成工具 （一个工具， operation 论证选择行为-- 这是此服务器使用的真实、当前的工具数量减少模式）：

工具 操作
unity_core launch_editor, create_project, execute_method, check_univrm, install_univrm, create_project_with_univrm
unity_scene create_light
unity_avatar import_vrm, setup_animator
unity_asset optimize_textures
unity_build build_project
vrchat check_auth, authenticate, check_sdk, validate_avatar, setup_descriptor, upload_avatar — 仅限头像，无全球上传/发布
worldlabs assemble_review, import_marble, check_gaussian, install_gaussian, optimize_for_vrchat
multiplatform list_platforms, check_sdk, check_cck, setup_cvr_avatar, validate_cvr, prepare_resonite, check_resonite_compat, check_cluster_kit, prepare_cluster, audit_all （ChilloutVR/Resonite/Cluster——不是VRChat，这是 vrchat 工具）
unity_bridge status, execution_mode, ping, get_hierarchy, create_object, delete_object, transform_object, capture_game_view — 实时编辑，仅限动手
unity_render bridge_status, get_scene_summary, capture_multi_angle --代理愿景
unity_api get_scene_objects, modify_object, create_prefab, run_simulation, execute_method, batch_operations, move_along_path, create_path_visualization, follow_path_2d, follow_path_3d, stop_path_movement — 所有真实的，依赖于桥梁 （需要实时Unity编辑器会话 MCPBridge.cs 跑步；返回一个诚实的“桥未连接”错误，否则不是假成功）
unity_jobs submit (job_type：构建/批处理导入/模拟）， status, list, cancel --异步队列
unity_import import_blender, import_fleet_batch, list_formats --搅拌机/车队GLB/VRM/FBX/OBJ交接
unity_vision_refine capture, review_bundle, apply_bridge_commands
unity_validation list_limits, validate_scene, check_polycount, check_materials, validate_model, validate_avatar, unified_audit

2个独立工具 （双模/代理，直接注册，不通过 经理班）：

工具 目的
unity3d_disk_api [Hands-Off] UnityPy磁盘操作：inspect_file、list_textures、modify_yaml——无重叠，真正独立
unity3d_agentic_workflow SEP-1577采样——从高层次目标出发的自主多步编排

清理完毕2026-07-18 （之前在这里标记为已知重复， 现在实际上已删除——请参阅 TODO.md 完整记录）：

  • 9个平台辅助工具(list_vr_platforms, check_platform_sdk, check_cck_installed, setup_cvr_avatar, validate_for_chilloutvr, prepare_for_resonite, check_resonite_compatibility, check_cluster_kit, prepare_for_cluster)都走了。使用 multiplatform(operation=...).
  • 11公寓 api_* 工具(api_execute_method, api_get_scene_objects, 等等）及其支持 _api_* 服务器类上的存根方法包括 跑了。使用 unity_api(operation=...) --真正的实施，哪 实际上为 get_scene_objects/modify_object 通过直播 bridge（扁平版本无条件返回“未实现”， 即使是那些）。
  • unity3d_bridge_status 和 unity3d_editor_api 消失了，折叠成 unity_bridge一次手术 unity3d_editor_api 有这个 unity_bridge 没有 capture_game_view --现在是a unity_bridge 操作也是。使用 unity_bridge(operation="status") 和 unity_bridge(operation=...) 相反。

仍然真实，尚未注册 （不是这张通行证的一部分——更大的， 单独任务（如果完成）：电机控制(api_add_motor 等等），通用 资产出口/进口(export_fbx, import_asset_package, batch_import), 以及专用的VRM Unity装配工具(import_vrm_to_unity, setup_unity_avatar_rigging等等） 未作为MCP工具公开 全部 --底层管理器类存在(motor_manager.py, import_export_manager.py, vrm_avatar_manager.py)但里面什么都没有 server.py 注册它们。 app.py （及其 .bak 双胞胎）是死代码 包含其中一些的第二个从未有线实现——不要 相信它是可调用信息的真实来源。

复制 src/unity3d_mcp/resources/MCPBridge.cs 到你的项目 Assets/Editor/ 文件夹。

网络应用程序 智能体工具 页面： /agent-tools （镜像混合器mcp Agent Lab UI）。

双模式（实时GUI与无头）

模式 何时 您看到
手在 Unity编辑器+ MCPBridge.cs （：10835） 场景编辑、游戏模式模拟、在编辑器中实时捕捉
放手的 无桥接/仅磁盘 UnityPy编辑、导入、， 创造就业机会 (-batchmode，无GUI）

unity_bridge(operation='execution_mode') 报告当前模式。看 docs/DUAL_MODE.md.

可观察性（v1.5）

  • 普罗米修斯： http://127.0.0.1:9092/metrics 和 /api/v1/metrics 日期：10831
  • JSON日志： UNITY3D_MCP_LOG_FORMAT=json
  • Docker： docker compose --profile monitoring up -d — docs/MONITORING.md, docs/DOCKER.md

车队管道（搅拌机→ 团结）

.\scripts\run-fleet-pipeline.ps1 -ProjectPath "D:\Unity\MyProject" -ModelPath "D:\exports\avatar.glb" -SkipBuild

看 docs/FLEET_PIPELINE.md.

blender-mcp export GLB/VRM → unity_import import_blender → unity_vision_refine review_bundle → VRChat/build
worldlabs Marble → worldlabs assemble_review → agent fixes → unity_jobs build

一次性自动化： docs/FLEET_PIPELINE.md — scripts/run-fleet-pipeline.ps1

git clone https://github.com/sandraschi/unity3d-mcp
cd unity3d-mcp
just

这将打开一个交互式仪表板，显示所有可用命令。跑 just bootstrap 要安装依赖项，请执行以下操作 just serve 或 just dev 开始。

手动设置

如果你没有 just 安装：

特性

核心Unity自动化

  • Unity编辑器管理：启动、控制和自动化Unity编辑器
  • 项目运营：创建、配置和管理Unity项目
  • 场景管理：创建和操纵Unity场景
  • 构建管道：针对多个平台的自动化构建

Avatar和VRM管道

  • VRM导入：为Unity导入和配置VRM化身
  • 头像优化：优化化身以实现VRChat兼容性
  • 动画系统：设置动画师控制器和动画片段
  • 性能分析：分析和优化化身性能

资产管理

  • 包导入：导入Unity资产包
  • 纹理优化：特定于平台的纹理优化
  • 物料管理：为VRChat创建和转换材料
  • 资产组织：自动化资产组织和版本控制

VRChat集成

  • SDK自动化：自动化VRChat SDK操作
  • 头像上传：将头像上传到VRChat平台
  • OSC通信：实时OSC参数控制
  • 性能验证：VRChat特定性能验证
  • 认证：VRChat API验证，支持2FA/TOTP

多平台社交VR

平台 引擎 头像格式 SDK 状态
VRChat Unity VRC预制件 VRChat SDK 完全支持
ChilloutVR Unity CVR预制件 CCK 支持
共振体 FrooxEngine VRM/GLB直接 无需 支持
簇 Unity VRM 创建者工具包 支持
  • ChilloutVR：CCK检测、CVRAvatar设置、验证
  • 共振体：直接导入VRM/GLB（无需Unity！）
  • 簇：支持VRM的日本社交VR

高级Unity编辑器API操作

被覆盖 unity_api 组合工具（见上面的工具表）。 每个操作都是真实的，并且依赖于网桥：它调用 MCPBridge.cs 编辑器桥（HTTP， localhost:10835)并要求Unity对 该脚本已安装并正在运行。两个已知的、有真实记录的 当前桥梁实施的局限性：

  • execute_method 仅支持公共、静态、， 无参数的 统一 方法（与Unity自己的约束相同 -executeMethod CLI标志有）。 经过 parameters 被接受，但明确报告为 忽略，而不是默默放弃或强制输入。
  • 路径移动(move_along_path, follow_path_2d, follow_path_3d) 近似全部 path_type 曲线变体(bezier, spline, catmull_rom)作为直线多段线性插值——实 未实现曲线数学。

这仅通过手动C#代码审查进行了验证（否 dotnet/mono/csc 编译器在内置的环境中可用），因此请处理它 在你对Unity编辑器进行烟雾测试之前，它是未经验证的 你自己。

目前根本没有作为MCP工具公开 （实际代码存在于 motor_manager.py, import_export_manager.py，以及 vrm_avatar_manager.py，但里面什么都没有 server.py 注册它）： 电机控制（在物体上连接/启动/停止/配置电机），通用 资产出口/进口(.unitypackage，独立FBX/预制件导出， 纹理特定导入）和专用VRM Unity装配工具分开 来自 unity_avatars import_vrm/setup_animator.如果你需要任何 这些，他们需要一个合成词包装，并在 server.py 首先，这是真实的、有范围的未来工作，而不是文档 修复。已追踪 TODO.md.

代理采样（SEP-1577）

FastMCP 3.2.0+介绍 代理采样，允许服务器借用客户端的LLM来自主编排复杂的工作流。

  • unity3d_agentic_workflow：执行基于任务的目标（例如，“设置一个新的VRChat项目并导入我的头像”）。

情境发现（技能和提示）

该服务器通过SOTA技能系统提供专家指令和预定义的工作流程。

技能

可通过 resource://unity3d/skills/:

  • unity-editor-automation：编辑控制专家指南。
  • vrc-avatar-pipeline：VRM到VRChat优化指南。

提示

已注册的SOTA提示：

  • unity_setup_workflow：项目初始化指南。
  • vrc_avatar_workflow：VRM优化生命周期说明。

双模式操作

此服务器独特地支持两种不同的操作模式，以在开发和CI/CD环境中实现最大的灵活性。

1.参与（活动会话）

实时控制正在运行的Unity编辑器。需要 MCPBridge.cs 插件。

  • 工具: unity_bridge （操作：状态、执行模式、ping、获取层次结构、创建对象、删除对象、转换对象、捕获名称视图）
  • 用例：场景布局、实时调试、照明设置和实时层次操纵。
  • 港口：10835（HTTP）
  • 指南：[实时编辑器自动化](file:///D:/Dev/repos/unity3d-mcp/docs/GUIDE_EDITOR_AUTO.md）

2.放手（磁盘操作）

直接操作磁盘上的Unity资产。由...驱动 UnityPy 的.

  • 工具: unity3d_disk_api
  • 用例：CI/CD管道、批处理资产审计、纹理提取和快速预制修复，无需启动Unity。
  • 支持：序列化文件（.unity、.profab、.reset）+unity YAML源文件。
  • 指南：[直接磁盘操作](file:///D:/Dev/repos/unity3d-mcp/docs/ARCHITECTR_DUAL_MODE.md#模式-手持-离盘操作）

技术文档

全面的技术套件可在 [文档门户](file:///D:/Dev/repos/unity3d-mcp/docs/README.md）.

核心概念

  • [建筑深度学习](file:///D:/Dev/repos/unity3d-mcp/docs/ARCHITECTURE_DUAL_MODE.md）：动手与不动手分析。
  • [完整的API参考资料](file:///D:/Dev/repos/unity3d-mcp/docs/API_REFERENCE.md）：所有50+工具的详细信息。

专用管道

  • [VRM到VRChat指南](file:///D:/Dev/repos/unity3d-mcp/docs/GUIDE_VRCHAT_PIPELINE.md）：高保真化身优化。
  • [场景自动化指南](file:///D:/Dev/repos/unity3d-mcp/docs/GUIDE_EDITOR_AUTO.md）：实时编辑器控件。

技术标准

  • FastMCP 3.2.0+：采用ASGI/Uvicorn和SEP-1577采样的最新MCP协议实施。
  • 代理工作流：使用双模智能的集成自主编排。
  • 模块化技能：桥安装和磁盘操作的专家说明。
  • 结构化日志记录：JSON格式的日志通过 structlog.
  • 安全：已应用CVE-2025-62801和CVE-2025-62800修复程序。

世界实验室集成

  • 大理石进口：从World Labs Marble导入人工智能生成的3D世界
  • 凿子支架：适用于Chisel编辑环境
  • 高斯溅射：安装渲染器 .ply/.splat 文件
  • VRChat优化：VRChat世界上传建议
  • 格式支持：OBJ、FBX、GLB、GLTF网格+高斯散斑

UniVRM管理

  • 包装检测：检查是否安装了UniVRM
  • 自动安装：通过包管理器安装UniVRM 0.x或1.0
  • 项目模板：使用预先配置的UniVRM创建项目

高级功能

  • 双接口：stdio和HTTP（ASGI/Uvicorn）接口。
  • FastMCP 3.2.0：具有采样支持的现代MCP服务器架构。
  • 综合录井：具有性能指标的结构化日志记录。
  • 平台管理：多平台构建和优化。
  • 路径解析：智能Unity安装检测。

安装

先决条件

  • 紫外线 已安装（推荐）
  • Python 3.12+

快速开始

立即通过运行 uvx:

uvx unity3d-mcp

Claude桌面集成

添加到您的 claude_desktop_config.json:

"mcpServers": {
  "unity3d-mcp": {
    "command": "uv",
    "args": ["--directory", "D:/Dev/repos/unity3d-mcp", "run", "unity3d-mcp"]
  }
}

来自PyPI（推荐）

pip install unity3d-mcp

包装与配送

该存储库符合SOTA 2026标准，并使用经过官方验证的 @anthropic-ai/mcpb 分发工作流程。

包扩展

生成一个 .mcpb 包含完整源代码和自动构建排除的发行包：

# SOTA 2026 standard pack command
mcpb pack . dist/unity3d-mcp.mcpb

来自GitHub发布

# Direct wheel download
pip install https://github.com/sandraschi/unity3d-mcp/releases/download/v1.2.0/unity3d_mcp-1.2.0-py3-none-any.whl

# Or from git
pip install git+https://github.com/sandraschi/unity3d-mcp.git

配置

创建配置文件或使用环境变量：

{
  "unity_editor_path": "C:/Program Files/Unity/Hub/Editor/2022.3.0f1/Editor/Unity.exe",
  "project_path": "D:/Unity Projects",
  "auto_detect_unity": true,
  "enable_http": true,
  "http_port": 8080,
  "log_level": "INFO"
}

用法

命令行

# Start in stdio mode
unity3d-mcp --mode stdio

# Start HTTP server
unity3d-mcp --mode http --port 8080

# Dual mode (stdio + HTTP)
unity3d-mcp --mode dual

MCP工具

看 工具表面 在本README的顶部附近，对完整的源代码工具进行了验证 具有真实操作名称的列表。（此README的早期版本有 第二，这里的工具列表不兼容，名称如下 launch_unity_editor, import_vrm_avatar, upload_vrchat_avatar --这些不是可调用的工具； 实际操作是 unity_core(operation="launch_editor"), unity_avatar(operation="import_vrm"), vrchat(operation="upload_avatar")等等。删除2026-07-18以停止 两份名单渐行渐远，从现在开始只有一个真相来源。）

建筑学

unity3d_mcp/
 core/           # Unity Editor automation, project management, UniVRM
 avatar/         # VRM avatar management
 assets/         # Asset import and optimization
 build/          # Build pipeline management
 vrchat/         # VRChat SDK integration + authentication
 worldlabs/      # World Labs Marble/Chisel integration
 utils/          # Shared utilities

测试

# Run all tests
.\scripts\run-tests.ps1

# Run with coverage
.\scripts\run-tests.ps1 -Coverage

# Run E2E tests (requires Unity)
.\scripts\run-tests.ps1 -E2E

# Run specific test pattern
.\scripts\run-tests.ps1 -Pattern "test_worldlabs"

需求

  • Python 3.8+
  • Unity编辑器（2019.4 LTS或更新版本）
  • VRChat SDK（用于VRChat功能）
  • Windows 10/11（主要支持）

演出

针对以下方面进行了优化：

  • VRChat头像要求
  • 移动VR平台
  • 多平台部署
  • 实时OSC通信

🛡️ 工业级质量堆栈

该项目坚持 索塔14.1 高保真代理编排的工业标准：

  • Python（核心）: 拉夫 用于裁剪和格式化。零容忍 print 核心处理程序中的语句(T201).
  • Web应用程序（用户界面）: 生物群系 用于亚毫秒级的起毛。严格 noConsoleLog 执行。
  • 协议合规：硬化 stdout/stderr 隔离，以确保防崩溃的JSON-RPC通信。
  • 自动化: Justfile 所有舰队行动的食谱(just lint, just fix, just dev).
  • 安全：通过以下方式进行自动化审计 bandit 和 safety.

许可证

MIT许可证-请参阅 许可证 了解详情。

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加测试
  5. 提交拉取请求

支持

Webapp仪表板

此MCP服务器包括用于监视和控制的高级SOTA web界面。

港口分配（标准化）

  • 前端: 10830 （Vite/React）
  • 后端（API）: 10831 （FastAPI/FastMCP）

要启动Web应用程序，请执行以下操作：

  1. 导航到 web_sota 目录。
  2. 跑 start.bat （Windows）或 ./start.ps1 （PowerShell）。
  3. 仪表板将在以下时间自动打开 http://localhost:10830.

相关 MCP