Maya MCP Server

Connect Claude AI to Autodesk Maya through Model Context Protocol

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Français | Deutsch | Русский

---

Overview

Maya MCP Server enables Claude AI to directly control Autodesk Maya through the Model Context Protocol, enabling:

• 🎨 AI-assisted 3D modeling
• 🤖 Natural language Maya control
• 📸 Real-time scene preview
• 🔧 Workflow automation

Quick Start

1. Install Dependencies

pip install "mcp[cli]>=1.3.0"

2. Load Maya Plugin

Load plug-ins/maya_mcp.py in Maya's Plug-in Manager:

1. Copy plug-ins/maya_mcp.py to:

   • Windows: C:\Users\<username>\Documents\maya\<version>\plug-ins\
   • macOS: ~/maya/<version>/plug-ins/

2. Open Maya → Windows > Settings/Preferences > Plug-in Manager

3. Find maya_mcp.py, check Loaded and Auto load

4. Verify in Script Editor:

   MayaMCP: Plugin loaded successfully
   MayaMCP: Server started at localhost:9877
   

3. Configure Claude Desktop

Edit config file (Settings > Developer > Edit Config):

Option A: Using npx (Recommended)

Standard Configuration:

{
  "mcpServers": {
    "maya-mcp": {
      "command": "npx",
      "args": [
        "--yes",
        "maya-mcp-server"
      ],
      "env": {
        "MAYA_HOST": "localhost",
        "MAYA_PORT": "9877"
      },
      "alwaysAllow": [
          "get_scene_info",
          "get_object_info",
          "create_primitive",
          "delete_object",
          "set_material",
          "transform_object",
          "smart_select",
          "get_scene_summary",
          "get_console_output",
          "execute_maya_code"
      ]
    }
  }
}

Force Update Configuration (always pull latest package):

{
  "mcpServers": {
    "maya-mcp": {
      "command": "npx",
      "args": [
        "--yes",
        "--no-cache",
        "maya-mcp-server"
      ],
      "env": {
        "MAYA_HOST": "localhost",
        "MAYA_PORT": "9877"
      },
      "alwaysAllow": [
          "get_scene_info",
          "get_object_info",
          "create_primitive",
          "delete_object",
          "set_material",
          "transform_object",
          "smart_select",
          "get_scene_summary",
          "get_console_output",
          "execute_maya_code"
      ]
    }
  }
}

Option B: Using Python

{
  "mcpServers": {
    "maya-mcp": {
      "command": "python",
      "args": ["-m", "maya_mcp.server"],
      "env": {
        "PYTHONPATH": "YOUR_PROJECT_PATH/src",
        "MAYA_HOST": "localhost",
        "MAYA_PORT": "9877"
      },
      "alwaysAllow": [
          "get_scene_info",
          "create_primitive",
          "delete_object",
          "set_material",
          "transform_object",
          "smart_select",
          "get_scene_summary",
          "get_console_output",
          "execute_maya_code"
      ]
    }
  }
}

💡 More configuration options in examples/

4. Test Connection

Restart Claude Desktop, then ask:

Get current Maya scene information

If you see scene info returned, it's working! ✅

Features

🛠️ Core Tools

Tool	Function
get_scene_info	Get scene information (objects, cameras, lights)
get_object_info	Get object details (position, rotation, material)
create_primitive	Create geometry (cube/sphere/cylinder/plane/torus)
delete_object	Delete objects
transform_object	Transform objects (move/rotate/scale)
set_material	Set materials and colors
execute_maya_code	Execute Python code
smart_select	Smart object selection with regex and filters
get_scene_summary	Get comprehensive scene summary
get_console_output	Get Maya console/script editor output 🆕

💬 Example Conversations

User: Create a red cube at position (0, 5, 0)

Claude: 
1. Created cube
2. Moved to specified position
3. Applied red material
✅ Done

User: Create a simple table and chair scene

Claude:
1. Created table top (scaled cube)
2. Created 4 table legs (cylinders)
3. Created chair
4. Set materials
✅ Scene created successfully

Usage Examples

Basic Operations

# Scene queries
"Show all objects in the current scene"
"Get detailed info for pCube1"
"Get console output to see recent Maya logs"

# Create objects
"Create a sphere named mySphere"
"Create 10 cubes in a row"

# Modify objects
"Move pCube1 to (5, 0, 0)"
"Set pSphere1 to blue"
"Rotate pCylinder1 45 degrees on Y axis"

# Smart selection
"Select all objects with 'character' in their name"
"Find all meshes with more than 5000 faces"

Advanced Operations

# Procedural modeling
"Execute code to create a 5x5 cube grid"

# Vertex/Face editing
"Create a plane and edit vertices to make a terrain"
"Extrude faces to create details"

# UV editing
"Apply automatic UV projection to selected objects"
"Create spherical UV mapping for the sphere"

# Animation
"Create keyframe animation for bouncing ball"
"Set up 3-point lighting system"

# Rigging
"Create a spine bone chain with 5 joints"
"Set up parent constraints"

# Dynamics
"Create particle system with gravity"
"Apply bend deformer to plane"

# Boolean operations
"Subtract cube2 from cube1"
"Union two overlapping spheres"

# Batch operations
"Set all spheres to random colors"

# Complex scenes
"Create a simple interior scene with floor, walls, and furniture"

Configuration Options

Environment Variables

Variable	Default	Description
MAYA_HOST	localhost	Maya server address
MAYA_PORT	9877	Maya server port
PYTHONPATH	-	Python module search path (Python direct mode only)

Custom Port

In Maya plugin:

start_maya_mcp_server(host='localhost', port=9878)

In config file:

"env": {
  "MAYA_PORT": "9878"
}

Troubleshooting

Connection Failed

Issue: "Cannot connect to Maya"

Solutions:

1. ✅ Verify Maya is running
2. ✅ Confirm plugin is loaded (check Plug-in Manager)
3. ✅ Check Script Editor for startup messages
4. ✅ Ensure port 9877 is not in use

Module Not Found

Issue: "ModuleNotFoundError: No module named 'maya_mcp'"

Solutions:

1. Install dependencies: pip install "mcp[cli]>=1.3.0"
2. Check PYTHONPATH setting (if using Python direct mode)
3. Try using npx method instead

NPX Configuration Issues

Issue: npx fails to start the server or can't find files

Solutions:

1. Use absolute paths in configuration (not relative paths)
2. Use forward slashes / in Windows paths
3. Verify project structure is intact
4. See detailed guide: NPX_TROUBLESHOOTING.md

Plugin Load Failed

Issue: Maya reports "No initializePlugin() function"

Solutions:

• Ensure using latest version of maya_mcp.py
• Plugin file contains initializePlugin() and uninitializePlugin() functions

Security Notes

⚠️ Important:

• execute_maya_code tool allows execution of arbitrary Python code
• Always save Maya scene before executing
• Use with caution in production environments
• Test operations in a test scene first

Logs

Server logs are saved at:

• Windows: %TEMP%\maya-mcp\maya-mcp.log
• macOS/Linux: /tmp/maya-mcp/maya-mcp.log

Check logs to debug connection issues or command execution errors.

Development

Adding New Tools

1. Add command handler in plug-ins/maya_mcp.py
2. Add MCP tool definition in src/maya_mcp/server.py
3. Test new tool

Run Development Server

# Set environment
export PYTHONPATH=/path/to/maya-mcp-server/src

# Run server
python -m maya_mcp.server

Contributing

Contributions welcome! See CONTRIBUTING.md

Acknowledgments

Inspired by:

• Blender-MCP - Architecture reference

License

MIT License

Disclaimer

This is a third-party project, not an official Autodesk product.

---

<div align="center">

Get Started • Configuration Guide • Report Issues

Made with ❤️ for Maya artists and AI enthusiasts

</div>