Maya MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to connect to and control Autodesk Maya. Provides 29 tools for 3D modeling, animation, debugging, and Maya API access through the standardized MCP protocol.

🚀 Features

• 🤖 MCP Protocol Integration: Full Model Context Protocol implementation for AI assistants
• 🔗 Maya Command Port: Direct connection via command port (port 7022)
• 📦 NPX Distribution: Install and run with npx maya-mcp-server
• 🔌 Auto-loading Plugin: Maya plugin loads automatically on startup
• 🛠️ 29 Tools: Complete Maya API coverage - creation, selection, transformation, debugging, and more
• 🔒 Security: Command validation and safe execution environment
• 🎯 Multi-version: Maya 2023, 2024, and 2025 support
• 🐛 Debug Tools: Console capture, logging, and development utilities
• ⚙️ Flexible Config: Files, environment variables, or CLI options

🚀 Quick Start

1. Install and Run via NPX (Recommended)

# Start the MCP server
npx maya-mcp-server

# Or with custom configuration
npx maya-mcp-server --host localhost --port 8765 --debug

2. Install Maya Plugin

Automatic Installation:

# Use the built-in installer
npx maya-mcp-server --install-plugin
# or
npm run install-plugin

Manual Installation:

# Windows
copy plug-ins/maya_mcp.py "%USERPROFILE%\Documents\maya\plug-ins\"

# macOS
cp plug-ins/maya_mcp.py ~/Library/Preferences/Autodesk/maya/plug-ins/

# Linux
cp plug-ins/maya_mcp.py ~/maya/plug-ins/

3. Start Maya

Launch Maya (2023-2025 supported). The MCP plugin will automatically load and start listening on port 7022.

Verify Plugin Loading:

• Check Maya's Script Editor for "Maya MCP Plugin loaded successfully"
• Or manually load via Window → Settings/Preferences → Plug-in Manager

4. Connect AI Assistant

Configure your AI assistant to connect to the MCP server:

Local NPX (29 tools):

{
  "mcpServers": {
    "maya": {
      "command": "npx",
      "args": ["maya-mcp-server"],
      "env": {}
    }
  }
}

Smithery.ai Hosted (10 core tools):

{
  "mcpServers": {
    "maya": {
      "command": "npx",
      "args": ["@smithery/cli", "run", "@Jeffreytsai1004/maya-mcp"],
      "env": {}
    }
  }
}

Installation

NPX (Recommended)

# Install and run
npx maya-mcp-server

# With options
npx maya-mcp-server --debug --port 8765

Manual Installation

git clone https://github.com/Jeffreytsai1004/maya-mcp.git
cd maya-mcp
pip install -r requirements.txt
python src/server.py

Configuration

Configuration File

Create a config.yaml file:

host: localhost
port: 8765
maya_port: 7022
debug: false
log_level: INFO
timeout: 30

Environment Variables

export MAYA_MCP_HOST=localhost
export MAYA_MCP_PORT=8765
export MAYA_MCP_MAYA_PORT=7022
export MAYA_MCP_DEBUG=true

Command Line Options

python src/server.py --host localhost --port 8765 --debug

Available Tools (29 Total)

Core Maya Operations (9 tools)

maya_create

Create Maya objects (cubes, spheres, etc.)

{
  "object_type": "polyCube",
  "name": "myCube"
}

maya_select

Select objects by name

{
  "objects": ["pCube1", "pSphere1"]
}

maya_transform

Transform objects (move, rotate, scale)

{
  "objects": ["pCube1"],
  "translate": [5, 0, 0],
  "rotate": [0, 45, 0]
}

maya_delete

Delete objects from scene

{
  "objects": ["pCube1", "pSphere1"]
}

maya_execute

Execute Python commands in Maya

{
  "command": "import maya.cmds as cmds; cmds.polyCube(name='scriptCube')"
}

maya_get_selection

Get currently selected objects

{}

maya_get_scene_info

Get detailed scene information

{
  "include_transforms": true,
  "include_attributes": false
}

maya_get_object_info

Get detailed information about specific objects

{
  "object_name": "pCube1",
  "include_attributes": true
}

maya_list_objects

List objects in scene by type

{
  "object_type": "transform",
  "pattern": "cube*"
}

Console Capture & Debugging Tools (6 tools)

maya_get_console_output

Get Maya console output for debugging

{
  "lines": 50,
  "include_errors": true
}

maya_enable_console_capture

Enable Maya console output capture

{
  "max_lines": 1000
}

maya_disable_console_capture

Disable Maya console output capture

{}

maya_clear_console_buffer

Clear Maya console output buffer

{}

maya_set_debug_mode

Enable or disable debug mode

{
  "enabled": true
}

maya_get_debug_info

Get comprehensive debug information

{}

Advanced Maya Integration (14 tools)

maya_get_log_file

Get Maya log file contents for debugging

{
  "log_type": "output",
  "lines": 100
}

maya_browse_outliner

Browse Maya outliner hierarchy and DAG structure

{
  "root_node": "|",
  "depth": 3,
  "include_shapes": true,
  "filter_type": "all"
}

maya_get_menu_structure

Get Maya main menu structure and available commands

{
  "menu_name": "Create",
  "include_submenus": true
}

maya_execute_menu_command

Execute Maya menu command by name

{
  "command": "polyCube",
  "arguments": {"name": "menuCube"}
}

maya_get_shelf_tools

Get available tools from Maya shelves

{
  "shelf_name": "Polygons"
}

maya_list_plugins

List available and loaded Maya plugins

{
  "loaded_only": false,
  "include_info": true
}

maya_load_plugin

Load a Maya plugin by name

{
  "plugin_name": "objExport",
  "quiet": false
}

maya_unload_plugin

Unload a Maya plugin by name

{
  "plugin_name": "objExport",
  "force": false
}

maya_api_call

Direct Maya API function call with OpenMaya

{
  "api_module": "OpenMaya",
  "function_name": "MGlobal.displayInfo",
  "arguments": ["Hello from API"],
  "return_type": "string"
}

maya_execute_mayapy

Execute Python script using MayaPy interpreter

{
  "script_content": "import maya.cmds as cmds; print(cmds.ls())",
  "timeout": 30
}

maya_get_node_connections

Get detailed node connection information

{
  "node_name": "pCube1",
  "connection_type": "both",
  "include_attributes": true
}

maya_search_nodes

Advanced node search with filters and patterns

{
  "search_pattern": "*cube*",
  "node_type": "transform",
  "has_attribute": "visibility"
}

maya_get_workspace_info

Get Maya workspace and project information

{
  "include_rules": true
}

maya_set_workspace

Set Maya workspace directory

{
  "workspace_path": "/path/to/project",
  "create_if_missing": false
}

Maya Plugin

The Maya plugin (plug-ins/maya_mcp.py) provides:

• Automatic loading when Maya starts
• Command port server on port 7022
• Safe Python command execution
• Scene state management
• Error handling and logging

Manual Plugin Loading

If the plugin doesn't auto-load:

import maya.cmds as cmds
cmds.loadPlugin("path/to/maya_mcp.py")

Development

Development Mode

python src/server.py --debug

Debug Mode

python src/server.py --debug

Hot Reload

The server supports hot reloading of configuration and scripts without restart.

Supported Maya Versions

• Maya 2023
• Maya 2024
• Maya 2025

Requirements

• Python 3.8+
• Autodesk Maya 2023-2025
• MCP SDK
• aiohttp
• websockets

Security

The server includes security measures:

• Command validation and filtering
• Blocked dangerous operations
• Safe Python execution environment
• Connection authentication (optional)

Documentation

• Installation Guide - Detailed installation instructions for all platforms
• API Documentation - Complete API reference with examples
• Troubleshooting Guide - Solutions for common issues

Troubleshooting

For detailed troubleshooting information, see the Troubleshooting Guide.

Quick Fixes

• Maya Not Connecting: Ensure Maya is running and plugin is loaded
• Plugin Not Loading: Check plugin directory and Maya version compatibility
• Port Issues: Try alternative ports (7023, 7024, etc.)
• Server Won't Start: Verify Python 3.8+ and install dependencies

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test your changes
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

v1.0.6 (Latest)

• ✅ WebSocket Compatibility: Fixed Python 3.14 compatibility issues
• ✅ Version Synchronization: Unified all version numbers across files
• ✅ Connection Stability: Improved Maya connection reliability
• ✅ Documentation: Updated all documentation with latest information

v1.0.5

• 🔧 Version number fixes and NPM package updates

v1.0.4

• 🐛 WebSocket timeout parameter compatibility fixes

v1.0.3

• 📝 Documentation improvements and bug fixes

Links

• NPM Package: maya-mcp-server (v1.0.6)
• GitHub Repository: Jeffreytsai1004/maya-mcp
• Smithery.ai: @Jeffreytsai1004/maya-mcp

Support

• Issues: Report bugs and request features
• Discussions: Community help
• Documentation: Installation • API • Troubleshooting