Maya MCP Server

# Maya MCP Server Troubleshooting Guide (v1.0.6) ## 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 - **Version Mismatch**: Use `npx maya-mcp-server@latest` for the newest version (1.0.6) ## Recent Fixes (v1.0.6) - ✅ **WebSocket Compatibility**: Fixed Python 3.14 compatibility issues - ✅ **Version Synchronization**: All version numbers now unified - ✅ **Connection Stability**: Improved Maya connection reliability ## Common Issues and Solutions ### 🔌 Connection Issues #### Maya Not Connecting **Symptoms:** - "Not connected to Maya" error messages - Server starts but can't communicate with Maya - Tools return connection errors **Solutions:** 1. **Verify Maya is Running** ```bash # Check if Maya process is running # Windows: tasklist | findstr maya # macOS/Linux: ps aux | grep maya ``` 2. **Check Plugin Status** ```python # In Maya Script Editor: import maya.cmds as cmds print(cmds.pluginInfo("maya_mcp", query=True, loaded=True)) ``` 3. **Verify Command Port** ```python # In Maya Script Editor: import maya.cmds as cmds print(cmds.commandPort(query=True, name=":7022")) ``` 4. **Manual Plugin Load** ```python # In Maya Script Editor: import maya.cmds as cmds cmds.loadPlugin("path/to/maya_mcp.py") ``` #### Port Already in Use **Symptoms:** - "Port 7022 already in use" error - Server fails to start - Connection refused errors **Solutions:** 1. **Find Process Using Port** ```bash # Windows: netstat -ano | findstr :7022 # macOS/Linux: lsof -i :7022 ``` 2. **Use Alternative Port** ```bash npx maya-mcp-server --maya-port 7023 ``` 3. **Kill Conflicting Process** ```bash # Windows (replace PID): taskkill /PID 1234 /F # macOS/Linux: kill -9 1234 ``` #### Firewall Blocking Connection **Symptoms:** - Connection timeouts - Works locally but not remotely - Intermittent connection issues **Solutions:** 1. **Windows Firewall** ```bash # Add firewall rule for Maya netsh advfirewall firewall add rule name="Maya MCP" dir=in action=allow protocol=TCP localport=7022 ``` 2. **Test Local Connection** ```bash telnet localhost 7022 ``` 3. **Use Localhost Only** ```bash npx maya-mcp-server --host 127.0.0.1 ``` ### 🔧 Plugin Issues #### Plugin Not Loading **Symptoms:** - No "Maya MCP Plugin loaded" message in Script Editor - Plugin not visible in Plugin Manager - Maya starts without MCP functionality **Solutions:** 1. **Check Plugin Path** ```python # In Maya Script Editor: import maya.cmds as cmds print(cmds.internalVar(userPluginDir=True)) ``` 2. **Verify File Permissions** ```bash # Ensure plugin file is readable ls -la ~/maya/plug-ins/maya_mcp.py ``` 3. **Check Maya Version Compatibility** - Maya 2023: Supported ✅ - Maya 2024: Supported ✅ - Maya 2025: Supported ✅ - Maya 2022: Not tested ❌ 4. **Manual Installation** ```bash # Copy plugin to correct directory # 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/ ``` #### Plugin Crashes Maya **Symptoms:** - Maya crashes when loading plugin - Error messages in Maya log - Plugin loads but causes instability **Solutions:** 1. **Check Maya Log** ```bash # Windows: type "%TEMP%\maya_*.log" # macOS: cat ~/Library/Logs/Autodesk/maya/maya.log # Linux: cat ~/.autodesk/maya/maya.log ``` 2. **Safe Mode Loading** ```python # Load plugin with error catching try: import maya.cmds as cmds cmds.loadPlugin("maya_mcp.py") except Exception as e: print(f"Plugin load error: {e}") ``` 3. **Check Python Environment** ```python # Verify Python version in Maya import sys print(sys.version) print(sys.path) ``` ### 🚀 Server Issues #### Server Won't Start **Symptoms:** - "Failed to start server" error - Import errors - Permission denied errors **Solutions:** 1. **Check Python Version** ```bash python --version # Should be 3.8+ ``` 2. **Install Dependencies** ```bash pip install -r requirements.txt ``` 3. **Check Port Availability** ```bash # Test if port 8765 is available python -c "import socket; s=socket.socket(); s.bind(('localhost', 8765)); print('Port available')" ``` 4. **Run with Debug Mode** ```bash npx maya-mcp-server --debug ``` #### Server Starts but Tools Don't Work **Symptoms:** - Server appears to start successfully - Tools return "Unknown command" errors - MCP client can't discover tools **Solutions:** 1. **Verify Tool Registration** ```bash # Check server logs for tool registration npx maya-mcp-server --debug 2>&1 | grep -i "tool" ``` 2. **Test Tool Discovery** ```python # Test MCP tool discovery import asyncio from mcp_server import MayaMCPServer async def test(): server = MayaMCPServer() tools = await server.list_tools() print(f"Available tools: {[t.name for t in tools]}") asyncio.run(test()) ``` 3. **Check Configuration** ```bash # Verify config file is valid python -c "import yaml; print(yaml.safe_load(open('config.yaml')))" ``` ### 🔒 Security Issues #### Commands Blocked in Safe Mode **Symptoms:** - "Command contains blocked keyword" errors - Python execution fails - Import statements rejected **Solutions:** 1. **Disable Safe Mode** (Use with caution) ```json { "command": "import os; print(os.getcwd())", "safe_mode": false } ``` 2. **Use Maya-Safe Commands** ```python # Instead of: import os # Use: import maya.cmds as cmds scene_path = cmds.file(query=True, sceneName=True) ``` 3. **Check Blocked Keywords** ```python # Current blocked keywords: blocked = [ "import os", "import sys", "exec(", "eval(", "__import__", "open(", "file(", "subprocess", "system", "reload", "compile" ] ``` #### Permission Errors **Symptoms:** - "Permission denied" errors - Can't write files - Plugin installation fails **Solutions:** 1. **Run as Administrator** (Windows) ```bash # Right-click Command Prompt -> "Run as administrator" npx maya-mcp-server ``` 2. **Check File Permissions** (macOS/Linux) ```bash chmod +x bin/maya-mcp-server chmod 644 plug-ins/maya_mcp.py ``` 3. **Use User Directory** ```bash # Install to user directory instead of system pip install --user -r requirements.txt ``` ### 📊 Performance Issues #### Slow Response Times **Symptoms:** - Tools take long time to respond - Timeout errors - Maya becomes unresponsive **Solutions:** 1. **Increase Timeout** ```bash npx maya-mcp-server --timeout 60 ``` 2. **Check Scene Complexity** ```python # In Maya, check object count import maya.cmds as cmds print(f"Total objects: {len(cmds.ls(dag=True))}") ``` 3. **Optimize Queries** ```json { "object_type": "transform", "pattern": "specific_name" } ``` 4. **Monitor Performance** ```bash # Enable performance logging npx maya-mcp-server --debug --log-level DEBUG ``` #### Memory Issues **Symptoms:** - Out of memory errors - Maya crashes during operations - System becomes slow **Solutions:** 1. **Monitor Memory Usage** ```python # In Maya Script Editor: import psutil process = psutil.Process() print(f"Memory usage: {process.memory_info().rss / 1024 / 1024:.1f} MB") ``` 2. **Clear Maya History** ```python import maya.cmds as cmds cmds.flushUndo() ``` 3. **Restart Maya Periodically** ```bash # For long-running operations, restart Maya every few hours ``` ### 🐛 Debugging Tools #### Enable Debug Logging ```bash # Start server with maximum logging npx maya-mcp-server --debug --log-level DEBUG ``` #### Test Individual Tools ```python # Test tool execution directly import asyncio from maya_bridge import MayaBridge from config import ServerConfig async def test_tool(): config = ServerConfig() bridge = MayaBridge(config) await bridge.initialize() # Test create tool request = MayaRequest( command="maya_create", arguments={"object_type": "polyCube"}, request_id="test_001" ) response = await bridge.execute_command(request) print(f"Response: {response}") asyncio.run(test_tool()) ``` #### Check Connection Status ```python # Get detailed connection status import asyncio from maya_bridge import MayaBridge async def check_status(): bridge = MayaBridge(config) status = await bridge.get_connection_status() print(f"Connection status: {status}") asyncio.run(check_status()) ``` #### Maya Plugin Diagnostics ```python # In Maya Script Editor - run diagnostics import maya_mcp status = maya_mcp.mcp_diagnose_connection() print(status) ``` ### 📝 Log Files #### Server Logs - Location: Console output or specified log file - Enable: `--debug` flag - Format: Timestamp, level, component, message #### Maya Logs - **Windows**: `%TEMP%\maya_*.log` - **macOS**: `~/Library/Logs/Autodesk/maya/maya.log` - **Linux**: `~/.autodesk/maya/maya.log` #### Plugin Logs - Visible in Maya Script Editor - Prefix: `maya-mcp-plugin` - Levels: INFO, WARNING, ERROR ### 🆘 Getting Help #### Before Reporting Issues 1. **Check Version Compatibility** - Maya version: 2023-2025 - Python version: 3.8+ - OS compatibility 2. **Gather Information** ```bash # System info python --version maya -v # Maya version npx maya-mcp-server --version ``` 3. **Test Basic Functionality** ```bash # Test server startup npx maya-mcp-server --help # Test Maya connection telnet localhost 7022 ``` 4. **Collect Logs** ```bash # Run with debug logging npx maya-mcp-server --debug > debug.log 2>&1 ``` #### Reporting Issues Include the following information: - **Environment**: OS, Maya version, Python version - **Error Messages**: Complete error text - **Steps to Reproduce**: Exact commands used - **Log Files**: Debug output and Maya logs - **Configuration**: Config files and command-line arguments #### Community Support - **GitHub Issues**: [Report bugs](https://github.com/Jeffreytsai1004/maya-mcp/issues) - **Discussions**: [Community help](https://github.com/Jeffreytsai1004/maya-mcp/discussions) - **Documentation**: [Wiki pages](https://github.com/Jeffreytsai1004/maya-mcp/wiki) ### 🔧 Advanced Troubleshooting #### Network Debugging ```bash # Test network connectivity curl -v http://localhost:8765/health # Check port binding netstat -tulpn | grep 8765 ``` #### Process Debugging ```bash # Monitor server process ps aux | grep maya-mcp-server # Check resource usage top -p $(pgrep -f maya-mcp-server) ``` #### Configuration Debugging ```python # Validate configuration from config import ConfigManager manager = ConfigManager() config = manager.load_config() print(config) ``` This troubleshooting guide covers the most common issues. If you encounter problems not covered here, please check the GitHub issues or create a new issue with detailed information.