Maya 影视动画与建模 MCP 服务器 (Maya MCP Server)

Maya MCP Server 允许 AI 智能体通过模型上下文协议 (MCP)，使用日常自然语言直接与 Autodesk Maya 建立深度交互并进行全方位控制。这一集成使创作者能够通过提示词驱动 3D 辅助建模、场景程序化构建、材质赋予与动效资产编排。

该服务器是由资深开发者 Patrick Palmer 创建并开源的第三方独立工具，非 Autodesk 官方或 Griptape 官方维护项目。

第三方开源服务免责提示

该 MCP 服务器未获得 Griptape 或 Autodesk Maya 的官方商业背书。在将其接入工作流时请自行评估操作边界，并确保在执行前对重要工程做好物理备份。

前置运行环境 (Prerequisites)

在正式接入 Maya MCP 服务器前，请确保满足以下条件：

1. 已安装 Autodesk Maya 2023 或更新版本；
2. 宿主机安装了 Python 3.10 或更新版本；
3. 已克隆并搭建好 Maya MCP 服务端本地虚拟环境（详见下文安装向导）。

---

部署与配置向导 (Installation)

第一步：下载并搭建 Maya MCP 服务端环境

1. 打开操作系统终端，导航至存放代码仓库的物理路径（例如 Mac 上的 $HOME/Documents/GitHub 或 Windows 下的对应工程盘）：

   cd $HOME/Documents/GitHub
   

2. 克隆官方代码仓库并进入目录：

   git clone https://github.com/PatrickPalmer/MayaMCP.git
   cd MayaMCP
   

3. 创建专属的 Python 虚拟隔离环境：

   python -m venv .venv
   

4. 激活该虚拟环境：

   • Windows：.venv\Scripts\activate.bat
   • macOS / Linux：source .venv/bin/activate

5. 安装核心依赖包：

   pip install -r requirements.txt
   

---

第二步：启动 Maya 并激活命令端口 (Command Port)

Maya 内部原生提供了 Command Port 端口机制，用于接收外部 IPC 管道指令。MCP 服务正是通过该端口与 Maya 内部 Python 解释器通信。

1. 启动 Autodesk Maya 软件；

2. 打开 Maya 的 Script Editor (脚本编辑器)，并在 Python 标签页中执行以下代码：

   import maya.cmds as cmds
   
   
   def setup_maya_command_port(port=50007):
       """配置并开启 Maya 命令端口（带容错处理）"""
       try:
           # 首先尝试关闭该端口上可能残留的历史连接
           try:
               cmds.commandPort(name=f"localhost:{port}", close=True)
               print(f"Closed existing command port on localhost:{port}")
           except:
               pass
   
           # 正式启用命令端口
           cmds.commandPort(name=f"localhost:{port}")
           print(f"Command Port successfully enabled on localhost:{port}")
           return True
   
       except Exception as e:
           print(f"Error setting up command port: {e}")
           return False
   
   
   # 执行初始化设置
   if setup_maya_command_port(50007):
       print("Maya MCP server should now be able to connect!")
   else:
       print("Failed to setup command port. Check Maya's Preferences.")
   

每次启动 Maya 时均需激活端口

Command Port 默认不会在关闭 Maya 后持久化保持。这意味着每次全新打开 Maya 时，均需执行一次端口激活脚本。

工程简化推荐：配置自动启动

为了免除每次手动粘贴脚本的繁琐操作，可采用以下两种自动化方式之一：

方案 A：创建 Maya 工具架快捷按钮 (Shelf Button) 将上述 Python 脚本直接全选拖拽至 Maya 顶部的用户 Shelf 工具架中生成快捷图标，每次启动软件后轻点一下即可。

方案 B：通过 userSetup.py 实现开机自动静默执行 定位到 Maya 的用户脚本目录： - Windows：%USERPROFILE%\Documents\maya\2025\scripts\ - macOS：~/Library/Preferences/Autodesk/maya/2025/scripts/ - Linux：~/maya/2025/scripts/

在目录下的 userSetup.py（若不存在则新建）中写入自动执行代码，即可实现软件启动时全自动静默监听 50007 端口。

初次授权弹窗提示

当 MCP 服务初次尝试穿透端口连接 Maya 时，Maya 内部可能会弹出一个安全授权弹窗。请务必勾选并点击 "Allow All (全部允许)" 以保障后续持续指令畅通。

---

第三步：在 Griptape Nodes 中配置与注册

1. 打开 Griptape Nodes，依次点击 Settings → MCP Servers；
2. 点击 + New MCP Server；

3. 基础参数配置：

   • Server Name/ID：maya
   • Connection Type：Local Process (stdio)
   • Configuration JSON（根据你所处的操作系统选择对应语法）：

   Windows 平台示例：

   {
     "transport": "stdio",
     "command": "C:\\path\\to\\MayaMCP\\.venv\\Scripts\\python.exe",
     "args": [
       "C:\\path\\to\\MayaMCP\\src\\maya_mcp_server.py"
     ],
     "cwd": null,
     "encoding": "utf-8",
     "encoding_error_handler": "strict"
   }
   

   macOS / Linux 平台示例：

   {
     "transport": "stdio",
     "command": "/path/to/MayaMCP/.venv/bin/python",
     "args": [
       "/path/to/MayaMCP/src/maya_mcp_server.py"
     ],
     "cwd": null,
     "encoding": "utf-8",
     "encoding_error_handler": "strict"
   }
   

   ⚠️ 注意：请务必将路径替换为你本机真实的 MayaMCP 虚拟环境解释器及入口脚本绝对物理路径。

4. 点击 Create Server。

---

提供的可用工具集矩阵 (Available Tools)

基础场景与对象控制

• list_objects_by_type — 列出场景中的所有实体对象，支持针对摄像机、灯光、材质球或几何形态进行类型过滤；
• create_object — 创建标准基础 3D 图元（立方体、圆锥、球体、圆柱体、摄像机及灯光组件）；
• get_object_attributes — 提取 Maya 物体节点上的所有属性列表与当前取值；
• set_object_attribute — 精准修改某个对象属性的数值或布尔状态；
• scene_new / scene_open / scene_save — 控制场景的重置新建、打开载入与持久化磁盘保存；
• select_object / clear_selection_list — 控制视口选中状态与清空选区；
• viewport_focus — 将三维视图摄像机自动居中并框选聚焦于目标物体。

工业级高级建模与资产编排

• create_advanced_model — 基于复合参数算法程序化生成复杂 3D 资产（载具、植被树木、楼宇建筑、杯子、桌椅家具等）；
• mesh_operations — 执行网格拓扑编辑操作（挤出 Extrude、倒角 Bevel、细分 Subdivide、布尔运算 Boolean、合并 Combine、桥接 Bridge、切分 Split）；
• create_material — 实时创建并为表面赋予材质着色器（Lambert、Phong、木质纹理、大理石、金属铬、玻璃等）；
• create_curve — 生成 NURBS 曲线（线性、圆形、阿基米德螺旋线、螺旋弹簧线、星形、工业齿轮等）；
• curve_modeling — 基于曲线生成曲面几何体（放样 Loft、旋转成型 Revolve、沿路径扫掠 Sweep）；
• organize_objects — 空间结构编组、父子级链接对齐与矩阵阵列分布。

---

典型自然语言驱动提示词范例

在挂载了 maya 服务的 MCPTask 节点中，可直接输入：

• “创建一个包含 4 个车轮、具有流线型运动跑车风格的汽车基础模型。”
• “生成一棵包含 3 个主枝干且树叶茂密的松树模型。”
• “构建一座带有窗户细节的楼宇，并为其表面赋予红砖纹理材质。”
• “生成一个高脚杯，并为其指定高反射率的金属铬着色器。”
• “生成一条三维阿基米德螺旋曲线，并通过圆形横截面扫掠挤出成一根机械弹簧。”
• “将视口中所有的室内家具模型整体打包编组，命名为 LivingRoom_Furniture 并居中对齐世界坐标系原点。”
• “重置场景并将当前成果保存为 my_project.ma。”

---

常见疑难排查 (Troubleshooting)

通信连接失败 (Connection Issues)

• 检查 Maya 软件是否处于正常运行状态；
• 确认是否已在 Script Editor 中成功激活 setup_maya_command_port；
• 检查 JSON 中配置的 Python 路径是否指向了虚拟环境 .venv 内部的执行文件。

权限阻断 (Permission Denied)

• Maya 初次通信时弹出的网络询问弹窗，必须点击 "Allow All" 给予放行。

---

安全警示与风控原则

任意代码动态执行风险 (Arbitrary Code Execution)

Maya MCP 服务器最终会将大模型的生成逻辑转换为 Python / MEL 脚本并在 Maya 解释器内部执行：

• 在执行高破坏性操作（如批量对象布尔运算或脚本清空）前，务必先通过 Cmd/Ctrl+S 将工程保存落盘；
• 在生产制作管线中，建议分段进行复杂模型生成；
• 确保只在受信的网络环境中开放 Command Port。