dcc-mcp-maya 0.3.4

Maya plugin for the DCC Model Context Protocol (MCP) ecosystem — embeds a Streamable HTTP MCP server directly inside Maya

dcc-mcp-maya

Bring Autodesk Maya to MCP-native AI agents.

dcc-mcp-maya turns Maya into a standards-compliant MCP Streamable HTTP backend. Agents can inspect scenes, create geometry, edit materials, run animation and render workflows, export assets, and recover project state through typed tools instead of brittle ad-hoc scripts.

The Maya plugin starts a Rust dcc-mcp-server sidecar by default, so HTTP and gateway traffic stay isolated from Maya's UI thread while actual Maya API work is routed through Maya-safe dispatchers.

Why Use It

What you get	Why it matters
164 typed Maya tools across 23 bundled skill packages	Agents can call validated tools for scene, mesh, material, animation, render, export, and pipeline work.
Progressive loading	Maya boots with a compact tool surface; agents discover unloaded capabilities and load only what they need.
Sidecar isolation by default	HTTP/gateway runtime is out of Maya's UI thread, with a Qt dispatcher bridge back into Maya.
Multi-instance gateway	Run several Maya sessions behind one local MCP URL, with optional LAN gateway exposure.
Operational guardrails	Readiness probes, project persistence, MCP resources, job persistence, crash cleanup, cancellation, and script-execution lockouts.

Quick Start

Install into Maya's Python:

mayapy -m pip install dcc-mcp-maya

Start directly from Maya's Script Editor or a mayapy script:

import dcc_mcp_maya

handle = dcc_mcp_maya.start_server(port=8765)
print(handle.mcp_url())  # http://127.0.0.1:8765/mcp

Or load the Maya plugin from maya/plugin/dcc_mcp_maya_plugin.py. Plugin mode starts automatically and defaults to the sidecar gateway:

{
  "mcpServers": {
    "maya": {
      "url": "http://127.0.0.1:9765/mcp"
    }
  }
}

If you start the Python server manually with start_server(port=8765), point your MCP host at http://127.0.0.1:8765/mcp instead.

Architecture

The default plugin path is:

1. MCP host connects to the elected gateway at http://127.0.0.1:9765/mcp.
2. dcc-mcp-server sidecar owns the HTTP runtime and gateway election.
3. The sidecar calls back into Maya through the Qt event-loop dispatcher.
4. MayaMcpServer routes work to typed skills, resources, project tools, readiness, metrics, and the Maya API.

Set DCC_MCP_MAYA_SIDECAR=0 before loading the plugin to use the legacy in-process gateway path. Newer sidecar binaries also expose the elected gateway on the LAN at http://<this-machine-lan-ip>:59765/mcp; set DCC_MCP_GATEWAY_REMOTE_PORT=0 to disable that listener.

Tool Surface

Default startup is intentionally small: maya-scripting and the core maya-scene group are available immediately, while other skills stay discoverable through dcc_capability_manifest, search_skills, and search_tools.

Stage	Purpose	Skills
bootstrap	Escape hatch when no typed skill fits	maya-scripting
scene	Scene lifecycle, DAG, attributes, node graph, viewport display	maya-scene, maya-scene-assembly, maya-display, maya-attributes, maya-node-graph
authoring	Meshes, UVs, materials, rigs, animation, expressions, lighting	maya-primitives, maya-mesh-ops, maya-uv-ops, maya-materials, maya-material-library, maya-texture-bake, maya-rigging, maya-animation, maya-pose-library, maya-expressions, maya-light-rig
interchange	Geometry and scene I/O	maya-geometry, maya-export-preset
pipeline	Project, publish, shot export, render, render farm	maya-pipeline, maya-shot-export, maya-render, maya-render-farm

Typical agent flow:

search_skills / dcc_capability_manifest
  -> load_skill("maya-primitives")
  -> maya_primitives__create_sphere(...)
  -> activate_group("extended") only when optional tools are needed

execute_python and execute_mel remain available as escape hatches, but production deployments can block them with DCC_MCP_MAYA_DISABLE_EXECUTE_PYTHON=1, DCC_MCP_MAYA_DISABLE_EXECUTE_MEL=1, or DCC_MCP_MAYA_DISABLE_ARBITRARY_SCRIPT=1.

See src/dcc_mcp_maya/skills/SKILLS_INDEX.md for task-to-skill routing examples and docs/guide/mcp-tools.md for a user-facing tool map.

Runtime Features

Feature	Surface
Capability manifest	dcc_capability_manifest({"loaded_only": false}) returns a compact index of loaded and unloaded Maya actions without full schemas.
MCP resources	scene://current, maya-cmds://help/<command>, maya-cmds://flags/<command>, maya-api://signatures/<class>, maya-project://current.
Readiness	/v1/readyz reports process, dispatcher, and dcc readiness before orchestration routes work to Maya.
Project state	project.save, project.load, project.resume, and project.status persist state under <scene_dir>/.dcc-mcp/project.json.
Job persistence	Optional SQLite-backed job storage with DCC_MCP_MAYA_JOB_STORAGE and DCC_MCP_MAYA_JOB_RECOVERY=requeue.
Shutdown hardening	Maya exiting hook, atexit, process sentinel, and optional defensive finalizer reduce stale registry rows.
Safe sessions	MCP-dispatched Maya jobs suppress blocking modal dialogs and snooze AutoSave unless opted out.
Metrics	Optional Prometheus /metrics endpoint via DCC_MCP_MAYA_METRICS=1.

Installation

PyPI

mayapy -m pip install dcc-mcp-maya

For plugin-side sidecar mode, install the sidecar extra when your environment does not already provide dcc-mcp-server:

mayapy -m pip install "dcc-mcp-maya[sidecar]"

Maya Plugin

1. Put maya/plugin/dcc_mcp_maya_plugin.py on MAYA_PLUG_IN_PATH.
2. Load it from Window > Settings/Preferences > Plug-in Manager.
3. Or load it from userSetup.py:

import maya.cmds as cmds

cmds.loadPlugin("dcc_mcp_maya_plugin")

Useful plugin defaults:

Mode	URL
Plugin sidecar gateway	http://127.0.0.1:9765/mcp
Optional LAN gateway	http://<this-machine-lan-ip>:59765/mcp
Direct start_server(port=8765)	http://127.0.0.1:8765/mcp

Configuration

Environment variable	Default	Description
DCC_MCP_MAYA_PORT	8765 direct, 0 plugin	TCP port for the in-process Maya server. Plugin mode uses an OS-assigned instance port by default.
DCC_MCP_MAYA_SERVER_NAME	maya-mcp	Name shown in MCP initialize.
DCC_MCP_MAYA_SKILL_PATHS	none	Extra Maya skill directories (; on Windows, : on Unix).
DCC_MCP_SKILL_PATHS	none	Global fallback skill directories for all DCC adapters.
DCC_MCP_MINIMAL	1	0 loads the full tool surface at startup.
DCC_MCP_DEFAULT_TOOLS	none	Comma-separated skill names to load at startup.
DCC_MCP_MAYA_EXCLUDE_STUBS_FROM_TOOLS_LIST	0	Hide __skill__* / __group__* stubs from large tools/list syncs.
DCC_MCP_MAYA_SIDECAR	1	0 disables the default plugin sidecar process.
DCC_MCP_SERVER_BIN	auto	Override the dcc-mcp-server binary path.
DCC_MCP_GATEWAY_PORT	9765 plugin	Local gateway election port; 0 disables gateway mode.
DCC_MCP_GATEWAY_REMOTE_PORT	59765 sidecar	LAN gateway listener port; 0 disables remote access.
DCC_MCP_GATEWAY_REMOTE_HOST	0.0.0.0	Bind address for the LAN gateway listener.
DCC_MCP_REGISTRY_DIR	OS temp dir	Shared FileRegistry directory for service discovery.
DCC_MCP_MAYA_ENABLE_GATEWAY_FAILOVER	1	Allow non-gateway instances to promote themselves on gateway loss.
DCC_MCP_MAYA_ENABLE_WORKFLOWS	0	Enable core workflow tools.
DCC_MCP_MAYA_PROJECT_TOOLS	1	0 disables project.* MCP tools.
DCC_MCP_MAYA_RESOURCES	1	0 disables MCP resource publishing.
DCC_MCP_MAYA_READINESS_TIMEOUT_SECS	none	Advisory timeout value for readiness consumers.
DCC_MCP_MAYA_METRICS	0	1 enables Prometheus /metrics.
DCC_MCP_MAYA_JOB_STORAGE	<data_dir>/jobs.db	SQLite job persistence path; set "" to disable.
DCC_MCP_MAYA_JOB_RECOVERY	drop	requeue resumes idempotent interrupted jobs.
DCC_MCP_MAYA_HOT_RELOAD	0	1 watches skills for disk changes.
DCC_MCP_MAYA_FAULTHANDLER	1	0 disables fatal-signal traceback logging from the Maya plugin.
DCC_MCP_MAYA_SUPPRESS_CRASH_REPORTER	0	1 suppresses Maya crash reporter dialogs during unattended startup.
DCC_MCP_MAYA_DISABLE_AUTOSAVE	1	0 opts out of the plugin's AutoSave suppression during MCP jobs.
DCC_MCP_MAYA_SAFE_SESSION	1	0 disables the modal-dialog firewall around MCP-dispatched jobs.
DCC_MCP_MAYA_DISABLE_EXECUTE_PYTHON	0	Refuse execute_python.
DCC_MCP_MAYA_DISABLE_EXECUTE_MEL	0	Refuse execute_mel.
DCC_MCP_MAYA_DISABLE_ARBITRARY_SCRIPT	0	Refuse both arbitrary Python and MEL execution.

Authoring Skills

Skill scripts should lazy-import maya.cmds inside the callable so packages can be discovered without a running Maya:

from dcc_mcp_maya.api import maya_success, with_maya


@with_maya
def create_sphere(radius: float = 1.0) -> dict:
    import maya.cmds as cmds

    result = cmds.polySphere(radius=radius)
    return maya_success("Created sphere", object_name=result[0])

Every tools.yaml entry must declare execution mode and thread affinity:

tools:
  - name: playblast
    description: Capture a viewport playblast
    execution: async
    affinity: main
    timeout_hint_secs: 600

  - name: list_export_presets
    execution: sync
    affinity: any

Use affinity: main for anything touching maya.* or scene state. Use affinity: any only for pure Python or filesystem work. CI enforces this with tools/lint_skill_affinity.py.

Long-running loops should poll cancellation:

from dcc_mcp_maya import check_maya_cancelled, maya_success


def render_frames(frames):
    for frame in frames:
        check_maya_cancelled()
        cmds.currentTime(frame)
        cmds.render()
    return maya_success("Rendered frames", frames=len(frames))

Documentation

• Getting started
• Installation
• Local MCP + debug
• Multi-instance deployment
• MCP resources
• Tool inventory
• Shutdown matrix
• API reference

Development

git clone https://github.com/loonghao/dcc-mcp-maya
cd dcc-mcp-maya
pip install -e ".[dev]"
pytest tests/

Common development commands:

just verify-deps
just test-quick
just maya-link
just maya-install-core maya-py=/path/to/mayapy

Windows PowerShell helpers:

just maya-link-win
just maya-install-core-win maya-version=2025
just maya-status-win
just maya-unlink-win

Windows symlinks require Developer Mode or an elevated shell. If symlinks are unavailable, the helper scripts fall back to copying files.

Requirements

• Autodesk Maya 2020+
• Python 3.7+
• dcc-mcp-core>=0.17.15,<1.0.0
• Optional sidecar binary: dcc-mcp-server>=0.17.15

License

MIT - see LICENSE.