mcp-for-maya

English | 简体中文

mcp-for-maya

为 AI Agent 提供 Autodesk Maya 场景空间感知能力的 MCP 服务

这是什么

mcp-for-maya 是一个 模型上下文协议（MCP）服务，让大模型 Agent（Codex、Claude 等）能够直接驱动 Autodesk Maya，进行 3D 建模、场景规划和工程级交付。

本项目从 chadrik/maya-mcp-server 派生，在上游连接栈的基础上增加了场景智能层：空间感知、确定性审计、事务安全和可视化循环。

**核心能力：**Agent 不再“盲目编写”——它可以感知空间状态、材质和对象关系，然后依据工程规则验证变更。

警告

此服务会在 Maya 中执行任意 Python——这是有意设计的能力，并非漏洞。内置的验证 / 速率限制 / 审计流程是用于应对意外和注入指令的安全网，而不是防范恶意客户端的边界；连接的 Agent 是可信的。请参阅 docs/threat-model.md。

以下所有素材均由本项目自己的工具链实际采集，并非样图：场景通过 execute_code / write_module（以及一次实时 asset_import）以程序化方式构建；画面通过 scene_render_preview 渲染；审计素材由 scene_review + scene_viewport_snapshot 生成；环绕序列则通过 playblast 逐帧采集（Maya 2024 GUI 会话）。

提示词	结果
write_module → t20_movement.build() — “参数化渐开线齿轮机芯：真正的渐开线齿形、日内瓦条纹夹板、蓝钢螺丝、红宝石轴承、螺旋游丝”
write_module → t20_bonsai.build() — “低多边形 L-system 盆景：递归分枝、多面叶簇、花盆 + 苔藓 + 石头”
asset_import("vintage_pocket_watch") + asset_import("metal_tool_chest") → t20_workbench.build() — “钟表匠工作台：导入的资源已接入纹理，程序化生成渐开线备用零件”
write_module → t20_street.build() — “低多边形街角街区：11 栋参数化建筑、山墙屋顶、遮阳篷、街道设施、停放的货车”
write_module → t20_teapot.build() — “犹他茶壶复刻：旋转轮廓生成壶身、贝塞尔曲线渐缩壶嘴、耳形把手、棋盘格地面”
scene_review() 检查堆满杂物的工作台 → scene_plan(auto_fix=True) 并清理 → 再次运行 scene_review() — 评分 53.7 → 64.2

使用 .github/assets-src/ 中的脚本即可复现每一帧。

与 blender-mcp 的比较

与 ahujasid/mcp-for-blender 进行坦诚的三级比较（测量于 2026-09）：

级别	内容
本项目独有	ICEV 强制工作流（位于服务说明中）、CoS 符号输出、检查点／回滚事务安全机制、scene_plan 整体规划（区域映射 + 布局建议）、多会话管理、11 项确定性审计检查、带元数据的播放预览渲染
blender-mcp 独有	丰富的资源生态（Sketchfab/Hyper3D/Hunyuan3D）、一流的对象 CRUD 工具、AI 生成模型集成、社区规模
共有	MCP 工具接口、Poly Haven 资源来源、视口截图反馈、任意 Python 执行、本地套接字连接

Poly Haven 模型搜索 + 导入功能已在 0.2.0 中发布（issue #2 的精简实现：FBX + 纹理接入；HDRI 和纹理包仍在路线图中）。AI 生成和一流的对象 CRUD 明确不在范围内——后者已由 execute_code 覆盖。 在共享的资源下载路径中，本项目的控制措施由代码强制执行，而非依赖常规约定：下载仅在主机端进行——使用 HTTPS + 主机白名单、逐文件 MD5 校验、大小上限，以及根据 URL 最后一个路径段清理文件名（polyhaven.py）——Maya 本身不会访问网络。强制措施详情：docs/threat-model.md。

能力	工具	说明
🧊 空间感知	scene_snapshot scene_inspect scene_measure	一次调用即可获得完整场景空间模型；精确测量距离／重叠／间隙
🎨 美学分析	scene_aesthetics	5 个维度：色彩理论（60-30-10）、空间构图（黄金比例／三分法）、比例与尺度（人体工学）、灯光质量（三点布光／补光比例／色温／衰减）、视觉流线
🎬 摄像机规划	camera_create camera_orbit	8 种行业标准镜头类型 + 环绕动画
🛡️ 灾难恢复	scene_checkpoint scene_rollback scene_checkpoint_list	导出内存中的快照；回滚时显式重新绑定原始路径
🧠 场景规划	scene_plan	组织健康度、区域平衡、布局建议、冲突预防、自然语言规划
📋 工程审计	scene_review scene_validate scene_assert	11 项确定性检查（0-100 分）+ 自定义约束验证 + 状态断言
⚡ 代码执行	execute_code write_module	在 Maya 中运行任意 Python 代码／注入可复用模块
👁️ 视觉循环	scene_viewport_snapshot scene_render_preview	所见即所得视口捕获 + 单帧 playblast 预览（仅限 GUI 会话）
🔌 会话管理	list_sessions add_session maya_setup_guide	多会话发现／连接 + 连接诊断／安装／回退指导
📦 资源库	asset_search asset_import	Poly Haven CC0 模型——主机端 HTTPS 下载（主机白名单、MD5 校验、大小上限、platformdirs 缓存），Maya 端 FBX 导入并连接纹理，面数／尺寸保护，GRP_asset_<id> 去重
📤 场景导出	scene_export	FBX／OBJ／USD 导出——整个场景或指定对象；根据扩展名推断格式（冲突时报错，绝不猜测），自动创建父目录，需显式选择是否覆盖，恢复所选对象
🔎 场景图内省	scene_describe scene_nodes	API 级节点自描述（精确类型、逐属性元数据：可设关键帧／可连接／枚举／范围、连接关系——限制大小并通过 *_truncated 标明截断，limit 最高为 1000）+ 有界枚举，包括非 DAG 节点（材质／工具节点），并支持 has_more／next_cursor 分页

总计 25 个 MCP 工具。

1. 安装

# Install from PyPI (recommended)
pip install mcp-for-maya

# or run straight away with uvx
uvx mcp-for-maya

# alternative: install from git with uv
uv tool install git+https://github.com/Xxx91n/mcp-for-maya.git

# or clone the source
git clone https://github.com/Xxx91n/mcp-for-maya.git
cd mcp-for-maya
pip install -e .

说明

三层命名：发行包名称 mcp-for-maya（PyPI 包名）→ 安装的导入包 maya_mcp_server（沿用上游名称）；脚本名称 mcp-for-maya（旧名称 maya-mcp-server 仍作为兼容别名保留）。uvx mcp-for-maya 能准确解析，因为命令名称与发行包名称一致。

2. 连接 Maya

选项 A：自动（推荐）

启动 MCP 服务后，Agent 调用 maya_setup_guide 引导完成连接：

1. 确保 Maya 正在运行
2. 向 Agent 发出任意指令（例如“看看我的 Maya 场景”）
3. 如果尚未连接，Agent 会运行诊断，并可安装 userSetup.py（通过幂等标记块合并，写入前创建带时间戳的备份）
4. 重启 Maya 后，命令端口会自动打开

选项 B：手动

在 Maya 的脚本编辑器中（Python 模式，而非 MEL）：

import maya.cmds as cmds

cmds.commandPort(name=":7001", sourceType="python")

选项 C：持久自动连接

将以下内容保存为 Maya 脚本目录中的 userSetup.py：

平台	路径
Windows	%MAYA_APP_DIR%\<version>\scripts\
Linux	~/maya/<version>/scripts/
macOS	~/Library/Preferences/Autodesk/maya/<version>/scripts/

import maya.cmds as cmds

cmds.evalDeferred('cmds.commandPort(name=":7001", sourceType="python")', lowestPriority=True)

多个 Maya 实例

commandPort 是绑定到一个 host:port 的单个侦听套接字——第二个实例无法绑定相同端口，因此每个 Maya 实例都需要使用自己的端口。典型拓扑如下：

Maya 实例	commandPort	备注
实例 A	:7001 python	主实例
实例 B	:7002 python	第二个实例
实例 A	:7011 mel	MEL 端口（自动检测并排除，不会不断报错）

在每个实例中（其脚本编辑器或各自的 userSetup.py），运行 cmds.commandPort(name=":<port>", sourceType="python")。自动扫描是主要方式——服务会定期枚举正在侦听的 Maya 端口并为其引导；如果漏掉某个会话，可使用 add_session(host, port) 手动添加。如果扫描探测到机器上的非 Maya TCP 服务，请通过 MAYA_MCP_INCLUDE_PORTS=7001,7002 限定探测端口（以逗号分隔，也允许使用 7005-7010 范围），或通过 MAYA_MCP_EXCLUDE_PORTS=<port> 排除有问题的端口。

注意：commandPort 不会跨会话持久化——Maya 关闭时它也会关闭；如需持久化，请将其写入 userSetup.py（选项 C）。

故障排除

问题	解决方法
list_sessions 返回空结果	调用 maya_setup_guide(action="diagnose")
端口已被占用	关闭其他 Maya 实例或选择其他端口
未加载 userSetup.py	检查文件是否位于正确的脚本目录中，然后重启 Maya
防火墙阻止连接	确保可以访问 localhost:7001
未列出第二个 Maya 实例	每个实例都需要自己的 commandPort（端口相同会导致绑定冲突）；如果扫描仍未发现它，请调用 add_session(host, port)
脚本编辑器不断报语法错误	这是探测 MEL 端口时的旧版症状——当前版本会自动排除非 Python 端口；如果问题仍然存在，请通过 MAYA_MCP_EXCLUDE_PORTS 排除该端口

3. 配置 MCP 客户端

Codex ~/.codex/config.toml：

[mcp_servers.maya]
command = "uvx"
args = ["mcp-for-maya"]
tool_timeout_sec = 120

使用 git 源时，请设置 args = ["--from", "git+https://github.com/Xxx91n/mcp-for-maya.git", "mcp-for-maya"]；使用源代码检出时，请设置 command = "python"、args = ["-m", "maya_mcp_server"]，并在 env 中将 PYTHONPATH 指向 <repo>/src。

4. 开始使用

直接用自然语言交流：

“看看我的 Maya 场景里有什么，然后在入口处创建一个展示架”

Agent 会调用 scene_snapshot() → 理解场景 → 建模 → scene_review() 审核结果。

每次场景修改都遵循 ICEV 循环（也以 Agent 流程卡的形式提供，参见 skills/icev-workflow）：

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ INSPECT  │ ──→ │ COMPUTE  │ ──→ │ EXECUTE  │ ──→ │ VERIFY   │
│ snapshot │     │  plan    │     │  apply   │     │  audit   │
└──────────┘     └──────────┘     └──────────┘     └──────────┘

1. 检查：使用 scene_snapshot() 获取完整场景空间数据
2. 计算：根据这些数据规划位置、尺寸和间隙
3. 执行：execute_code() 执行 Maya Python
4. 验证：scene_assert() + scene_review() 确认结果；在 GUI 会话中，视觉工具可提供像素级确认

工具参考

空间

scene_snapshot(detail="compact", format="cos")  # full scene in one call
scene_inspect(target="wall_entrance", include_neighbors=True)
scene_measure(obj_a="wall_north", obj_b="counter_A", mode="clearance")
scene_assert(expectations='{"wall": {"exists": true, "position": [0,0,500]}}')

审核

scene_review()  # 11 deterministic checks, 0-100 score
scene_validate(rules='[{"type": "min_clearance", "value": 180}]')

摄像机

camera_create(target="product_display", shot_type="medium", azimuth=30, elevation=15)
# extreme_wide / wide / medium / close / extreme_close / bird_eye / low_angle / over_shoulder
camera_orbit(center=[0, 100, 0], radius=500, frames=120)

灾难恢复

scene_checkpoint(name="before_renovation")  # exportAll in-memory snapshot; no undo history
scene_checkpoint_list()
scene_rollback(filename="cp_before_renovation.ma")
# auto safety snapshot first, then rebinds the scene name to the original path
# call scene_snapshot() after a rollback — snapshots carry no undo history
# self-contained: references are flattened (no write-back); one scene file per session assumed

资源（Poly Haven，由主机端下载）

asset_search(query="camera", asset_type="models", limit=20)  # Poly Haven index
asset_import(asset_id="Camera_01", resolution="1k")
# HTTPS-only download into a platformdirs cache (per-file md5 verify + sha256 audit),
# then Maya imports the local FBX under GRP_asset_<asset_id> (repeat calls dedup;
# force=True re-imports). Textures auto-wire by filename suffix
# (diff/rough/metal/nor_gl/ao/disp...) with sRGB/Raw color spaces and bump2d normals.
# Single-part assets ship bare map names (Diffuse/Rough/Metal...) — those are
# recognised too and wired onto the asset's single material.
# Guards: 100k-face polycount cap (allow_high_polycount override), dims sanity report.

场景导出

scene_export(path="D:/out/scene.fbx")  # whole scene; format inferred from .fbx
scene_export(path="/tmp/kit", format="obj")  # missing extension is appended -> kit.obj
scene_export(path="D:/out/kit.usd", objects=["GEO_box"])  # exportSelected; prior selection restored
# format {fbx,obj,usd}: an extension/format conflict is an error, never a guess.
# An existing file is rejected unless overwrite=True. prompt=False is forced
# (no modal can hang the channel); the scene's modified flag is untouched.
# Alembic is not supported — AbcExport is not a cmds.file surface.

视觉循环（仅限 GUI 会话）

scene_viewport_snapshot(
    max_size=800, format="jpeg"
)  # HUD/selection included — what the artist sees
scene_render_preview(camera="CAM_hero", width=640, height=360)  # clean single-frame playblast
# both return [image, JSON metadata]; headless sessions get a gui_session_required error
# prefer format="png" for wireframe/line-art review; trust returned metadata for actual size

CoS 表示法

默认输出使用 Chain-of-Symbol 表示法压缩场景数据。该格式的论文报告称，在其演示场景中，与 JSON 相比可节省约 65% 的令牌（arXiv:2305.10276，−65.8%）——本项目实现了这种表示法；该数据是论文的测量结果，并非本项目的基准测试结果。

SCENE[164obj, 5zones] UNIT=cm UP=y
shell (23obj) @(-11.8,178.8,145.7)
  GRP_floor[mesh]@(0,0,0) 1121.5x20x1530.5

Agent Skills

skills/ 中包含两个实验性流程卡片：

技能	用途
skills/icev-workflow	ICEV 规范：每次场景修改都必须经过 Inspect→Compute→Execute→Verify
skills/scene-review-playbook	审核手册：说明 11 项检查的评估依据，以及如何将发现的问题对应到修复措施

仅在 Claude Code 上评估过；尚未在 Codex/Gemini CLI/Cursor 上测试。跨模型评估进度记录在 issue #3 中。

scene_review() 提供 11 项通用检查（分数归一化至 0-100）：

检查项	最高分	检查内容
spatial	10	对象/摄像机/灯光是否存在
overlaps	10	边界框碰撞（不包括父子对象）
conflicts	10	无关对象之间的穿透
zones	5	命名规则的分区覆盖情况
naming	5	生产命名规范
components	10	GRP_ 分组 + 嵌套深度 ≤ 4
orphans	5	空组/默认名称
aesthetics	15	5 个维度的美学评估（色彩/构图/比例/照明/流动感）
lighting	10	三点布光、补光比、衰减
organization	10	整体层级结构健康度
constraints	5	自定义规则违规情况

信任与隐私

• 零遥测：不会向外发送数据——项目不包含遥测或未经请求的出站流量；请检查源代码进行验证。唯一的出站调用来自两个资源工具：通过 HTTPS 访问 api.polyhaven.com / dl.polyhaven.org|.com（polyhaven.py 中设有主机允许列表、md5 和大小上限），且仅在调用这些工具时发生。
• 本地、单用户：命令端口仅绑定到 localhost；连接的 MCP 客户端受信任。
• 安全网：统一管线（pipeline.py + security.py）会验证参数、执行令牌桶速率限制（每个会话每 60 秒约 100 次读取、约 20 次写入）、模式扫描（默认仅警告），并为全部 25 个工具记录独立的 JSONL 审计日志。它能防止意外操作，但无法防范恶意客户端——完整模型见 docs/threat-model.md。
• 事务安全：scene_checkpoint/scene_rollback 提供内存快照和显式回滚（没有撤销历史；引用会被扁平化）。
• 严格策略模式（可选）：设置 MAYA_MCP_DISABLE_EXECUTE=1、MAYA_MCP_DISABLE_WRITE_MODULE=1 或 MAYA_MCP_DISABLE_ARBITRARY=1（可同时设置全部三项），即可从 tools/list 中移除逃生舱工具，并以 [policy_disabled] 拒绝调用。只读工具不受影响。这些是防误用护栏，而非抵御恶意 Agent 的边界——仍持有 execute_code 的 Agent 已经处于信任边界之内；这些设置的作用是缩小演示、误操作或 CI 沙箱中的影响范围。设计依据：docs/threat-model.md。各错误码的参考文档：docs/guide/error-codes.md。
• 漏洞报告：SECURITY.md。

版本管理

本项目遵循语义化版本：

• 0.x（截至 0.3.x，Alpha）：工具接口仍可能变更；小版本更新包含新功能，不冻结兼容性。
• Beta（0.4.0）：功能完备阶段——从此版本开始接受外部测试（分类标记为 4 - Beta）。
• 1.0.0：冻结公开 API——工具接口和输出架构按语义化版本保持稳定；破坏性变更需要升至 2.0.0。与 5 - Production/Stable 分类标记在同一提交中一并升级；升级受 #7 真机检查清单约束（通过项全部为绿色，并明确列出获准豁免的项目及负责人／到期时间——三态门槛，D-163）。

公开 API 指 MCP 工具接口：工具名称、输入／输出结构、两层错误契约（主机 isError 故障与 {error:{code,message,suggestion}} 领域结果），以及工具注释语义（docs/threat-model.md §5）。增量变更（新增工具、新增可选响应字段）以小版本发布；破坏性变更以大版本发布。1.0.0 是对这一接口作出冻结承诺，并非质量认证：剩余的真机验证范围会在 #7 中明确跟踪，而不会被含糊带过。

发布由里程碑驱动——不承诺固定周期。路线图位于 GitHub issues：#2 Poly Haven 集成（模型部分已在 0.2.0 发布；scene_plan 推荐功能的剩余部分拆分到 #31）、#3 Skills 计划（v1.x）、#4 安全与权限模型（v1.x）、#5 场景导出 + 内省（scene_export 已在 0.3.0 发布：FBX/OBJ/USD；scene_describe/scene_nodes 内省也已在同一 0.3.0 版本发布）、#6 更多素材来源（探索中）、#7 真机检查清单 + v1.0 反馈（置顶）。

要求

环境	要求
主机（运行 MCP 服务）	Python >= 3.10（requires-python）；Windows / Linux / macOS
注入的辅助程序（在 Maya 中运行）	Maya >= 2023（内置 Python >= 3.9；依赖 ast.unparse——注入时会明确拒绝较旧版本）
已验证环境	Maya 2024 GUI

这两个视觉循环工具需要 GUI 会话（headless/mayapy 会返回结构化的能力错误）。首次捕获时，服务会按会话探测 VP2 读回方向（使用一次性场景探测，无净副作用）；如果驱动报告有误，可通过 MAYA_MCP_VP2_BOTTOM_UP=0|1 强制指定。

开发

uv sync --frozen                  # locked dev env from uv.lock (alt: pip install -e . --group dev, pip>=25.1)
python -m pytest tests/ -q       # tests
ruff check src tests             # lint
mypy src                         # typecheck
python -m maya_mcp_server -vv    # run with DEBUG logs (-v=INFO, -vv=DEBUG)

PR 流程请参阅 CONTRIBUTING.md，变更日志请参阅 CHANGELOG.md。

致谢

本项目分叉自 chadrik/maya-mcp-server——保留上游 MIT 版权声明（见 LICENSE）；本项目在其连接栈之上增添了场景智能层。

本分叉如何处理每个上游未解决问题及其对应的发布版本，请参阅：docs/upstream-issue-status.md。