Content
# Luma AI MCP Server 🎥
A Model Context Protocol server for Luma AI's Dream Machine API.
## Overview
This MCP server integrates with Luma AI's Dream Machine API (v1) to provide tools for generating, managing, and manipulating AI-generated videos and images via Large Language Models. It implements the Model Context Protocol (MCP) to enable seamless interaction between AI assistants and Luma's creative tools.
## Features ✨
- Text-to-video generation
- Advanced video generation with keyframes
- Image-to-video conversion
- Video extension and interpolation
- Image generation with reference images
- Audio addition to videos
- Video upscaling
- Credit management
- Generation tracking and status checking
## Tools 🛠️
1. `ping`
- Check if the Luma API is running
- No parameters required
2. `create_generation`
- Creates a new video generation
- Input:
- `prompt` (string, required): Text description of the video to generate
- `model` (string, optional): Model to use (default: "ray-2")
- Available models: "ray-1-6", "ray-2", "ray-flash-2"
- `resolution` (string, optional): Video resolution (choices: "540p", "720p", "1080p", "4k")
- `duration` (string, optional): Video duration (only "5s" and "9s" are currently supported)
- `aspect_ratio` (string, optional): Video aspect ratio (e.g., "16:9", "1:1", "9:16", "4:3", "3:4", "21:9", "9:21")
- `loop` (boolean, optional): Whether to make the video loop
- `keyframes` (object, optional): Start and end frames for advanced video generation:
- `frame0` and/or `frame1` with either:
- `{"type": "image", "url": "image_url"}` for image keyframes
- `{"type": "generation", "id": "generation_id"}` for video keyframes
3. `get_generation`
- Gets the status of a generation
- Input:
- `generation_id` (string, required): ID of the generation to check
- Output includes:
- Generation ID
- State (queued, dreaming, completed, failed)
- Failure reason (if failed)
- Video URL (if completed)
4. `list_generations`
- Lists all generations
- Input:
- `limit` (number, optional): Maximum number of generations to return (default: 10)
- `offset` (number, optional): Number of generations to skip
5. `delete_generation`
- Deletes a generation
- Input:
- `generation_id` (string, required): ID of the generation to delete
6. `upscale_generation`
- Upscales a video generation to higher resolution
- Input:
- `generation_id` (string, required): ID of the generation to upscale
- `resolution` (string, required): Target resolution for the upscaled video (one of "540p", "720p", "1080p", or "4k")
- Note:
- The generation must be in a completed state to be upscaled
- The target resolution must be higher than the original generation's resolution
- Each generation can only be upscaled once
7. `add_audio`
- Adds AI-generated audio to a video generation
- Input:
- `generation_id` (required): The ID of the generation to add audio to
- `prompt` (required): The prompt for the audio generation
- `negative_prompt` (optional): The negative prompt for the audio generation
- `callback_url` (optional): URL to notify when the audio processing is complete
8. `generate_image`
- Generates an image from a text prompt with optional reference images
- Input:
- `prompt` (string, required): Text description of the image to generate
- `model` (string, optional): Model to use for image generation (default: "photon-1")
- Available models: "photon-1", "photon-flash-1"
- `aspect_ratio` (string, optional): Image aspect ratio (same options as video)
- `image_ref` (array, optional): Reference images to guide generation
- Each ref: `{"url": "image_url", "weight": optional_float}`
- `style_ref` (array, optional): Style reference images
- Each ref: `{"url": "image_url", "weight": optional_float}`
- `character_ref` (object, optional): Character reference images
- Format: `{"identity_name": {"images": ["url1", "url2", ...]}}`
- `modify_image_ref` (object, optional): Image to modify
- Format: `{"url": "image_url", "weight": optional_float}`
9. `get_credits`
- Gets credit information for the current user
- No parameters required
- Returns available credit balance in USD cents
10. `get_camera_motions`
- Gets all supported camera motions
- No parameters required
- Returns: List of available camera motion strings
## Setup for Claude Desktop 🖥️
1. Get your Luma API key from [Luma AI](https://lumalabs.ai) (sign up or log in to get your API key)
2. Add this to your Claude Desktop configuration file:
- On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"luma": {
"command": "uv",
"args": [
"run",
"--project",
"/path/to/your/luma-ai-mcp-server",
"-m",
"luma_ai_mcp_server"
],
"env": {
"LUMA_API_KEY": "your-luma-api-key-here"
}
}
}
}
```
Replace:
- `/path/to/your/luma-ai-mcp-server` with the actual path to your server directory
- `your-luma-api-key-here` with your actual Luma API key
3. Restart Claude Desktop
4. That's it! You can now use Luma AI tools directly in Claude Desktop conversations.
## Quick Troubleshooting 🛠️
If you're having issues:
1. Check your API key is correct
2. Make sure the path to the server is correct
3. View logs with: `tail -n 20 -f ~/Library/Logs/Claude/mcp*.log`
## Advanced Video Generation Types 🎬
The Luma API supports various types of advanced video generation through keyframes:
1. **Starting from an image**: Provide `frame0` with `type: "image"` and an image URL
2. **Ending with an image**: Provide `frame1` with `type: "image"` and an image URL
3. **Extending a video**: Provide `frame0` with `type: "generation"` and a generation ID
4. **Reverse extending a video**: Provide `frame1` with `type: "generation"` and a generation ID
5. **Interpolating between videos**: Provide both `frame0` and `frame1` with `type: "generation"` and generation IDs
## API Limitations and Notes 📝
- **Duration**: Currently, the API only supports durations of "5s" or "9s"
- **Resolution**: Valid values are "540p", "720p", "1080p", and "4k"
- **Models**:
- Video generation:
- "ray-2" (default) - Best quality, slower
- "ray-flash-2" - Faster generation
- "ray-1-6" - Legacy model
- Image generation:
- "photon-1" (default) - Best quality, slower
- "photon-flash-1" - Faster generation
- **Generation types**: Video, image, and advanced (with keyframes)
- **Aspect Ratios**: "1:1" (square), "16:9" (landscape), "9:16" (portrait), "4:3" (standard), "3:4" (standard portrait), "21:9" (ultrawide), "9:21" (ultrawide portrait)
- **States**: "queued", "dreaming", "completed", "failed"
- **Upscaling**:
- Video generations can only be upscaled when they're in a "complete" state
- Target resolution must be higher than the original generation's resolution
- Each generation can only be upscaled once
- **API Key**: Required in environment variables
- **API Version**: Uses Dream Machine API v1
## License 📄
MIT
