mcp-for-maya

English | 简体中文

[mcp-for-maya — Give AI agents eyes inside Autodesk Maya]

mcp-for-maya

MCP server giving AI agents spatial awareness of Autodesk Maya scenes

[CI] [PyPI] [License: MIT] [Python]

What this is

mcp-for-maya is a Model Context Protocol (MCP) server that lets LLM agents (Codex, Claude, etc.) drive Autodesk Maya for 3D modeling, scene planning, and engineering-grade delivery.

Forked from chadrik/maya-mcp-server. The fork keeps the upstream connection stack and adds a scene-intelligence layer: spatial awareness, deterministic auditing, transactional safety, and a visual loop. The agent stops writing blind — it reads spatial state, materials, and object relationships, then verifies changes against engineering rules.

[!WARNING] This server executes arbitrary Python inside Maya — a designed capability, not a bug. The validation / rate-limit / audit pipeline is a safety net for accidents and injected instructions, not a boundary against a malicious client; the connected agent is trusted. See docs/threat-model.md.

Every asset below is a real capture produced by this project's own tool chain — no mockups: scenes were built procedurally through execute_code / write_module (plus one live asset_import), frames rendered through scene_render_preview, the audit pair via scene_review + scene_viewport_snapshot, and the orbit sequence captured frame-by-frame with playblast (Maya 2024 GUI session).

[movement orbit — 20 real playblast frames, 120° sweep]

Reproduce every frame with the scripts in .github/assets-src/.

vs blender-mcp

Three-tier comparison with ahujasid/mcp-for-blender (measured 2026-09):

Poly Haven model search + import shipped in 0.2.0 (issue #2 thin slice: FBX + texture wiring; HDRIs and texture packs remain roadmap). AI generation and first-class object CRUD are out of scope — the latter is already covered by execute_code.

On the shared asset-download path, this project's controls are enforced in code: downloads happen host-side only — https + host allowlist, per-file md5, size caps, filenames sanitized from the URL's last segment (polyhaven.py) — and Maya itself never touches the network. Enforcement detail: docs/threat-model.md.

25 MCP tools in total.

1. Install

# Install from PyPI (recommended)pip install mcp-for-maya
# or run straight away with uvxuvx mcp-for-maya
# alternative: install from git with uvuv tool install git+https://github.com/Xxx91n/mcp-for-maya.git
# or clone the sourcegit clone https://github.com/Xxx91n/mcp-for-maya.gitcd mcp-for-mayapip install -e .

[!NOTE] Three-layer naming: dist name mcp-for-maya (PyPI shelf name) → installs import package maya_mcp_server (kept from upstream); script name mcp-for-maya (old name maya-mcp-server remains as a compat alias). uvx mcp-for-maya resolves precisely because the command name matches the dist name.

2. Connect Maya

Option A: automatic (recommended)

With the MCP server running, the agent calls maya_setup_guide to walk the connection:

1. Make sure Maya is running
2. Give the agent any instruction (e.g. "look at my Maya scene")
3. If unconnected, the agent runs diagnostics and can install userSetup.py (idempotent marker-block merge, timestamped backup before writing)
4. After restarting Maya, the command port opens automatically

Option B: manual

In Maya's Script Editor (Python mode, not MEL):

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

Option C: persistent auto-connect

Save this as userSetup.py in your Maya scripts directory:

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

Multiple Maya instances

A commandPort is a single listening socket bound to one host:port — a second instance fails to bind the same port, so each Maya instance needs its own port. Typical topology:

Run cmds.commandPort(name=":<port>", sourceType="python") inside each instance (its Script Editor or its own userSetup.py). Auto-scan is the primary path — the server periodically enumerates listening Maya ports and bootstraps them; if a session is missed, add_session(host, port) is the manual fallback. If scanning probes a non-Maya TCP service on the box, bound the probe set with MAYA_MCP_INCLUDE_PORTS=7001,7002 (comma-separated, 7005-7010 ranges allowed) or exclude offenders via MAYA_MCP_EXCLUDE_PORTS=<port>.

Note: a commandPort does not persist across sessions — it dies with Maya; for persistence write it into userSetup.py (Option C).

Troubleshooting

3. Configure the MCP client

Codex ~/.codex/config.toml:

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

For the git source use args = ["--from", "git+https://github.com/Xxx91n/mcp-for-maya.git", "mcp-for-maya"]; for a source checkout use command = "python", args = ["-m", "maya_mcp_server"], and point PYTHONPATH at <repo>/src under env.

4. Use it

Talk naturally:

"Look at what's in my Maya scene, then create a display shelf at the entrance"

The agent calls scene_snapshot() → understands the scene → models → scene_review() audits the result.

Every scene modification follows the ICEV loop (also shipped as an agent process card, see skills/icev-workflow):

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

1. INSPECT: scene_snapshot() for full-scene spatial data
2. COMPUTE: plan positions, sizes, clearances from that data
3. EXECUTE: execute_code() applies Maya Python
4. VERIFY: scene_assert() + scene_review() confirm the result; on GUI sessions the visual tools give pixel-level confirmation

Tools reference

Spatial

scene_snapshot(detail="compact", format="cos")  # full scene in one callscene_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]}}')

Audit

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

Cameras

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

Disaster recovery

scene_checkpoint(name="before_renovation")  # exportAll in-memory snapshot; no undo historyscene_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

Assets (Poly Haven, host-side download)

asset_search(query="camera", asset_type="models", limit=20)  # Poly Haven indexasset_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

scene_export(path="D:/out/scene.fbx")  # whole scene; format inferred from .fbxscene_export(path="/tmp/kit", format="obj")  # missing extension is appended -> kit.objscene_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.

Visual loop (GUI sessions only)

scene_viewport_snapshot(    max_size=800, format="jpeg")  # HUD/selection included — what the artist seesscene_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 notation

Default output uses Chain-of-Symbol notation to compress scene data. The format's paper reports ~65% token savings vs JSON on its demo scenes (arXiv:2305.10276, −65.8%) — this project implements the notation; that figure is the paper's measurement, not a benchmark of this project.

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

Agent skills

Two Experimental process cards ship in skills/:

Evaluated on Claude Code only; untested on Codex/Gemini CLI/Cursor. Cross-model evaluation is tracked in issue #3.

scene_review() provides 11 universal checks (score normalized to 0-100):

Trust & privacy

• Zero telemetry: no phone-home — the project ships no telemetry or unsolicited outbound traffic; verify in source. The ONLY outbound calls are the two asset tools: HTTPS to api.polyhaven.com / dl.polyhaven.org|.com (host allowlist + md5 + size caps in polyhaven.py), and only when you call them.
• Local, single-user: the command port binds localhost only; the connected MCP client is trusted.
• Safety net: a unified pipeline (pipeline.py + security.py) validates arguments + token-bucket rate limits (~100/60s reads, ~20/60s writes, per session) + pattern scan (warn-only by default) + an independent JSONL audit log across all 25 tools. It catches accidents, not malicious clients — full model in docs/threat-model.md.
• Transactional safety: scene_checkpoint/scene_rollback give in-memory snapshots and explicit rollback (no undo history; references flattened).
• Strict policy mode (optional): set MAYA_MCP_DISABLE_EXECUTE=1, MAYA_MCP_DISABLE_WRITE_MODULE=1, or MAYA_MCP_DISABLE_ARBITRARY=1 (all three) to remove the escape-hatch tools from tools/list and deny the call with [policy_disabled]. Read-only tools are unaffected. These are misuse guardrails, not a hostile-agent boundary — an agent that still holds execute_code is already inside the trust boundary; what they buy is a smaller blast radius for a demo, a mistake, or a CI sandbox. Rationale: docs/threat-model.md. Per-code reference: docs/guide/error-codes.md.
• safe_mode AST gate (optional): set MAYA_MCP_SAFE_MODE=1 (default off) and the two code-bearing tools stay listed but their code payloads pass a deny-by-default AST allowlist: v1 import roots (maya/math/json/re/collections/itertools/functools/dataclasses/typing), no denied builtin names — every reference rejects, not just calls (eval/exec/open/__import__/getattr/setattr/…), no __builtins__, no dunder attribute access, and unparseable input rejects ("cannot decide ⇒ deny"). Rejections raise [safe_mode_rejected] (a host isError failure) naming the rule id and are audited rejected; successful responses carry mode: "safe" and the tool descriptions gain one Boundary: line. DISABLE flags still remove tools first — safe_mode only narrows what remains. Same posture as the DISABLE flags: a safety net, not a boundary. Rationale: docs/threat-model.md. Per-code reference: docs/guide/error-codes.md.
• Vulnerability reporting: SECURITY.md.

Versioning

This project follows Semantic Versioning:

• 0.x (through 0.3.x, Alpha): the tool surface could still change; minor bumps carried features, no compatibility freeze.
• Beta (0.4.0 onward; current release 0.7.0): feature-complete tier — external testing begins here (classifier 4 - Beta).
• 1.0.0: public API freeze — tool surface and output schemas stable per semver; breaking changes require 2.0.0. Promoted together with the 5 - Production/Stable classifier in one commit; gated by the #7 real-machine checklist.

The public API is the MCP tool surface: tool names, their input/output shapes, the two-layer error contract (host isError failures vs {error:{code,message,suggestion}} domain results), and tool-annotation semantics (docs/threat-model.md §5). Additive changes (new tools, new optional response fields) ship as minor releases; breaking changes ship as a major bump. 1.0.0 freezes this surface — it is not a quality certification; the remaining real-machine verification surface is tracked explicitly in #7.

Releases are milestone-driven — no fixed cadence. Roadmap lives in GitHub issues: #2 Poly Haven integration (model slice shipped in 0.2.0; scene_plan recommendation residual split to #31), #3 Skills program (v1.x), #4 security & permission model (v1.x), #5 scene export + introspection (both shipped in 0.3.0), #6 more asset sources (exploratory), #7 real-machine checklist + v1.0 feedback (pinned).

Requirements

The two visual-loop tools need a GUI session (headless/mayapy returns a structured capability error). On the first capture the server probes the VP2 readback direction per-session (a disposable scene probe, net-zero side effects); MAYA_MCP_VP2_BOTTOM_UP=0|1 forces it when a driver misreports.

Development

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

See CONTRIBUTING.md for the PR flow and CHANGELOG.md for the change log.

Credits

Forked from chadrik/maya-mcp-server — upstream MIT copyright retained (see LICENSE); this project adds the scene-intelligence layer on top of its connection stack.

How each upstream open issue maps to a disposition and release version in this fork: docs/upstream-issue-status.md.