usd-mcp

Model Context Protocol (MCP) server for interacting with Pixar USD (Universal Scene Description) files using clean, single-action tools ideal for LLM orchestration.

Features

• Stage management: open/close, list, summarize (stateful) and stateless file helpers.
• File inspection: summarizeFile, listPrimsFile, primInfoFile, getAttrFile.
• Attribute writes: setAttrFile and batch set via setAttrsFile (aliases displayColor→primvars:displayColor, coerces [r,g,b]→[[r,g,b]]).
• Prim authoring: createPrimFile, deletePrimFile.
• Transforms: getXformFile, setXformFile (CommonAPI ops; strips TypeTransform; smart parent/child scaling; gprim size handling).
• Composition: composeReferencedAssembly (one‑shot), addReferencesBatchInFile, setDefaultPrimFile.
• Variants: listVariantsFile, setVariantFile.
• Materials: listMaterialsFile, bindMaterialFile, unbindMaterialFile, getMaterialBindingFile.
• Cameras: listCamerasFile, getCameraFile, setCameraFile.
• Bounds: getBoundsFile (world AABB with fallbacks).
• Export: exportUsdFile (flatten, skipIfExists), exportUsdzFile.
• Ergonomics: camelCase tool aliases; argument normalization (flat JSON, tolerant keys); createStage is open‑or‑create, default upAxis Z.

Docs and guides

• Docs index: Docs Index
• Installation: Installation
• Usage and quickstart: Usage / Quickstart
• Tool contracts (Tier 0): Tier 0 Tools
• Architecture decisions: ADRs
• MCP + Griptape setup: MCP with Griptape
• Sample NL prompts for Griptape: Griptape Prompts
  • Includes new composition flow via composeReferencedAssembly and batch reference helpers.
• Test locally with Inspector: MCP Inspector

Examples

• See examples/ including:
  • minimal_read.py
  • create_stage.py

License

• Apache-2.0. See LICENSE.

Status

• Active development. See Features above for what’s available now.

Quick install

• Create venv, install package, then install USD wheels if available:
  • python -m venv .venv && source .venv/bin/activate
  • pip install -e .
  • pip install "usd-core==25.11"
  • python -c "import pxr, usd_mcp; print('ok')"