mcp-for-maya

Manually add a Maya session at a specific host and port. 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). 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_<id> -> 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). 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. Supports industry-standard shot types: extreme_wide, wide, medium, close, extreme_close, over_shoulder, bird_eye, low_angle.

Create a camera that orbits around a point with animation.

Execute Python code in a Maya session.

List all active Maya sessions. 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. 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.

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.

Save a real scene snapshot (exportAll of in-memory state). 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. 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_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.

Measure spatial relationship between two objects.

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.

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.

Single-frame playblast preview from a camera (clean, no HUD). GUI sessions only - headless sessions get a structured gui_session_required error. Side-effect disclosures (read_only_hint is honest, D-026): 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. Use this after any major scene modification to verify quality.

Open a checkpoint and rebind the scene to its original path (S2). 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.

Validate scene against spatial constraints. Checks the scene for constraint violations like minimum clearance, object limits, overlaps, and height requirements.

Capture the active viewport as an image (WYSIWYG). 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 Python module in a Maya session.