Maya MCP Server

# Maya MCP Server Installation Guide ## Quick Installation (v1.0.6) ### NPX (Recommended) ```bash # Start the latest version npx maya-mcp-server@latest # With options npx maya-mcp-server --host localhost --port 8765 --debug # Verify version npx maya-mcp-server --version # Output: Maya MCP Server 1.0.6 ``` This automatically downloads, installs, and starts the MCP server. ## Detailed Installation ### Prerequisites #### System Requirements - **Operating System**: Windows 10+, macOS 10.15+, or Linux (Ubuntu 18.04+) - **Python**: 3.8 or higher - **Node.js**: 16.0 or higher (for NPX) - **Autodesk Maya**: 2023, 2024, or 2025 #### Check Prerequisites ```bash # Check Python version python --version # Should output: Python 3.8.x or higher # Check Node.js version (for NPX) node --version # Should output: v16.x.x or higher # Check Maya installation maya -v # Should output Maya version information ``` ### Step 1: Install Maya MCP Server #### Manual Installation ```bash # Clone repository git clone https://github.com/Jeffreytsai1004/maya-mcp.git cd maya-mcp # Install dependencies pip install -r requirements.txt # Test installation python src/server.py --help ``` ### Step 2: Install Maya Plugin The Maya plugin enables communication between the MCP server and Maya. #### Automatic Installation ```bash # Use the built-in installer npx maya-mcp-server --install-plugin # Or if installed manually python scripts/install_plugin.py ``` #### Manual Installation 1. **Locate Maya Plugins Directory** **Windows:** ``` %USERPROFILE%\Documents\maya\plug-ins\ ``` **macOS:** ``` ~/Library/Preferences/Autodesk/maya/plug-ins/ ``` **Linux:** ``` ~/maya/plug-ins/ ``` 2. **Copy Plugin File** ```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. **Verify Installation** Start Maya and check the Script Editor for: ``` Successfully loaded maya_mcp v1.0.0 ``` ### Step 3: Configure Maya #### Enable Plugin Auto-Loading 1. Open Maya 2. Go to **Window → Settings/Preferences → Plug-in Manager** 3. Find `maya_mcp.py` in the list 4. Check both **Loaded** and **Auto load** boxes #### Verify Command Port The plugin should automatically open a command port on port 7022. Verify in Maya's Script Editor: ```python import maya.cmds as cmds print(cmds.commandPort(query=True, name=":7022")) # Should return: True ``` ### Step 4: Start the Server #### Basic Startup ```bash # Start with default settings npx maya-mcp-server # You should see: # Maya MCP Server starting on localhost:8765 # Connecting to Maya on port 7022... # Server ready for connections ``` #### Custom Configuration ```bash # Start with custom options npx maya-mcp-server \ --host 0.0.0.0 \ --port 8766 \ --maya-port 7023 \ --debug ``` #### Using Configuration File Create `config.yaml`: ```yaml host: localhost port: 8765 maya_port: 7022 debug: false log_level: INFO timeout: 30 max_retries: 3 # Security settings allowed_commands: - polyCube - sphere - select - ls - getAttr - setAttr blocked_commands: - file - system - eval - exec ``` Then start: ```bash npx maya-mcp-server --config config.yaml ``` ### Step 5: Test Installation #### Test Server Connection ```bash # Test if server is responding curl http://localhost:8765/health # Should return server status information ``` #### Test Maya Connection In Maya's Script Editor: ```python # Test plugin functionality import maya_mcp status = maya_mcp.mcp_get_connection_status() print(status) ``` #### Test MCP Tools Using an MCP client or testing script: ```python # Test tool discovery import asyncio from mcp_client import MCPClient async def test(): client = MCPClient("http://localhost:8765") tools = await client.list_tools() print(f"Available tools: {[t['name'] for t in tools]}") # Test create tool result = await client.call_tool("maya_create", { "object_type": "polyCube", "name": "testCube" }) print(f"Create result: {result}") asyncio.run(test()) ``` ## Installation Verification ### Checklist - [ ] Python 3.8+ installed - [ ] Maya 2023-2025 installed - [ ] Maya MCP Server installed - [ ] Maya plugin copied to plugins directory - [ ] Plugin loads automatically in Maya - [ ] Command port opens on port 7022 - [ ] MCP server starts successfully - [ ] Server can connect to Maya - [ ] Tools are discoverable - [ ] Basic operations work ### Verification Commands ```bash # Check server version npx maya-mcp-server --version # Test server startup npx maya-mcp-server --help # Check plugin status (in Maya) import maya.cmds as cmds print(cmds.pluginInfo("maya_mcp", query=True, loaded=True)) # Test connection (in Maya) import maya_mcp print(maya_mcp.mcp_get_plugin_info()) ``` ## Platform-Specific Instructions ### Windows #### Prerequisites ```powershell # Install Python from python.org or Microsoft Store # Install Node.js from nodejs.org # Install Maya from Autodesk # Verify installations python --version node --version maya -v ``` #### Installation ```powershell # Install via NPX npx maya-mcp-server # Manual plugin installation copy plug-ins\maya_mcp.py "%USERPROFILE%\Documents\maya\plug-ins\" ``` #### Firewall Configuration ```powershell # Add firewall rule for Maya command port netsh advfirewall firewall add rule name="Maya MCP" dir=in action=allow protocol=TCP localport=7022 # Add rule for MCP server netsh advfirewall firewall add rule name="Maya MCP Server" dir=in action=allow protocol=TCP localport=8765 ``` ### macOS #### Prerequisites ```bash # Install Python via Homebrew brew install python # Install Node.js brew install node # Install Maya from Autodesk ``` #### Installation ```bash # Install via NPX npx maya-mcp-server # Manual plugin installation cp plug-ins/maya_mcp.py ~/Library/Preferences/Autodesk/maya/plug-ins/ ``` #### Permissions ```bash # Ensure plugin is executable chmod +x ~/Library/Preferences/Autodesk/maya/plug-ins/maya_mcp.py # Allow network connections in System Preferences → Security & Privacy ``` ### Linux (Ubuntu/Debian) #### Prerequisites ```bash # Update package list sudo apt update # Install Python sudo apt install python3 python3-pip # Install Node.js curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt-get install -y nodejs # Install Maya (download from Autodesk) ``` #### Installation ```bash # Install via NPX npx maya-mcp-server # Manual plugin installation mkdir -p ~/maya/plug-ins cp plug-ins/maya_mcp.py ~/maya/plug-ins/ ``` #### Firewall Configuration ```bash # Allow ports through UFW sudo ufw allow 7022 sudo ufw allow 8765 ``` ## Docker Installation (Advanced) ### Dockerfile ```dockerfile FROM python:3.9-slim # Install system dependencies RUN apt-get update && apt-get install -y \ curl \ && rm -rf /var/lib/apt/lists/* # Install Node.js for NPX RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \ && apt-get install -y nodejs # Set working directory WORKDIR /app # Copy application files COPY . . # Install Python dependencies RUN pip install -r requirements.txt # Expose ports EXPOSE 8765 # Start server CMD ["python", "src/server.py"] ``` ### Docker Compose ```yaml version: '3.8' services: maya-mcp-server: build: . ports: - "8765:8765" environment: - MAYA_MCP_HOST=0.0.0.0 - MAYA_MCP_PORT=8765 - MAYA_MCP_MAYA_PORT=7022 volumes: - ./config.yaml:/app/config.yaml restart: unless-stopped ``` ### Running with Docker ```bash # Build and run docker-compose up -d # Or run directly docker run -p 8765:8765 -p 7022:7022 maya-mcp-server ``` ## Troubleshooting Installation ### Common Issues 1. **Python Version Too Old** ```bash # Update Python # Windows: Download from python.org # macOS: brew upgrade python # Linux: sudo apt upgrade python3 ``` 2. **Maya Plugin Not Loading** ```python # Check plugin path in Maya import maya.cmds as cmds print(cmds.internalVar(userPluginDir=True)) # Manually load plugin cmds.loadPlugin("maya_mcp.py") ``` 3. **Port Conflicts** ```bash # Find process using port netstat -ano | findstr :7022 # Windows lsof -i :7022 # macOS/Linux # Use alternative port npx maya-mcp-server --maya-port 7023 ``` 4. **Permission Errors** ```bash # Run as administrator (Windows) # Use sudo for system directories (Linux/macOS) # Check file permissions ``` ### Getting Help If you encounter issues: 1. Check the [Troubleshooting Guide](TROUBLESHOOTING.md) 2. Review the [FAQ](FAQ.md) 3. Search [GitHub Issues](https://github.com/Jeffreytsai1004/maya-mcp/issues) 4. Create a new issue with: - Operating system and version - Python and Maya versions - Complete error messages - Steps to reproduce ## Next Steps After successful installation: 1. Read the [API Documentation](API.md) 2. Try the [Examples](examples/) 3. Configure your AI assistant to use the MCP server 4. Explore advanced features and customization options ## Uninstallation ### Remove NPX Installation ```bash # If installed globally npm uninstall -g maya-mcp-server # NPX cache cleanup npx clear-npx-cache ``` ### Remove Manual Installation ```bash # Remove plugin from Maya rm ~/maya/plug-ins/maya_mcp.py # Linux/macOS del "%USERPROFILE%\Documents\maya\plug-ins\maya_mcp.py" # Windows # Remove source code rm -rf maya-mcp-server/ # Linux/macOS rmdir /s maya-mcp-server\ # Windows ``` ### Remove Python Package ```bash pip uninstall maya-mcp-server ```