# Maya MCP Server - Complete Installation Guide
## Quick Navigation
- [Express Install (2 minutes)](#express-install-2-minutes)
- [Detailed Install](#detailed-installation)
- [Verification](#verification)
- [First Steps](#first-steps)
---
## Express Install (2 Minutes)
### Step 1: Install Dependencies (30 seconds)
```bash
cd maya-mcp-server
pip install -r requirements.txt
```
### Step 2: Start Maya & Open Port (30 seconds)
In Maya Script Editor (Python tab):
```python
import maya.cmds as cmds
cmds.commandPort(name="localhost:4434", sourceType="python", echoOutput=False)
print("Ready!")
```
### Step 3: Configure Claude Desktop (30 seconds)
**macOS:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** Edit `%APPDATA%/Claude/claude_desktop_config.json`
Add this (update path!):
```json
{
"mcpServers": {
"maya": {
"command": "python3",
"args": ["/FULL/PATH/TO/maya-mcp-server/src/expanded_mcp_server.py"],
"env": {
"MAYA_HOST": "localhost",
"MAYA_PORT": "4434"
}
}
}
}
```
### Step 4: Restart Claude (30 seconds)
Quit and restart Claude Desktop (File → Exit)
### Step 5: Test! (30 seconds)
In Claude, try:
> "Create a torus"
**Done!**
---
## Detailed Installation
### Prerequisites Check
**1. Python Version**
```bash
python3 --version
# Should be 3.8 or higher
```
**2. Maya Version**
- Maya 2020 or higher required
- Verify: In Maya, Help → About
**3. Claude Desktop**
- Download from https://claude.ai/download
- Or use any MCP-compatible client
---
### Installation Methods
#### Method 1: Automated Setup (Recommended)
```bash
cd maya-mcp-server
python3 setup.py
```
This will:
- Install dependencies
- Find Claude config
- Configure automatically
- Show next steps
#### Method 2: Manual Setup
**1. Install Dependencies**
```bash
pip install mcp>=1.0.0
# Or
pip install -r requirements.txt
```
**2. Configure Manually**
Follow Express Install Step 3
---
### Maya Setup Options
#### Option A: Manual Each Time (Good for testing)
```python
# In Maya Script Editor
import maya.cmds as cmds
cmds.commandPort(name="localhost:4434", sourceType="python")
```
#### Option B: Auto-Start (Production)
Create `userSetup.py`:
**Location:**
- macOS: `~/Library/Preferences/Autodesk/maya/2024/scripts/userSetup.py`
- Windows: `Documents/maya/2024/scripts/userSetup.py`
- Linux: `~/maya/2024/scripts/userSetup.py`
**Content:**
```python
import maya.cmds as cmds
def start_mcp():
cmds.commandPort(name="localhost:4434", sourceType="python", echoOutput=False)
print("MCP port ready")
cmds.evalDeferred(start_mcp)
```
#### Option C: Use Provided Script
```python
# In Maya
exec(open('/path/to/maya-mcp-server/src/maya_setup.py').read())
```
---
### Configuration Details
#### Full Claude Config Example
```json
{
"mcpServers": {
"maya": {
"command": "/usr/local/bin/python3",
"args": [
"/Users/yourname/Projects/maya-mcp-server/src/expanded_mcp_server.py"
],
"env": {
"MAYA_HOST": "localhost",
"MAYA_PORT": "4434"
}
}
}
}
```
**Important:**
- Use FULL paths (no ~, no relative paths)
- Check Python path: `which python3`
- Update your actual username/path
- Use forward slashes on Windows too
#### Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| MAYA_HOST | localhost | Maya hostname |
| MAYA_PORT | 4434 | Command port number |
#### Custom Port
If 4434 is in use:
```python
# In Maya
cmds.commandPort(name="localhost:7001", sourceType="python")
```
```json
// In Claude config
"MAYA_PORT": "7001"
```
---
## Verification
### Test 1: Connection Test
```bash
cd maya-mcp-server
python tests/test_connection.py
```
**Expected:**
```
Connected to Maya!
Test passed! Found X transforms
Created and deleted test object
All tests passed!
```
### Test 2: Maya Check
In Maya:
```python
import maya.cmds as cmds
print(cmds.commandPort("localhost:4434", query=True))
# Should print: True
```
### Test 3: Claude Check
In Claude Desktop:
1. Click tools icon (🔧)
2. Look for "maya" server
3. Should see 30+ tools listed
### Test 4: End-to-End
In Claude, try:
```
You: "Create a sphere"
Maya: Creates sphere
You: "Create a cube and scale it to [5, 5, 5]"
Maya: Creates and scales cube
You: "List all objects in the scene"
Maya: Shows list
```
---
## First Steps
### Learn the Basics (10 minutes)
**1. Create shapes:**
```
Create a sphere
Make a torus
Build a pyramid
```
**2. Transform them:**
```
Create a cube and scale it to [10, 2, 10]
Make a sphere at position [5, 0, 0]
```
**3. Add materials:**
```
Create a sphere with a red lambert material
Make a cube with shiny blue material
```
### Try Examples (20 minutes)
See `examples/example_prompts.md` for 100+ ready-to-use prompts.
### Read Documentation (30 minutes)
1. `docs/QUICK_START.md` - Overview
2. `docs/TOOLS_REFERENCE.md` - All tools
3. `docs/EXAMPLES.md` - Tutorials
---
## Troubleshooting
### "Could not connect to Maya"
**Cause:** Port not open or wrong port
**Fix:**
```python
# In Maya
import maya.cmds as cmds
# Check status
print(cmds.commandPort("localhost:4434", query=True))
# If False, open it
cmds.commandPort(name="localhost:4434", sourceType="python")
```
### "Module mcp not found"
**Cause:** MCP SDK not installed
**Fix:**
```bash
pip install mcp --break-system-packages
```
### "Tool not available in Claude"
**Cause:** Config not loaded or wrong path
**Fix:**
1. Check config file location
2. Verify path is absolute and correct
3. Restart Claude Desktop (File → Exit)
4. Check `~/Library/Logs/Claude/mcp*.log`
### Port Already in Use
**Symptoms:** Can't open port 4434
**Fix:** Use different port
```python
# Maya
cmds.commandPort(name="localhost:7001", sourceType="python")
```
```json
// Claude config
"MAYA_PORT": "7001"
```
### Wrong Python Version
**Symptoms:** "Python 3.8+ required"
**Fix:**
```bash
# Check version
python3 --version
# Use specific version in config
"command": "/usr/local/bin/python3.9"
```
See `docs/TROUBLESHOOTING.md` for complete guide.
---
## Platform-Specific Notes
### macOS
- Config: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Python: Usually `/usr/local/bin/python3` or `/opt/homebrew/bin/python3`
- Maya scripts: `~/Library/Preferences/Autodesk/maya/VERSION/scripts/`
### Windows
- Config: `%APPDATA%/Claude/claude_desktop_config.json`
- Python: Usually `C:\Python3X\python.exe`
- Maya scripts: `Documents/maya/VERSION/scripts/`
- Use forward slashes in paths: `C:/path/to/file`
### Linux
- Config: `~/.config/Claude/claude_desktop_config.json`
- Python: Usually `/usr/bin/python3`
- Maya scripts: `~/maya/VERSION/scripts/`
---
## Advanced Setup
### Multiple Maya Versions
Use different ports for each Maya version:
```python
# Maya 2023
cmds.commandPort(name="localhost:4434", sourceType="python")
# Maya 2024
cmds.commandPort(name="localhost:4435", sourceType="python")
```
Update Claude config to use appropriate port.
### Remote Maya
```python
# Maya on 192.168.1.100
cmds.commandPort(name="0.0.0.0:4434", sourceType="python")
```
```json
// Claude config
"MAYA_HOST": "192.168.1.100"
```
**Security:** Use firewall, VPN, or SSH tunnel for remote!
### Development Setup
```bash
# Clone editable
git clone https://your-repo/maya-mcp-server
cd maya-mcp-server
# Install dev dependencies
pip install -e .
pip install pytest pytest-asyncio
# Run tests
pytest tests/
```
---
## Updating
### Update to Latest Version
```bash
cd maya-mcp-server
git pull origin main
pip install -r requirements.txt --upgrade
```
Then restart Claude Desktop.
### Check Version
```bash
cd maya-mcp-server
grep "version" PROJECT_MANIFEST.md
```
---
## Uninstalling
### Remove from Claude
Edit config, remove "maya" entry, restart Claude.
### Remove Files
```bash
rm -rf maya-mcp-server
```
### Reset Maya
```python
# In Maya
import maya.cmds as cmds
cmds.commandPort(name="localhost:4434", close=True)
```
---
## Next Steps
1. Installation complete
2. Read `docs/QUICK_START.md`
3. Try `examples/example_prompts.md`
4. Study `docs/TOOLS_REFERENCE.md`
5. Build something amazing!
---
## Support
- **Documentation:** `docs/` directory
- **Examples:** `examples/` directory
- **Issues:** Check `docs/TROUBLESHOOTING.md`
---
**You're all set!**
Start creating 3D worlds with AI!
