luma-ai

This MCP server provides programmatic access to Luma AI's Dream Machine API (v1) for generating and managing AI-driven videos and images. The server exposes a suite of tools under the Model Context Protocol (MCP) that let you create video generations from text prompts, track their status, upscale, add AI-generated audio, and generate images with optional references. Core capabilities include text-to-video generation with customizable models, resolution, duration, aspect ratio, and optional keyframes for advanced video creation. You can also generate images from text prompts with optional reference and style inputs, and manage your credits and generation lifecycle end-to-end using the MCP commands described in the tool list.

Prerequisites:

• Python installed on your system (Python 3.8+).
• Access to a suitable runtime for the MCP server (the example uses uv/uvx as the runner).
• An active Luma API key obtainable from Luma AI (https://lumalabs.ai).

Installation steps:

1. Install uv/uvx if you haven’t already. For example, using npm (uvx) or your preferred Python environment as per your setup.
2. Ensure you have a working MCP server directory named appropriately (e.g., luma_ai_mcp_server) that contains the MCP server implementation compatible with the Dream Machine API v1.
3. Set the LUMA_API_KEY in your environment or in the MCP configuration as shown in the example below.
4. Run the MCP server using the configuration method (the example uses uv to run a Python project).

Example commands (adjust paths as needed):

• Ensure dependencies are installed within your project environment.

• Start the server via the provided MCP runner:

  uv run --project /path/to/your/luma-ai-mcp-server -m luma_ai_mcp_server

5. Confirm the server is responding to MCP requests (see troubleshooting tips in additional_notes).

Tips and notes:

• Ensure the LUMA_API_KEY environment variable is securely stored and accessible to the MCP process.
• Valid input parameters (models, resolutions, durations, aspect ratios) must match the API limitations listed in the README (e.g., durations: 5s or 9s; resolutions: 540p, 720p, 1080p, 4k).
• Use generation IDs returned by get_generation for subsequent operations like get_credits, upscale_generation, add_audio, and delete_generation.
• When using keyframes, provide frame0/frame1 with the correct structure (type: image or generation) as specified in the API docs.
• If using Claude Desktop integration, ensure the path to the MCP server is accurate and that Claude is restarted after config changes.
• Common issues include invalid API keys, incorrect project paths, or network issues preventing access to the Dream Machine API. Check logs for details and verify API key scope/permissions.