Maya MCP Server

# Maya MCP Server API Documentation ## Overview Maya MCP Server v1.0.6 provides 29 tools for interacting with Autodesk Maya through the Model Context Protocol. All tools follow the MCP specification and return structured responses. **Tool Categories:** - **Core Operations (9)**: Object creation, selection, transformation, deletion, execution - **Console & Debugging (6)**: Output capture, debug mode, console management - **Advanced Integration (14)**: Outliner browsing, plugin management, Maya API access **Latest Version**: 1.0.6 - Includes WebSocket compatibility fixes and unified version numbering ## Tool Reference ### 1. maya_create Create Maya objects (primitives, curves, etc.) **Input Schema:** ```json { "type": "object", "properties": { "object_type": { "type": "string", "enum": ["polyCube", "sphere", "cylinder", "plane", "cone", "torus"], "description": "Type of Maya object to create" }, "name": { "type": "string", "description": "Optional name for the created object" }, "transform": { "type": "object", "properties": { "translate": {"type": "array", "items": {"type": "number"}, "minItems": 3, "maxItems": 3}, "rotate": {"type": "array", "items": {"type": "number"}, "minItems": 3, "maxItems": 3}, "scale": {"type": "array", "items": {"type": "number"}, "minItems": 3, "maxItems": 3} }, "description": "Optional transform values" } }, "required": ["object_type"] } ``` **Example Request:** ```json { "object_type": "polyCube", "name": "myCube", "transform": { "translate": [0, 5, 0], "scale": [2, 2, 2] } } ``` **Example Response:** ```json { "success": true, "result": "Created polyCube: myCube", "error": null } ``` ### 2. maya_select Select objects in the Maya scene by name. **Input Schema:** ```json { "type": "object", "properties": { "objects": { "type": "array", "items": {"type": "string"}, "description": "List of object names to select" }, "add": { "type": "boolean", "default": false, "description": "Add to current selection instead of replacing" } }, "required": ["objects"] } ``` **Example Request:** ```json { "objects": ["pCube1", "pSphere1"], "add": false } ``` **Example Response:** ```json { "success": true, "result": "Selected objects: ['pCube1', 'pSphere1']", "error": null } ``` ### 3. maya_transform Transform objects (move, rotate, scale). **Input Schema:** ```json { "type": "object", "properties": { "objects": { "type": "array", "items": {"type": "string"}, "description": "List of objects to transform" }, "translate": { "type": "array", "items": {"type": "number"}, "minItems": 3, "maxItems": 3, "description": "Translation values [x, y, z]" }, "rotate": { "type": "array", "items": {"type": "number"}, "minItems": 3, "maxItems": 3, "description": "Rotation values [x, y, z] in degrees" }, "scale": { "type": "array", "items": {"type": "number"}, "minItems": 3, "maxItems": 3, "description": "Scale values [x, y, z]" }, "absolute": { "type": "boolean", "default": false, "description": "Use absolute values instead of relative" } }, "required": ["objects"] } ``` **Example Request:** ```json { "objects": ["pCube1"], "translate": [5, 0, 0], "rotate": [0, 45, 0], "absolute": true } ``` ### 4. maya_delete Delete objects from the Maya scene. **Input Schema:** ```json { "type": "object", "properties": { "objects": { "type": "array", "items": {"type": "string"}, "description": "List of object names to delete" } }, "required": ["objects"] } ``` **Example Request:** ```json { "objects": ["pCube1", "pSphere1"] } ``` ### 5. maya_execute Execute arbitrary Python code in Maya's environment. **Input Schema:** ```json { "type": "object", "properties": { "command": { "type": "string", "description": "Python code to execute in Maya" }, "safe_mode": { "type": "boolean", "default": true, "description": "Enable safety checks to prevent dangerous operations" } }, "required": ["command"] } ``` **Example Request:** ```json { "command": "import maya.cmds as cmds; result = cmds.ls(selection=True); print(f'Selected: {result}')", "safe_mode": true } ``` **Security Note:** When `safe_mode` is enabled (default), the following operations are blocked: - File system operations (`open`, `file`) - System commands (`subprocess`, `system`) - Code execution (`exec`, `eval`, `compile`) - Module imports outside Maya's safe modules ### 6. maya_get_selection Get the currently selected objects in Maya. **Input Schema:** ```json { "type": "object", "properties": { "long_names": { "type": "boolean", "default": false, "description": "Return full DAG paths instead of short names" } } } ``` **Example Response:** ```json { "success": true, "result": ["pCube1", "pSphere1"], "error": null } ``` ### 7. maya_get_scene_info Get comprehensive information about the current Maya scene. **Input Schema:** ```json { "type": "object", "properties": { "include_transforms": { "type": "boolean", "default": true, "description": "Include transform node count" }, "include_attributes": { "type": "boolean", "default": false, "description": "Include attribute information for selected objects" } } } ``` **Example Response:** ```json { "success": true, "result": { "scene_name": "myScene.ma", "selected_objects": ["pCube1"], "total_objects": 15, "current_time": 1.0, "playback_range": [1.0, 24.0], "transforms": 8 }, "error": null } ``` ### 8. maya_get_object_info Get detailed information about a specific object. **Input Schema:** ```json { "type": "object", "properties": { "object_name": { "type": "string", "description": "Name of the object to query" }, "include_attributes": { "type": "boolean", "default": true, "description": "Include object attributes" }, "include_connections": { "type": "boolean", "default": false, "description": "Include node connections" } }, "required": ["object_name"] } ``` **Example Response:** ```json { "success": true, "result": { "name": "pCube1", "type": "transform", "exists": true, "transform": { "translate": [0.0, 0.0, 0.0], "rotate": [0.0, 0.0, 0.0], "scale": [1.0, 1.0, 1.0] }, "attributes": ["translateX", "translateY", "translateZ", "..."] }, "error": null } ``` ### 9. maya_list_objects List objects in the scene by type or pattern. **Input Schema:** ```json { "type": "object", "properties": { "object_type": { "type": "string", "enum": ["all", "transform", "mesh", "camera", "light", "material"], "default": "all", "description": "Type of objects to list" }, "pattern": { "type": "string", "description": "Optional pattern to filter object names" } } } ``` **Example Response:** ```json { "success": true, "result": { "objects": ["pCube1", "pSphere1", "pCylinder1"], "count": 3, "type": "transform" }, "error": null } ``` ## Error Handling All tools return a consistent error format: ```json { "success": false, "result": null, "error": "Error description with helpful context" } ``` ### Common Error Types 1. **Connection Errors**: Maya not running or plugin not loaded 2. **Validation Errors**: Invalid input parameters 3. **Execution Errors**: Maya command failures 4. **Security Errors**: Blocked operations in safe mode 5. **Timeout Errors**: Operations taking too long ### Error Response Examples **Maya Not Connected:** ```json { "success": false, "result": null, "error": "Not connected to Maya. Please ensure Maya is running and the MCP plugin is loaded." } ``` **Invalid Object:** ```json { "success": false, "result": null, "error": "Object 'nonexistent' does not exist" } ``` **Security Violation:** ```json { "success": false, "result": null, "error": "Command contains blocked keyword: import os" } ``` ## Best Practices ### 1. Error Handling Always check the `success` field before processing results: ```python response = await call_tool("maya_create", {"object_type": "polyCube"}) if response["success"]: print(f"Created: {response['result']}") else: print(f"Error: {response['error']}") ``` ### 2. Object Naming Use descriptive names for created objects: ```json { "object_type": "polyCube", "name": "buildingBlock_01" } ``` ### 3. Batch Operations Group related operations for better performance: ```python # Create multiple objects for i in range(5): await call_tool("maya_create", { "object_type": "polyCube", "name": f"cube_{i:02d}", "transform": {"translate": [i * 2, 0, 0]} }) ``` ### 4. Safe Execution Use safe mode for untrusted code: ```json { "command": "cmds.polyCube(name='safeCube')", "safe_mode": true } ``` ## Performance Considerations - **Batch Operations**: Group multiple operations when possible - **Selective Queries**: Use specific object types in `maya_list_objects` - **Attribute Filtering**: Only request attributes when needed - **Connection Pooling**: The server maintains persistent connections to Maya ## Rate Limits - No explicit rate limits, but Maya's responsiveness depends on scene complexity - Large scenes may require longer timeouts - Consider Maya's undo queue when performing many operations ## Version Compatibility | Maya Version | Supported | Notes | |--------------|-----------|-------| | 2023 | ✅ | Full support | | 2024 | ✅ | Full support | | 2025 | ✅ | Full support | | 2022 | ❌ | Not tested | ## Advanced Usage ### Custom Scripts Load and execute custom Python modules: ```json { "command": "exec(open('/path/to/custom_script.py').read())", "safe_mode": false } ``` ### Scene Automation Automate complex scene setups: ```python # Create a grid of cubes for x in range(5): for z in range(5): await call_tool("maya_create", { "object_type": "polyCube", "name": f"cube_{x}_{z}", "transform": {"translate": [x * 2, 0, z * 2]} }) ``` ### Debugging Use debug mode for detailed operation logs: ```bash npx maya-mcp-server --debug ``` ## Console Capture and Debugging Tools ### 10. maya_get_console_output Get Maya console output for debugging purposes. **Input Schema:** ```json { "type": "object", "properties": { "lines": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Number of recent lines to retrieve (default: all)" }, "include_errors": { "type": "boolean", "default": true, "description": "Include error output in results" } } } ``` **Example Request:** ```json { "lines": 50, "include_errors": true } ``` **Example Response:** ```json { "success": true, "result": { "output": [ "// Result: pCube1 //", "Created polyCube: pCube1", "Selection changed to: ['pCube1']" ], "errors": [ "Warning: Object 'nonexistent' not found" ], "capture_enabled": true, "total_lines": 150, "total_errors": 3 }, "error": null } ``` ### 11. maya_enable_console_capture Enable Maya console output capture for debugging. **Input Schema:** ```json { "type": "object", "properties": { "max_lines": { "type": "integer", "minimum": 100, "maximum": 10000, "default": 1000, "description": "Maximum number of lines to keep in buffer" } } } ``` **Example Request:** ```json { "max_lines": 2000 } ``` ### 12. maya_disable_console_capture Disable Maya console output capture. **Input Schema:** ```json { "type": "object", "properties": {} } ``` ### 13. maya_clear_console_buffer Clear Maya console output buffer. **Input Schema:** ```json { "type": "object", "properties": {} } ``` ### 14. maya_set_debug_mode Enable or disable debug mode for detailed logging. **Input Schema:** ```json { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable debug mode" } } } ``` **Example Request:** ```json { "enabled": true } ``` ### 15. maya_get_debug_info Get comprehensive debug information about Maya MCP plugin. **Input Schema:** ```json { "type": "object", "properties": {} } ``` **Example Response:** ```json { "success": true, "result": { "plugin_name": "maya_mcp", "plugin_version": "1.0.0", "debug_mode": true, "console_capture_enabled": true, "console_buffer_size": 150, "error_buffer_size": 3, "active_port": 7022, "command_port_status": true, "maya_version": "2024.0", "maya_api_version": "20240000", "python_version": "3.9.7", "recent_errors": ["Warning: Object not found"], "recent_output": ["Created cube", "Selection changed"] }, "error": null } ``` ## Debugging Workflow ### 1. Enable Console Capture ```json { "tool": "maya_enable_console_capture", "arguments": {"max_lines": 1000} } ``` ### 2. Enable Debug Mode ```json { "tool": "maya_set_debug_mode", "arguments": {"enabled": true} } ``` ### 3. Execute Operations Perform your Maya operations normally. ### 4. Check Console Output ```json { "tool": "maya_get_console_output", "arguments": {"lines": 50, "include_errors": true} } ``` ### 5. Get Debug Information ```json { "tool": "maya_get_debug_info", "arguments": {} } ``` ### 6. Clear Buffer (Optional) ```json { "tool": "maya_clear_console_buffer", "arguments": {} } ``` ## Plugin Development Tips ### Console Output Monitoring - Enable console capture during plugin development - Monitor both stdout and stderr for comprehensive debugging - Use debug mode for detailed operation logging - Clear buffers periodically to manage memory usage ### Error Tracking - Check recent errors in debug info for quick troubleshooting - Use console capture to track Maya command execution - Monitor command port status for connection issues ### Performance Debugging - Track buffer sizes to monitor memory usage - Use debug info to verify plugin status and configuration - Monitor Maya version compatibility through debug info ## Security Considerations for Debugging - Console capture may contain sensitive information - Debug mode increases logging verbosity - Clear console buffers regularly in production environments - Disable console capture when not needed for performance