maya-mcp

Control Autodesk Maya with natural language using Claude and the Model Context Protocol (MCP)

📊 Code knowledge graph

Interactive, auto-published map of this codebase — modules, functions, call/import edges and community clusters — rebuilt by graphify and deployed to GitHub Pages on every push to src/:

abrahamadsk.github.io/maya-mcp · part of the MCP ecosystem graph hub.

MCP server for Autodesk Maya — 17 MCP tools with RAG-powered documentation search, anti-hallucination safety, self-learning patterns, and optional AI-driven 3D generation via the Vision3D addon.

Related MCP server: Maya MCP

Features

Production Maya Operations

Beyond primitives, maya-mcp handles real production tasks: polygon modeling (extrude, bevel, boolean, combine, smooth), animation keyframing with tangent control, multi-format I/O (OBJ, FBX, GLTF, Alembic, USD, MA/MB), viewport capture/playblast, full scene snapshots, and shelf button creation. All operations use undo chunks for safe rollback.

AI-Powered 3D Generation (optional addon)

Optionally integrates with Vision3D for image-to-3D and text-to-3D generation. Non-blocking async workflow: submit job → poll status → download results → import into Maya. Runs on a remote GPU server so your local machine stays responsive. Vision3D is not required — maya-mcp works fully without it.

Embedded Maya Console Panel

A dockable Qt panel that lives inside Maya as a workspaceControl tab (next to the Attribute Editor). Provides a chat interface to Claude with live Maya context (scene name, object count, selection, renderer). Installs automatically — the first time Claude connects to Maya (via maya_ping or maya_launch), the MCP Pipeline menu and panel are injected into the running Maya session. No manual userSetup.py editing required. The panel persists across Maya sessions — if left open, it auto-restores on next launch. Uses PySide2 (Maya 2023–2024) or PySide6 (Maya 2025+) automatically via a compatibility shim. All MCP servers (maya-mcp, fpt-mcp, flame-mcp) are accessible from the panel through Claude Code CLI.

Cross-MCP Orchestration

Works alongside fpt-mcp (ShotGrid/Flow Production Tracking) and flame-mcp (Autodesk Flame). Each DCC has its own embedded console, and all consoles access all MCP servers via Claude Code CLI. When multiple servers are configured, Claude can orchestrate end-to-end VFX workflows across applications. Consistent architecture across all three servers.

Review & Colour Management

Review previews are colour-correct and deterministic. The Viewport 2.0 capture paths (review_turntable, maya_viewport_capture) pin the colour-management view transform before the playblast and restore it after, so a version preview matches the viewport instead of riding the session's current view. The view is configurable (config.json → review_view_transform, default Un-tone-mapped (sRGB) — the view of Maya's built-in default OCIO config). For Arnold file renders, color_policy.py (and docs/ARNOLD_API.md) provide a preview-vs-EXR policy: bake the output transform for an 8-bit preview, but force the driver to Raw for scene-linear EXRs — the guardrail that keeps a display transform out of the EXRs the comp/Flame stage consumes.

Architecture

Claude / LLM
    ↕  MCP protocol (stdio)
FastMCP server (src/maya_mcp/server.py) — 17 MCP tools
    ├── RAG engine (src/maya_mcp/rag/)
    │     ├── ChromaDB + BM25 hybrid search
    │     ├── HyDE adaptive query expansion
    │     └── In-session cache + RRF fusion
    ├── Safety module (src/maya_mcp/safety.py)
    │     └── 14+ dangerous pattern detectors
    ├── Maya bridge (src/maya_mcp/maya_bridge.py)
    │     └── TCP socket → Command Port :8100
    └── Vision3D client (HTTP)
          └── GPU server for 3D generation

Tools (17 MCP tools)

Maya Direct Tools (10 tools)

Dispatcher Tools (3 tools)

RAG & Intelligence (4 tools)

Maya Session Dispatcher (maya_session — 12 actions)

Vision3D Dispatcher (maya_vision3d — 7 actions, optional, requires Vision3D)

Skills (3)

Tools are what the server can do. Skills are the recipe — which tools, in what order, and what fails silently. They live in docs/skills/, version controlled with the code they describe, and load only when the request matches their trigger, so they cost almost nothing until they are relevant.

Activate them on a fresh clone by symlinking into your user skills directory:

for s in maya-headless-batch maya-scene-assembly maya-anim-transfer; do
  ln -s "$PWD/docs/skills/$s" ~/.claude/skills/"$s"
done

See docs/skills/README.md for the four-layer split (tool / skill / RAG / memory) and why they are not under .claude/.

RAG — Knowledge Engine

Architecture

LLMs hallucinate Maya API details constantly — wrong flag names (width= instead of w=), nonexistent commands (cmds.usdExport instead of cmds.mayaUSDExport), incorrect return types. maya-mcp includes a hybrid RAG engine (ChromaDB semantic + BM25 lexical, fused via Reciprocal Rank Fusion) with 5 curated documentation corpora covering maya.cmds, PyMEL, Arnold/mtoa, Maya-USD, and a comprehensive anti-patterns database. The LLM calls search_maya_docs before writing any unfamiliar code, getting verified syntax with relevance scores.

HyDE Query Expansion

Short queries like "set keyframe tangent" don't match code-heavy documentation well. maya-mcp uses Hypothetical Document Embedding (HyDE) — it detects which Maya API domain the query targets (cmds, PyMEL, Arnold, USD, MEL) and wraps the query in a domain-specific code template before embedding. This bridges the gap between natural-language questions and code documentation.

Dangerous Pattern Detection

Before any code reaches Maya, the safety module scans for 14+ dangerous patterns: bulk deletes without filters, undo system tampering, filesystem operations on scene files, plugin deregistration with active nodes, namespace deletions, referenced geometry modification, and more. Each pattern includes an explanation of WHY it is dangerous and a SAFE alternative.

Self-Learning

When the RAG returns low-relevance results (< 60%) but the operation succeeds, the LLM can call learn_pattern to save the working pattern for future sessions. Model trust gates ensure only Opus/Fable can write directly to docs — other models stage candidates for human review. Knowledge grows over time without manual curation.

Token Tracking

Every tool call tracks tokens in/out. The session_stats tool reports how much context was saved by RAG vs loading full documentation, making the efficiency gains measurable and visible.

Project Structure

maya-mcp/
├── src/
│   └── maya_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py              # FastMCP server — 17 MCP tools
│       ├── maya_bridge.py         # TCP bridge → Maya Command Port :8100
│       ├── safety.py              # Dangerous pattern detection (14+ patterns)
│       ├── config.example.json
│       ├── rag/
│       │   ├── config.py          # Embedding model, search params, token tracking
│       │   ├── build_index.py     # Chunk docs → ChromaDB + BM25 corpus
│       │   ├── search.py          # Hybrid search: BM25 + semantic + HyDE + RRF
│       │   ├── index/             # ChromaDB persistent index (auto-generated)
│       │   └── corpus.json        # BM25 corpus (auto-generated)
│       └── docs/
│           ├── CMDS_API.md        # maya.cmds reference (commands, flags, patterns)
│           ├── PYMEL_API.md       # PyMEL object-oriented API reference
│           ├── ARNOLD_API.md      # Arnold/mtoa shaders, AOVs, render settings
│           ├── USD_API.md         # Maya-USD import/export, proxy shapes, pxr API
│           └── ANTI_PATTERNS.md   # Common LLM hallucinations + wrong flag names
├── docs/
│   └── skills/                    # Claude Code skills (symlinked into ~/.claude/skills/)
│       ├── maya-headless-batch/   # mayapy/kick out-of-process work + runner template
│       ├── maya-scene-assembly/   # references, namespaces, version swaps
│       └── maya-anim-transfer/    # HumanIK retarget, cycles, reach semantics
│
├── console/                    # Qt console — Maya panel + legacy standalone
│   ├── qt_compat.py            # PySide2 (Maya 2023-2024) / PySide6 (2025+) shim
│   ├── maya_panel.py           # Dockable workspaceControl panel for Maya
│   ├── chat_widget.py          # Reusable MCPChatWidget (shared by panel & standalone)
│   ├── claude_worker.py        # QThread worker — Claude CLI subprocess bridge
│   ├── server_panel.py         # MCP server discovery, health checks, ServerStatusBar
│   ├── userSetup_snippet.py    # Paste into Maya's userSetup.py for auto-setup
│   ├── app.py                  # Legacy standalone entry point (use fpt-mcp console)
│   ├── chat_window.py          # Legacy standalone chat window
│   └── build_app_bundle.py     # Legacy macOS .app bundle generator
│
├── tests/
├── pyproject.toml              # Build config, entry point: python -m maya_mcp.server
├── reference/                  # Pipeline I/O (git-ignored)
├── CLAUDE.md                   # Project documentation for Claude
├── WORKFLOW_GUIDE.md           # Workflow guide
├── .env.example                # Configuration template
└── README.md

Requirements

• macOS

• Autodesk Maya 2023 or later

• Python 3.13 or higher (ships with Maya 2027)

• Node.js v22 or higher (required by Claude Code)

• Claude Code 2.x

• A Claude account — Pro, Max, or API key

Optional

• Ollama >= 0.17.6 — for local / free inference instead of Anthropic cloud

  • macOS: brew install ollama && brew services start ollama

  • Linux: https://ollama.com/download/linux (systemd)

  • Verify: ollama --version

  • Create the qwen3.5-mcp model (required for Ollama backends):

    ollama pull qwen3.5:9b
    cat > /tmp/Modelfile.qwen35mcp <<'EOF'
    FROM qwen3.5:9b
    PARAMETER num_ctx 16384
    PARAMETER temperature 0.7
    PARAMETER top_p 0.8
    PARAMETER top_k 20
    EOF
    ollama create qwen3.5-mcp -f /tmp/Modelfile.qwen35mcp

  • See MODEL_STRATEGY.md for the full rationale (num_ctx bump, think: false requirement, KEEP_ALIVE tuning, KV-cache dtype)

• Vision3D server for AI-powered 3D generation

Installation

Automatic Installation

git clone https://github.com/abrahamADSK/maya-mcp.git
cd maya-mcp
chmod +x install.sh
./install.sh

The installer creates a virtual environment, installs dependencies, builds the RAG index, and registers the MCP server with Claude Code.

1. Clone and configure

git clone https://github.com/abrahamADSK/maya-mcp.git
cd maya-mcp
cp .env.example .env
# Optional: set GPU_API_URL as a *suggested default* for Vision3D.
# It is never auto-selected — Claude will surface it when asking you
# which Vision3D URL to use, and you have to confirm it explicitly.
# Example: GPU_API_URL=http://<your-gpu-host>:8000

2. Install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# RAG dependencies (optional but recommended)
pip install chromadb sentence-transformers rank-bm25

3. Build the RAG index

python -m maya_mcp.rag.build_index

First run downloads the embedding model (~570 MB, cached afterwards). The index is stored in src/maya_mcp/rag/index/ and can be committed to git.

4. Set up Maya Command Port — automatic

install.sh does this for you. Step 7 of the installer detects every Maya version installed on the host, locates each version's user scripts dir, and writes an idempotent guarded block into userSetup.py that:

• Adds the maya-mcp repo root to sys.path

• Opens the Command Port on MAYA_PORT (from .env, default 8100) bound to localhost using sourceType='mel' with the name= kwarg form (the localhost bind keeps the port reachable only from this host — an all-interfaces bind would expose an unauthenticated arbitrary-code-execution port to the LAN; Maya 2027 also silently ignores the positional form when sourceType is specified)

• Registers the MCP Pipeline menu via executeDeferred

The block is bounded by sentinel markers and reruns of install.sh are safe — the installer replaces the whole region when the markers are found.

Run ./install.sh --doctor after install to verify userSetup.py was written for every detected version (plus 4 other install-completeness checks).

Port 8100 default rationale: maya-mcp historically used port 7001, the Maya commandPort convention. On hosts with Autodesk Flame installed, port 7001 is already held by Flame's S+W Service Discovery and S+W Probe Server, and connections silently succeed against Flame instead of Maya — producing empty responses that the bridge (prior to v1.4.2) misinterpreted as successful no-ops. The default was moved to 8100 to coexist with Flame. Override via MAYA_PORT in .env if your environment still uses 7001.

The MCP Pipeline Console panel installs itself automatically. The first time Claude connects to Maya (via maya_ping or maya_launch), the server injects the panel menu and UI through the Command Port. The panel docks next to the Attribute Editor and persists across sessions.

Add to your Maya userSetup.py:

• Windows: %USERPROFILE%/Documents/maya/<version>/scripts/userSetup.py

• macOS: ~/Library/Preferences/Autodesk/maya/<version>/scripts/userSetup.py

• Linux: ~/maya/<version>/scripts/userSetup.py

# --- MCP Pipeline Console auto-setup ---
import sys as _mcp_sys

_mcp_root = r"/path/to/maya-mcp"  # replace with your clone path
if _mcp_root not in _mcp_sys.path:
    _mcp_sys.path.insert(0, _mcp_root)

import maya.utils as _mcp_utils


def _mcp_open_command_port():
    try:
        import maya.cmds as _mc
        # Bind to localhost: an all-interfaces (":8100") bind exposes an
        # unauthenticated arbitrary-code-execution port to the whole LAN.
        if not _mc.commandPort("localhost:8100", query=True):
            _mc.commandPort(name="localhost:8100", sourceType="mel")
    except Exception:
        pass


def _mcp_menu_startup():
    try:
        from console.maya_panel import install_menu
        import maya.cmds as _mc
        if not _mc.menu("mcpPipelineMenu", exists=True):
            install_menu()
    except Exception:
        pass


_mcp_utils.executeDeferred(_mcp_open_command_port)
_mcp_utils.executeDeferred(_mcp_menu_startup)
# --- end MCP Pipeline Console ---

5. Configure Claude Code

claude mcp add maya-mcp -s user -- /path/to/maya-mcp/.venv/bin/python -m maya_mcp.server

Or for Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "maya-mcp": {
      "command": "/path/to/maya-mcp/.venv/bin/python",
      "args": ["-m", "maya_mcp.server"],
      "cwd": "/path/to/maya-mcp",
      "env": {
        "GPU_API_URL": "http://your-gpu-host:8000",
        "GPU_API_KEY": "your-api-key-here"
      }
    }
  }
}

6. Vision3D addon (optional — for AI 3D generation)

maya-mcp can optionally integrate with Vision3D for image-to-3D and text-to-3D generation. This is not required for core Maya functionality.

Vision3D URL is never stored. maya-mcp does not hold any Vision3D endpoint in config files, environment presets, or hardcoded defaults. On the first Vision3D call of each MCP session:

1. The dispatch returns vision3d_url_required.

2. Claude asks you in the chat which Vision3D URL to use.

3. You type the URL (e.g. a local Mac MPS instance or a remote CUDA host).

4. Claude calls maya_vision3d(action="select_server", params={"url": "<the-url>"}).

5. The URL is cached in the MCP process memory until restart and used for every subsequent call of the session.

You can switch servers mid-session by calling select_server again with a different URL. No restart required.

Suggested default via GPU_API_URL — if the environment variable GPU_API_URL is set, Claude surfaces it to you as a suggested default when asking for the URL. You still have to confirm or override it explicitly; it is never auto-selected. This is the only escape hatch for pre-selector installs. GPU_API_KEY is only needed if your Vision3D server has an API key configured.

Usage

Once installed, maya-mcp is available through Claude Code or any MCP-compatible client. Open Maya, ensure the Command Port is running, and start a conversation:

You: "Create a 2x2 grid of spheres with 0.5 unit spacing"
Claude → maya_create_primitive (sphere) × 4 → maya_transform (position each) → Result

You: "Generate a 3D model from this reference image and import it"
Claude → maya_vision3d(action='generate_image', ...) → maya_vision3d(action='poll', ...) → maya_vision3d(action='download', ...) → maya_import_file → Result

All operations go through the safety scanner before reaching Maya. Dangerous patterns are blocked with an explanation and a safe alternative.

Configuration Reference

config.json (not env vars) also accepts, besides backend/model/Ollama settings:

Audit Log (opt-in)

A durable, append-only record of what the model executed in Maya, and what happened — for accountability and forensics, separate from the logs/timings.jsonl efficiency telemetry.

• Off by default. It only writes when MAYA_AUDIT_LOG is set to a truthy value (1/true/yes/on). When unset there is zero perf, disk, or privacy impact and no behaviour change.

• What it records. One JSON line per call to src/maya_mcp/logs/audit.jsonl: ts, tool, action, sanitised params, status (ok / error / safety_blocked / ast_rejected), plus model/backend. It covers execute_python, the dedicated mutation tools, the mutating maya_session actions, and blocked attempts (safety scan / AST dry-run rejections). Read-only actions (ping, list_scene, scene_snapshot) are excluded.

• Size & privacy. For execute_python the code is stored truncated to ~2000 chars plus a SHA-256 of the full code and its length; Maya result payloads are never stored. The file rotates at 5 MB to audit.jsonl.1 (one rollover) and lives under the git-ignored logs/ dir.

• Write-only. There is no MCP tool to read it (the tool count is unchanged). Inspect it with jq/grep, e.g. jq 'select(.status=="safety_blocked")' src/maya_mcp/logs/audit.jsonl.

Cross-MCP Pipeline

When both maya-mcp and fpt-mcp are configured, Claude can orchestrate end-to-end VFX workflows: query ShotGrid for an asset → download reference image → generate 3D via Vision3D → import into Maya → register the publish back in ShotGrid. All from one conversation.

All three MCP servers (maya-mcp, fpt-mcp, flame-mcp) share the same architecture: hybrid RAG, HyDE, safety layer, self-learning, token tracking, and model trust gates.

Troubleshooting

Maya Command Port not responding — Verify in Maya's Script Editor: cmds.commandPort('localhost:8100', query=True). If False, run the open_command_port() snippet.

RAG search returns "index not found" — Run python -m maya_mcp.rag.build_index to build the index.

Shape inference fails immediately — Model weights may be incomplete. Check that hunyuan3d-dit-v2-0-turbo/model.fp16.safetensors (~4.6 GB) exists on the GPU server.

GPU API connection refused — Verify Vision3D is running: curl $GPU_API_URL/api/health.

Ecosystem

maya-mcp is part of a four-component VFX pipeline. Each component has a defined role:

maya-mcp sits at the 3D creation stage of the pipeline. It consumes vision3d via HTTP — submitting image-to-3D or text-to-3D jobs and importing the resulting .glb files into Maya. It works alongside fpt-mcp for end-to-end workflows: query ShotGrid for an asset, generate or load reference, build the 3D asset in Maya, and register the publish back in ShotGrid. flame-mcp typically operates downstream, receiving rendered outputs from Maya for finishing.

License

MIT License — see LICENSE for details.