# Maya MCP Server

**Control Autodesk Maya with AI through natural language**

A production-ready Model Context Protocol (MCP) server that enables AI assistants like Claude to control Autodesk Maya programmatically with 30+ comprehensive tools.

![Version](https://img.shields.io/badge/version-1.0.0-blue)
![Python](https://img.shields.io/badge/python-3.8+-green)
![Maya](https://img.shields.io/badge/Maya-2020+-orange)
![License](https://img.shields.io/badge/license-MIT-lightgrey)

---

## Features

- **30+ Maya Tools** - Comprehensive control over Maya's features
- **No Maya Installation Required** - Uses Maya's built-in command port
- **Natural Language Interface** - Build 3D scenes through conversation
- **Production Ready** - Error handling, logging, validation
- **Fully Documented** - Extensive guides and examples

### What You Can Do

- **Create any primitive shape** (19 types)
- **Advanced mesh modeling** (extrude, bevel, smooth, boolean)
- **Professional materials and lighting**
- **Scene organization and hierarchy**
- **Procedural generation** (arrays, grids, patterns)
- **Animation keyframes**
- **Deformers and non-destructive editing**

---

## Quick Start

### Prerequisites

- Python 3.8 or higher
- Autodesk Maya 2020 or higher
- Claude Desktop (or any MCP-compatible client)

### Installation (2 Minutes)

**1. Install Python dependencies:**
```bash
cd maya-mcp-server
pip install -r requirements.txt
```

**2. Open Maya command port:**

In Maya Script Editor (Python tab):
```python
import maya.cmds as cmds
cmds.commandPort(name="localhost:4434", sourceType="python", echoOutput=False)
print("Maya ready for MCP!")
```

**3. Configure Claude Desktop:**

Edit config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "maya": {
      "command": "python3",
      "args": ["/FULL/PATH/TO/maya-mcp-server/src/expanded_mcp_server.py"],
      "env": {
        "MAYA_HOST": "localhost",
        "MAYA_PORT": "4434"
      }
    }
  }
}
```

**4. Restart Claude Desktop**

**5. Start creating!**

> "Create a torus, bevel its edges, add a gold metallic material"

---

## Documentation

| Document | Description |
|----------|-------------|
| [Quick Start](docs/QUICK_START.md) | Get running in 2 minutes |
| [Tools Reference](docs/TOOLS_REFERENCE.md) | All 30+ tools documented |
| [Examples](docs/EXAMPLES.md) | Learn by example |
| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common issues solved |

---

## Example Usage

### Simple
```
You: "Create a sphere"
Maya: Creates sphere at origin
```

### Intermediate
```
You: "Create a cube, scale it to [10, 5, 10], bevel edges with 0.2 offset"
Maya: Creates beveled box
```

### Advanced
```
You: "Build a castle with keep, 4 towers, walls with gate cutout, stone material"
Maya: Creates complete castle scene
```

---

## Available Tools (30+)

| Category | Tools |
|----------|-------|
| **Primitives** | 19 types (polygon + NURBS) |
| **Mesh Ops** | Extrude, Bevel, Smooth, Boolean, Combine, Separate |
| **Lighting** | Point, Directional, Spot, Area, Ambient, Volume |
| **Materials** | Lambert, Blinn, Phong, PBR |
| **Organization** | Group, Parent, Arrange (grid/circle), Duplicate |
| **Animation** | Keyframe transforms |
| **Plus** | Cameras, Curves, Deformers |

See [Tools Reference](docs/TOOLS_REFERENCE.md) for details.

---

## Project Structure

```
maya-mcp-server/
├── src/
│   ├── expanded_mcp_server.py      # Main server (30+ tools)
│   ├── simplified_mcp_server.py    # Basic version (6 tools)
│   └── maya_setup.py               # Quick Maya setup
├── docs/
│   ├── QUICK_START.md              # Setup guide
│   ├── TOOLS_REFERENCE.md          # Tool docs
│   ├── EXAMPLES.md                 # Tutorials
│   └── TROUBLESHOOTING.md          # Help
├── examples/
│   └── example_prompts.md          # Sample prompts
├── tests/
│   └── test_connection.py          # Connection test
├── README.md                       # This file
├── requirements.txt                # Dependencies
├── setup.py                        # Installer
└── LICENSE                         # MIT License
```

---

## Testing

Test Maya connection:
```bash
python tests/test_connection.py
```

---

## Configuration

Environment variables:
- `MAYA_HOST` - Maya hostname (default: localhost)
- `MAYA_PORT` - Command port (default: 4434)

---

## Tips

1. **Use descriptive names**: `tree_trunk` not `cube1`
2. **Combine operations**: Do multiple things in one prompt
3. **Build hierarchies**: Use grouping and parenting
4. **Leverage strengths**: NURBS for organic, polygons for hard surface

---

## Troubleshooting

**"Could not connect to Maya"**
- Verify Maya is running
- Check: `cmds.commandPort("localhost:4434", query=True)`

See [Troubleshooting Guide](docs/TROUBLESHOOTING.md)

---

## License

MIT License - Free to use and modify

---

## Acknowledgments

- Anthropic - Model Context Protocol
- Autodesk - Maya Python API
- PatrickPalmer - [MayaMCP](https://github.com/PatrickPalmer/MayaMCP) inspiration

---

## Get Started

1. Read [Quick Start Guide](docs/QUICK_START.md)
2. Try [Example Prompts](examples/example_prompts.md)
3. Build something amazing!

**Ready to build 3D worlds with AI?**