mcp-luma-dream-machine

# 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