Maya MCP Server

# Maya MCP Server [](https://www.npmjs.com/package/maya-mcp-server) [](https://python.org) [](https://autodesk.com/maya) [](LICENSE) 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) ```bash # 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:** ```bash # Use the built-in installer npx maya-mcp-server --install-plugin # or npm run install-plugin ``` **Manual Installation:** ```bash # 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):** ```json { "mcpServers": { "maya": { "command": "npx", "args": ["maya-mcp-server"], "env": {} } } } ``` **Smithery.ai Hosted (10 core tools):** ```json { "mcpServers": { "maya": { "command": "npx", "args": ["@smithery/cli", "run", "@Jeffreytsai1004/maya-mcp"], "env": {} } } } ``` ## Installation ### NPX (Recommended) ```bash # Install and run npx maya-mcp-server # With options npx maya-mcp-server --debug --port 8765 ``` ### Manual Installation ```bash 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: ```yaml host: localhost port: 8765 maya_port: 7022 debug: false log_level: INFO timeout: 30 ``` ### Environment Variables ```bash export MAYA_MCP_HOST=localhost export MAYA_MCP_PORT=8765 export MAYA_MCP_MAYA_PORT=7022 export MAYA_MCP_DEBUG=true ``` ### Command Line Options ```bash 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.) ```json { "object_type": "polyCube", "name": "myCube" } ``` #### maya_select Select objects by name ```json { "objects": ["pCube1", "pSphere1"] } ``` #### maya_transform Transform objects (move, rotate, scale) ```json { "objects": ["pCube1"], "translate": [5, 0, 0], "rotate": [0, 45, 0] } ``` #### maya_delete Delete objects from scene ```json { "objects": ["pCube1", "pSphere1"] } ``` #### maya_execute Execute Python commands in Maya ```json { "command": "import maya.cmds as cmds; cmds.polyCube(name='scriptCube')" } ``` #### maya_get_selection Get currently selected objects ```json {} ``` #### maya_get_scene_info Get detailed scene information ```json { "include_transforms": true, "include_attributes": false } ``` #### maya_get_object_info Get detailed information about specific objects ```json { "object_name": "pCube1", "include_attributes": true } ``` #### maya_list_objects List objects in scene by type ```json { "object_type": "transform", "pattern": "cube*" } ``` ### Console Capture & Debugging Tools (6 tools) #### maya_get_console_output Get Maya console output for debugging ```json { "lines": 50, "include_errors": true } ``` #### maya_enable_console_capture Enable Maya console output capture ```json { "max_lines": 1000 } ``` #### maya_disable_console_capture Disable Maya console output capture ```json {} ``` #### maya_clear_console_buffer Clear Maya console output buffer ```json {} ``` #### maya_set_debug_mode Enable or disable debug mode ```json { "enabled": true } ``` #### maya_get_debug_info Get comprehensive debug information ```json {} ``` ### Advanced Maya Integration (14 tools) #### maya_get_log_file Get Maya log file contents for debugging ```json { "log_type": "output", "lines": 100 } ``` #### maya_browse_outliner Browse Maya outliner hierarchy and DAG structure ```json { "root_node": "|", "depth": 3, "include_shapes": true, "filter_type": "all" } ``` #### maya_get_menu_structure Get Maya main menu structure and available commands ```json { "menu_name": "Create", "include_submenus": true } ``` #### maya_execute_menu_command Execute Maya menu command by name ```json { "command": "polyCube", "arguments": {"name": "menuCube"} } ``` #### maya_get_shelf_tools Get available tools from Maya shelves ```json { "shelf_name": "Polygons" } ``` #### maya_list_plugins List available and loaded Maya plugins ```json { "loaded_only": false, "include_info": true } ``` #### maya_load_plugin Load a Maya plugin by name ```json { "plugin_name": "objExport", "quiet": false } ``` #### maya_unload_plugin Unload a Maya plugin by name ```json { "plugin_name": "objExport", "force": false } ``` #### maya_api_call Direct Maya API function call with OpenMaya ```json { "api_module": "OpenMaya", "function_name": "MGlobal.displayInfo", "arguments": ["Hello from API"], "return_type": "string" } ``` #### maya_execute_mayapy Execute Python script using MayaPy interpreter ```json { "script_content": "import maya.cmds as cmds; print(cmds.ls())", "timeout": 30 } ``` #### maya_get_node_connections Get detailed node connection information ```json { "node_name": "pCube1", "connection_type": "both", "include_attributes": true } ``` #### maya_search_nodes Advanced node search with filters and patterns ```json { "search_pattern": "*cube*", "node_type": "transform", "has_attribute": "visibility" } ``` #### maya_get_workspace_info Get Maya workspace and project information ```json { "include_rules": true } ``` #### maya_set_workspace Set Maya workspace directory ```json { "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: ```python import maya.cmds as cmds cmds.loadPlugin("path/to/maya_mcp.py") ``` ## Development ### Development Mode ```bash python src/server.py --debug ``` ### Debug Mode ```bash 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](docs/INSTALLATION.md)** - Detailed installation instructions for all platforms - **[API Documentation](docs/API.md)** - Complete API reference with examples - **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Solutions for common issues ## Troubleshooting For detailed troubleshooting information, see the [Troubleshooting Guide](docs/TROUBLESHOOTING.md). ### 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](https://www.npmjs.com/package/maya-mcp-server) (v1.0.6) - **GitHub Repository**: [Jeffreytsai1004/maya-mcp](https://github.com/Jeffreytsai1004/maya-mcp) - **Smithery.ai**: [@Jeffreytsai1004/maya-mcp](https://server.smithery.ai/@Jeffreytsai1004/maya-mcp/mcp) ## Support - **Issues**: [Report bugs and request features](https://github.com/Jeffreytsai1004/maya-mcp/issues) - **Discussions**: [Community help](https://github.com/Jeffreytsai1004/maya-mcp/discussions) - **Documentation**: [Installation](docs/INSTALLATION.md) • [API](docs/API.md) • [Troubleshooting](docs/TROUBLESHOOTING.md)