dcc-mcp-maya

中文

English

中文

English

Appearance

安装指南 ​

系统要求 ​

  • Maya：2020+（模块包覆盖 Maya 2022 至 2026）
  • Python：3.7 – 3.12（Maya 内嵌）
  • dcc-mcp-core：dcc-mcp-core>=0.20.0,<0.21.0（作为依赖自动安装）
  • dcc-mcp-server：≥ 0.18.21（默认 sidecar gateway 运行时，作为依赖自动安装）

方式一 — pip 安装到 mayapy ​

最简单的方式，使用 Maya 自身的 Python 解释器：

bash
# 通用
mayapy -m pip install dcc-mcp-maya

# Windows — Maya 2024
"C:\Program Files\Autodesk\Maya2024\bin\mayapy.exe" -m pip install dcc-mcp-maya

# macOS — Maya 2024
/Applications/Autodesk/maya2024/Maya.app/Contents/bin/mayapy -m pip install dcc-mcp-maya

验证安装：

bash
mayapy -c "import dcc_mcp_maya; print(dcc_mcp_maya.__version__)"

方式二 — Maya 插件 ​

这是推荐的 Maya GUI 启动方式。将插件文件复制到 MAYA_PLUG_IN_PATH 中的某个目录，然后通过插件管理器加载。

  1. 将 maya/plugin/dcc_mcp_maya_plugin.py 复制到 Maya 插件目录，例如：

    • Windows：%USERPROFILE%\Documents\maya\2024\plug-ins\
    • macOS：~/Library/Preferences/Autodesk/maya/2024/plug-ins/

  2. 打开 窗口 → 设置/首选项 → 插件管理器

  3. 找到 dcc_mcp_maya，勾选 已加载（可选：勾选自动加载）

插件加载后会自动启动服务器。默认情况下实例端口由操作系统分配，并接入 9765 端口上的网关。

默认 sidecar 模式下，本机 MCP 客户端使用 http://127.0.0.1:9765/mcp。默认关闭局域网入口。如需开启，可在加载插件前将 DCC_MCP_GATEWAY_REMOTE_PORT 设为正端口号（例如 59765）；如需改绑定地址或端口，设置 DCC_MCP_GATEWAY_REMOTE_HOST / DCC_MCP_GATEWAY_REMOTE_PORT。

插件初始化期间，dcc-mcp-maya 还会关闭 Maya 旧式 MEL commandPort（127.0.0.1:50007）。MCP 服务器不会使用该端口，关闭它可以避免误发的 HTTP 探测触发 Maya 安全警告弹窗。如果工作室仍依赖旧式 commandPort，可在加载插件前设置 DCC_MCP_MAYA_CLOSE_DEFAULT_COMMANDPORT=0 选择保留。

插件默认会在 Maya 旁边启动 Rust sidecar，同时保留进程内 MCP server 作为 host bridge。如需回到旧的进程内 gateway 路径，请在加载插件前设置 DCC_MCP_MAYA_SIDECAR=0。Sidecar 模式使用 Maya 内部 Qt event-loop dispatcher，不需要打开旧式 commandPort。

MCP 宿主配置：

json
{
  "mcpServers": {
    "maya": {
      "url": "http://127.0.0.1:9765/mcp"
    }
  }
}

非交互 GUI bootstrap 诊断 ​

无人值守启动 Maya 2025 GUI 时，请使用 adapter 提供的固定 launcher，不要拼接 MEL、Python 或 -script payload。使用已安装 dcc-mcp-maya 的同一个 mayapy 执行：

bash
# Windows
"C:\Program Files\Autodesk\Maya2025\bin\mayapy.exe" -m dcc_mcp_maya.gui_bootstrap launch --maya-executable "C:\Program Files\Autodesk\Maya2025\bin\maya.exe" --timeout 120

# macOS
/Applications/Autodesk/maya2025/Maya.app/Contents/bin/mayapy -m dcc_mcp_maya.gui_bootstrap launch --maya-executable /Applications/Autodesk/maya2025/Maya.app/Contents/MacOS/Maya --timeout 120

# Linux
/usr/autodesk/maya2025/bin/mayapy -m dcc_mcp_maya.gui_bootstrap launch --maya-executable /usr/autodesk/maya2025/bin/maya --timeout 120

示例使用 Maya 2025；对于其他受支持的 Maya 版本，只需替换带版本号的可执行文件 路径。命令和诊断契约本身不依赖具体版本。

该命令只启动一次 Maya，并保持 GUI 运行，同时输出一条 JSON 诊断。退出码 0 表示已找到与本次 Maya PID 匹配的 registry 记录；10 表示 bounded probe 已定位启动阶段；40 表示启动参数或可执行文件无效。四个有限失败原因是 plugin_not_invoked、plugin_load_failed、sidecar_failed 和 registry_registration_failed；next_action 提供机器可读的恢复动作。

返回的 bootstrap_log 是 JSONL 路径。按序阶段包括插件调用/解析/加载、 adapter import、registry registration、sidecar spawn 和完成；只有这些阶段与 目标 PID 的 registry 记录都满足后才报告 ready。如需在不启动第二个 Maya 的 情况下重新检查同一次启动，请使用：

bash
mayapy -m dcc_mcp_maya.gui_bootstrap probe --maya-pid <PID> --log-path <BOOTSTRAP_LOG> --timeout 30

仅当 Maya 使用相同的 DCC_MCP_REGISTRY_DIR base 时才传 --registry-dir。该路径不会修改插件管理器中的已加载或自动加载状态， 也不会执行调用方提供的 MEL/Python，更不会回退到 UI 自动化。真实 GUI 证明 仍需要可用的 Maya 安装与许可证。

方式三 — mayapy bootstrap ​

对于 headless E2E 或服务化运行，可以用自带的 bootstrap 启动 Maya：

bash
mayapy maya_bootstrap.py

该 bootstrap 在 batch 模式下创建 Maya host dispatcher，通过 core host bridge 对外暴露 /mcp 和 per-DCC REST skill API /v1/*。

Maya 许可证是 CI 中的前置条件。将此命令放到自托管 runner 或有 Maya 许可证的环境中执行。

更多 MCP host 配置、自定义 bootstrap 代码和 standalone-safe custom skill 示例见 Standalone mayapy 服务。

方式四 — userSetup.py（自动启动） ​

如需每次 Maya 启动时自动开启 MCP，推荐复制或 source 仓库自带的 maya/userSetup.py。它会设置安全的插件默认值、查找 module 安装，并等 Maya 空闲后再加载插件。

最小自定义 userSetup.py：

python
# userSetup.py
import maya.cmds as cmds

def _load_dcc_mcp_maya():
    if not cmds.pluginInfo("dcc_mcp_maya_plugin", query=True, loaded=True):
        cmds.loadPlugin("dcc_mcp_maya_plugin", quiet=True)

cmds.evalDeferred(_load_dcc_mcp_maya, lowestPriority=True)

文件位置：

  • Windows：%USERPROFILE%\Documents\maya\scripts\userSetup.py
  • macOS：~/Library/Preferences/Autodesk/maya/scripts/userSetup.py

避免在 Maya GUI 启动代码里直接调用普通的 dcc_mcp_maya.start_server()。GUI 会话需要 Maya UI dispatcher 才能执行 affinity: main 工具；插件会自动安装它。

自动加载排查 ​

如果插件没有加载，先查这两个信号，再动手猜：

  • Script Editor / 状态栏告警 —— 自动加载失败现在会通过 cmds.warning 上报，即使从未打开过 Script Editor 也能在 Maya 里看到。
  • 日志文件 —— <DCC_MCP_MAYA_BOOTSTRAP_ERROR_DIR>（默认 ~/.dcc-mcp/receipts/bootstrap-errors/）下，每次失败尝试写一行 JSON 到 userSetup-<YYYYMMDD>.jsonl，同目录还有 core 写的 dcc-mcp-maya.<pid>.host-errors.log。

DCC_MCP_LOG_DIR 是另一个通道：放的是插件的 Python 致命信号堆栈 （maya-faulthandler-<pid>.log），不是自动加载失败记录。

最常见的原因是调度 API 用错了：

python
# 错误 —— lowestPriority 会被当作参数传给回调函数（TypeError，被 Maya
# 的 deferred 调度器静默吞掉）：没有插件、没有服务、没有报错。
maya.utils.executeDeferred(_load_dcc_mcp_maya, lowestPriority=True)

# 正确 —— lowestPriority 是 evalDeferred 命令的调度标志。
cmds.evalDeferred(_load_dcc_mcp_maya, lowestPriority=True)

方式五 — 调试用 direct start_server ​

直连 server 模式适合本地调试和 mayapy 脚本。在 Maya GUI 中请显式传入 dispatcher：

python
from dcc_mcp_maya.dispatcher import MayaUiDispatcher, MayaUiPump
import dcc_mcp_maya

dispatcher = MayaUiDispatcher()
MayaUiPump(dispatcher).install()
handle = dcc_mcp_maya.start_server(host_dispatcher=dispatcher)
print(handle.mcp_url())  # 实际由操作系统分配的直连 URL

使用直连模式时，MCP 宿主填写 handle.mcp_url() 返回的 URL。插件模式请使用 稳定的 gateway URL：http://127.0.0.1:9765/mcp；dcc-mcp-cli list 会列出每个已注册实例及其实际绑定 URL。

多 Maya 版本 ​

每个 Maya 版本有独立的 Python 解释器，需分别安装：

bash
# Maya 2022（Python 3.7）
"C:\Program Files\Autodesk\Maya2022\bin\mayapy.exe" -m pip install dcc-mcp-maya

# Maya 2024
"C:\Program Files\Autodesk\Maya2024\bin\mayapy.exe" -m pip install dcc-mcp-maya

# Maya 2025
"C:\Program Files\Autodesk\Maya2025\bin\mayapy.exe" -m pip install dcc-mcp-maya

同时运行多个 Maya 实例时，插件 gateway 模式更简单：所有实例都会注册到 http://127.0.0.1:9765/mcp 后面。

直连 server 也会各自绑定操作系统分配的端口，不再需要手工维护端口范围或先探测 再绑定：

python
# 在每个 Maya 进程内分别执行。
handle = dcc_mcp_maya.start_server()
print(handle.mcp_url())

正常的多进程场景应让所有进程注册到 gateway，并通过发现元数据选择目标实例， 不要把这些临时直连 URL 固化进客户端配置。

升级 ​

bash
mayapy -m pip install --upgrade dcc-mcp-maya

卸载 ​

bash
mayapy -m pip uninstall dcc-mcp-maya

基于 MIT 许可证发布

Copyright © 2024-present Long Hao