Manually add a Maya session at a specific host and port.

Boundary: Disambiguated from list_sessions (report the sessions the SessionManager already discovered) and maya_setup_guide (diagnose and repair a connection) — add_session registers a host:port you already know.

Use this when auto-discovery doesn't find your Maya session, or to connect to a Maya instance on a specific port.

Import a Poly Haven CC0 model into Maya (find ids via asset_search).

Boundary: Disambiguated from asset_search (host-side id and metadata lookup that touches no Maya session) — asset_import is the mutating half and needs a live session to import into.

Pipeline: host downloads FBX + textures from the Poly Haven whitelist (https-only, size caps, per-file md5 verify) into the platformdirs cache -> Maya imports the local FBX (explicit meters unit handling) -> texture maps auto-wire by PH naming convention (diff/albedo -> color sRGB; rough/metal -> Raw single-channel; nor_gl -> bump2d normal) -> polycount gate -> group as GRP_asset_ -> bbox/metadata report.

Idempotent by default: a second call with the same asset_id reports the existing group instead of duplicating (force=True re-imports).

Search the Poly Haven CC0 asset index (host-side, no Maya needed).

Boundary: Disambiguated from asset_import (downloads the asset into a live Maya scene and mutates it) — asset_search only resolves ids and metadata, so it needs no session and changes nothing.

Queries https://api.polyhaven.com/assets and returns matching asset metadata. Read-only and idempotent - pure lookup.

Create a camera positioned for a specific shot type.

Boundary: Disambiguated from camera_orbit (animates a turntable around a point over many frames) — camera_create frames one static shot and adds no animation.

Supports industry-standard shot types: extreme_wide, wide, medium, close, extreme_close, over_shoulder, bird_eye, low_angle.

Create an orbiting camera with turntable animation around a point.

Side effects: creates a new camera and animation curves in the scene and marks the scene dirty. Not idempotent — each call adds another camera. Requires an active Maya session.

Boundary: Disambiguated from camera_create (static shot-type framing; use camera_orbit only when an animated orbit is needed).

Execute arbitrary Python or MEL code in an active Maya session.

Runs arbitrary code with full session privileges of the connected Maya process. Execution is irreversible and cannot be undone (modifications do not register an automatic undo chunk). The return value shape is governed by the result_type envelope parameter. Requires an established Maya session (discoverable via list_sessions).

List all active Maya sessions.

Boundary: Disambiguated from add_session (register a host:port by hand) and maya_setup_guide (diagnose an empty result) — list_sessions only reports what is already connected.

Returns a list of session information including:

• session_key: Session key used to interact with tools and resources

• host: Session host address

• port: Session port number

• pid: Maya process ID

• user: Logged-in user

• maya_version: Maya version string

• scene_name: Current scene filename

• scene_path: Full path to current scene

Note: To detect new or removed sessions, clients should call this tool periodically (e.g., every 10-30 seconds) and compare results. The SessionManager automatically scans for new Maya sessions in the background.

If this returns an empty list, call maya_setup_guide() for connection help.

Maya connection setup guide and diagnostics.

Boundary: Disambiguated from list_sessions (read the current session set) and add_session (attach a host:port you already know) — maya_setup_guide diagnoses and repairs the connection itself.

Use this tool when list_sessions returns empty or when setting up Maya MCP for the first time. Provides platform-aware diagnostics, auto-installation of userSetup.py, and step-by-step fallback instructions.

Professional-grade aesthetic analysis with 5 design dimensions.

Analyzes scene aesthetics across 5 professional design dimensions:

1. Color Theory: 60-30-10 rule, temperature balance, harmony type, saturation variety, contrast

2. Spatial Composition: golden ratio proportions, rule-of-thirds alignment, visual weight balance

3. Proportion & Scale: human ergonomic reference, size hierarchy (hero/secondary/tertiary)

4. Lighting Quality: layer composition (key/fill/rim/accent), color temperature consistency

5. Visual Flow: sight line clarity, circulation paths, visual rhythm patterns

Returns an overall score (0-100) with grade (S/A/B/C/D/F) and improvement suggestions.

Boundary: Disambiguated from scene_review (scene_aesthetics evaluates visual design theory and artistic harmony in depth, while scene_review is a broad multi-system scene health audit).

Verify scene state matches expected values.

Use this after modifications to confirm the scene is in the desired state. Enforces the VERIFY step of the ICEV workflow.

Boundary: Disambiguated from scene_validate (checks relational spatial constraints across zones rather than exact expected values for named objects).

Save a real scene snapshot (exportAll of in-memory state).

Boundary: Disambiguated from scene_checkpoint_list (enumerate the checkpoints already written) and scene_rollback (open one and rebind the scene to it) — scene_checkpoint is the write half.

Writes a self-contained .ma into a checkpoints/ directory next to the scene file. On untitled (never-saved) scenes an explicit name is required and produces an ad-hoc snapshot under the Maya workspace — returned with original_file_status="no_original_file" and scene_rebound_to=null. Same-name checkpoints are rejected unless overwrite=True (the old file is preserved via rename).

Honest bounds: the snapshot contains no undo history — after scene_rollback, call scene_snapshot to rebuild context. References are flattened (self-contained, no write-back). Assumes one scene file per session.

List all saved checkpoints for the current scene state.

Boundary: Disambiguated from scene_checkpoint (write a new checkpoint) and scene_rollback (open one and rebind the scene to it) — scene_checkpoint_list only reads what is already on disk.

Saved scenes list <scene_dir>/checkpoints; untitled scenes list the workspace ad-hoc snapshots (adhoc flag per entry).

API-level self-description of ONE node (not spatial).

Boundary: scene_inspect answers WHERE an object is (position, bbox, neighbors); scene_nodes discovers candidate node names; scene_describe answers WHAT the node is at the API level - exact node type, per-attribute metadata, and connection wiring - so you can compose accurate execute_code/setAttr/connectAttr calls against real names.

Export the Maya scene (or named objects) to a local file.

Writes through cmds.file with prompt=False forced (a modal dialog would hang the command channel). Formats: fbx, obj, usd (Alembic is not supported - its AbcExport API is not a cmds.file surface). The selection set is restored after every objects= export and the scene's modified flag is untouched.

destructive_hint is False but note: overwrite=True permanently replaces the target file - that path is not recoverable.

Deep inspection of a specific object or zone.

Returns detailed properties including transform, BBox, material, mesh stats, and optionally nearby objects with distances.

Boundary: Disambiguated from scene_snapshot (broad whole-scene spatial overview) and scene_describe (API-level attribute metadata, types, and connection wiring).

Measure the spatial relationship between two objects.

Call this in the COMPUTE step of the ICEV workflow, to turn a spatial question into a number before you execute a change: size a clearance before moving something, prove two objects interpenetrate before you separate them, or get the axis detail behind an overlap that scene_validate reported.

Read-only and idempotent: it queries world-space bounding boxes and never modifies the scene, so no undo checkpoint is created. Requires an active Maya session.

Every mode measures world-space AABBs, not the mesh surface and not the object origin. The modes differ in what the number means: center distance between the AABB midpoints. surface distance between the closest facing AABB corners — an axis-aligned approximation, so it over-reports clearance for rotated or concave geometry. clearance SIGNED, and 0 is NOT a "merely touching" signal. Per axis the gap is +separated / 0=touching / -penetrating: > 0 euclidean distance across the STRICTLY SEPARATED axes only. Penetrating axes contribute 0, so they are invisible in this number. = 0 no axis is strictly separated and at least one axis is exactly touching. The other axes may be deeply penetrating, so 0 does NOT mean the boxes just touch. < 0 all three axes penetrate; the value is the SHALLOWEST penetration depth, the minimum translation needed to pull them apart. bbox_overlap is true if and only if all three axes strictly penetrate. A single penetrating axis already makes it read false, so it can never be read as "no penetration". Read details.clearances_xyz for the signed per-axis truth before concluding anything from distance alone. bbox overlap test. On overlap, distance is 0 and overlap_dims holds the per-axis penetration extents; otherwise distance is euclidean and gaps_xyz holds the per-axis gaps.

Distances are in the scene's current linear unit (cm, m or mm), not always centimetres.

Boundary: Disambiguated from scene_inspect (per-object property deep-dive), scene_snapshot (whole-scene spatial overview) and scene_assert (checks the scene against expected values rather than measuring one pair).

Bounded enumeration of scene nodes - including non-DAG nodes.

Boundary: scene_snapshot is the low-resolution spatial overview you call once per workflow; scene_nodes is the name-discovery complement for the API layer - it lists nodes a spatial view never shows (materials, shadingEngines, tool nodes) and pages honestly: has_more/next_cursor tell you when the list was cut (for attribute schema and connection inspection, call scene_describe).

Holistic scene planning with organization validation and layout optimization.

Performs comprehensive scene health check and generates actionable plans:

• Organization validation: detects orphan meshes, empty groups, default names

• Zone analysis: coverage and spatial balance across functional zones

• Layout suggestions: spacing, overlap, and clustering detection

• Conflict prevention: near-miss collision prediction

• Action plan: prioritized step-by-step execution guide

Based on blockout-first methodology: validate organization and proportions before committing to detailed modeling. Supports natural language objectives.

Boundary: Disambiguated from scene_review (scene_plan focuses on forward-looking layout planning and actionable auto_fix reorganization, whereas scene_review provides an overall diagnostic audit score).

Single-frame playblast preview from a camera (clean, no HUD).

Boundary: Disambiguated from scene_viewport_snapshot (capture the panel as the artist sees it, HUD and selection highlights included) — scene_render_preview renders a chosen camera with the HUD suppressed.

GUI sessions only - headless sessions get a structured gui_session_required error.

Side-effect disclosures (read_only_hint is honest):

1. Switching the panel camera via the modelPanel camera flag is instantaneous, visible, and NOT undoable in Maya.

2. Net-zero side effect: the panel camera is restored on every path - success or failure - so terminal state equals entry.

3. The current time may visibly jump during capture; it is restored afterwards (playblast timeline quirk).

4. viewer=False: no playblast window pops up.

5. On failure the restore is still attempted; a failed restore is logged, never raised over the error result.

6. Only a killed Maya process can skip the restore.

Comprehensive scene audit - reviews all aspects after operations.

Runs spatial integrity, overlap detection, zone coverage, aesthetics, constraint validation, orphan detection, naming, componentization, conflicts, lighting quality, and scene organization. Returns a score (0-100) and detailed issue list.

Rules registered in the Maya session with _mcp_scene.register_validator(...) (call it through execute_code) are reported in a separate "custom" section - validators per rule, score/max_score in weight points, issues for what did not pass. The built-in score is unchanged and the section is absent when nothing is registered.

Boundary: Disambiguated from scene_validate (narrow rule-based spatial constraint checking) and scene_aesthetics (in-depth 5-dimension aesthetic theory scoring).

Use this after any major scene modification to verify quality.

Open a checkpoint and rebind the scene to its original path (S2).

Boundary: Disambiguated from scene_checkpoint (write a checkpoint from the current state) and scene_checkpoint_list (enumerate the ones already written) — scene_rollback is the restore half.

Before opening, the current in-memory state is exported to an auto_before_rollback safety snapshot; if that fails, the rollback aborts — pass discard_current_state=True to escape (the result reports safety_snapshot="skipped_by_user"). Untitled scenes and ad-hoc snapshots have no original path, so the scene stays on the checkpoint path (S1) and scene_rebound_to is null.

The snapshot carries no undo history — call scene_snapshot afterwards to rebuild context.

Get a complete spatial overview of the current Maya scene.

Returns a structured description of ALL objects with positions, sizes, and types. Call this once at the start of each workflow to establish spatial awareness.

Boundary: Disambiguated from scene_inspect (deep-dive inspection of specific objects or zones) and scene_nodes (granular DAG/DG node name discovery with pagination).

Validate scene against spatial constraints.

Checks the scene for constraint violations like minimum clearance, object limits, overlaps, and height requirements. This is a read-only check without auto_fix mutations (it cannot modify or repair objects; for automated fixes, see scene_plan with auto_fix=True). Because it is non-destructive, no undo rollback checkpoint is created. Requires an active Maya session.

Boundary: Disambiguated from scene_review (full scene quality audit across 11 checks) and scene_assert (verifies specific numeric values or object existence).

Capture the active viewport as an image (WYSIWYG).

Boundary: Disambiguated from scene_render_preview (playblast a frame from a chosen camera with the HUD suppressed) — scene_viewport_snapshot captures the panel exactly as the artist sees it, HUD included.

GUI sessions only - headless (mayapy/batch/native-channel) sessions get a structured gui_session_required error.

The capture is what the artist sees: viewport HUD, selection highlights and ornaments included. That is a feature - the agent verifies exactly what the user is looking at. A cmds.refresh(force=True) runs first so the frame is current.

Create a virtual in-memory Python module in an active Maya session.

Injects reusable Python functions into the target Maya session's sys.modules. Modules are virtual and in-memory: they do not persist across Maya restarts, and existing modules are protected unless overwrite=True is explicitly set. Requires an active Maya session.

Boundary: Use write_module to define reusable libraries and helper functions; use execute_code for one-shot imperative execution or expression evaluation.