LumaMCP
MCPLuma is an MCP server for AI-powered video generation using Luma Dream Machine via the AceDataCloud API. It works with Claude, VS Code, Cursor, and other MCP-compatible clients.
Core capabilities:
Text-to-Video (
luma_generate_video): Create videos from text prompts with options for aspect ratio, looping, clarity enhancement, and webhook callbacksImage-to-Video (
luma_generate_video_from_image): Animate one or two images as start/end frames with smooth motion generated between themExtend by ID (
luma_extend_video): Continue an existing video using its ID and a new promptExtend by URL (
luma_extend_video_from_url): Same as above but using the video's URLCheck task status (
luma_get_task): Query status and results (video URLs, thumbnails, metadata) for a single taskBatch status check (
luma_get_tasks_batch): Query up to 50 tasks at onceList aspect ratios (
luma_list_aspect_ratios): View all 7 supported ratios (16:9, 9:16, 1:1, 4:3, 3:4, 21:9, 9:21) with use case descriptionsList actions (
luma_list_actions): Browse all available API actions and their corresponding tools
LumaMCP
A Model Context Protocol (MCP) server for AI video generation using Luma Dream Machine through the AceDataCloud API.
Generate AI videos directly from Claude, VS Code, or any MCP-compatible client.
Features
Text to Video - Create AI-generated videos from text prompts
Image to Video - Animate images with start/end frame control
Video Extension - Extend existing videos with additional content
Multiple Aspect Ratios - Support for 16:9, 9:16, 1:1, and more
Loop Videos - Create seamlessly looping animations
Clarity Enhancement - Optional video quality enhancement
Task Tracking - Monitor generation progress and retrieve results
Related MCP server: SoraMCP
Tool Reference
Tool | Description |
| Generate AI video from a text prompt using Luma Dream Machine. |
| Generate AI video using reference images as start and/or end frames. |
| Extend an existing video with additional content. |
| Extend an existing video using its URL. |
| Query the status and result of a video generation task. |
| Query multiple video generation tasks at once. |
| List all available aspect ratios for Luma video generation. |
| List all available Luma API actions and corresponding tools. |
Connect: hosted OAuth, API token, or local stdio
The hosted endpoint is https://luma.mcp.acedata.cloud/mcp. Choose one route for the MCP client:
Route | When to use it | Credential setup |
Hosted OAuth | The client supports remote MCP OAuth | Add only the URL, then sign in to AceDataCloud and approve access. No token needs to be pasted into client configuration. |
Hosted API token | The client cannot finish OAuth, or you need an explicit integration credential | Send an AceDataCloud API token in the |
Local stdio | The client runs a local MCP process | Install |
The hosted service advertises OAuth metadata and Dynamic Client Registration (DCR). DCR registers the client application; it is not an API key. OAuth signs you in and the client sends the resulting Bearer token; it may reuse or create an API credential for the account. Browser sign-in still requires an AceDataCloud account. The hosted service can be metered: review current service documentation and displayed pricing before a real operation. Do not configure both an OAuth login and a fixed Authorization header for the same server.
Hosted OAuth examples
Claude and Claude Desktop chat: Add a remote custom connector in
Customize → Connectors → Add custom connector, enterhttps://luma.mcp.acedata.cloud/mcp, select sign-in, and choose Register automatically if Claude asks how to register its OAuth client. Complete consent. Claude Desktop's localclaude_desktop_config.jsonis a separate setup. Claude connector guide.Claude Code:
claude mcp add --transport http --scope user luma https://luma.mcp.acedata.cloud/mcp, thenclaude mcp login luma. Check/mcp. Claude Code MCP guide.Cursor: Add a remote server with only
https://luma.mcp.acedata.cloud/mcp. For a project, merge the entry below into<project>/.cursor/mcp.json; for personal use, use~/.cursor/mcp.json. Cursor MCP guide.VS Code / Copilot: Run MCP: Add Server, select HTTP, enter
https://luma.mcp.acedata.cloud/mcp, then finish the browser sign-in. New portable workspace configs use<project>/.mcp.json; the VS Code-specific format below uses<project>/.vscode/mcp.jsonor the user profile. Check MCP: List Servers. VS Code MCP setup.Codex:
codex mcp add luma --url https://luma.mcp.acedata.cloud/mcp, thencodex mcp login luma. Its user settings are in~/.codex/config.toml. Official Codex MCP guide.
Cursor project config (OAuth):
{
"mcpServers": {
"luma": {"url": "https://luma.mcp.acedata.cloud/mcp"}
}
}VS Code-specific workspace config (OAuth):
{
"servers": {
"luma": {"type": "http", "url": "https://luma.mcp.acedata.cloud/mcp"}
}
}Hosted API token
Open Ace Data Cloud → Applications. Sign in, or register an account first.
Find General application. If it has not been created, choose Initialize General Application. A general key can use the services available to your account; a dedicated application's key is limited to its service. Check the required service/model access and current pricing.
Copy the API Key from the application card, or open Keys / Manage Keys → Create to create a separate key for this integration. Give it a recognizable name so you can revoke or rotate it independently.
When creating a key, review Expiration Time, Set Usage Limitation, and Allowed APIs. Enable only the restrictions you need, allow the operations you will call, then click Create and copy the token from the key list. Task lookup does not grant permission to submit a generation. Confirm the application's balance can cover your first request; any trial allowance is whatever your account currently displays.
Copy only the token value, without quotation marks, spaces, or
Bearer. An API Key / API Token field expects this raw value; only a manually configured HTTPAuthorizationheader needs theBearerprefix. Aplatform-...account-management token cannot replace a generation API key.


Save the key in the client's credential store or the environment variable shown below. Never put it in a prompt, shared workflow, screenshot, or Git commit. If authentication fails, check the full copied value, application/service access, expiration, usage limit, and balance before creating another key.
A fixed Bearer header bypasses OAuth. If the header is invalid, remove it before trying browser sign-in; keep the saved credential private.
For Claude Code, the shell expands the token when you add the server; treat the saved user MCP config as a secret:
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
claude mcp add --transport http --scope user luma https://luma.mcp.acedata.cloud/mcp \
--header "Authorization: Bearer $ACEDATACLOUD_API_TOKEN"For a Claude Code project config, put a variable reference in <project>/.mcp.json and set that variable in the environment that launches Claude Code:
{
"mcpServers": {
"luma": {
"type": "http",
"url": "https://luma.mcp.acedata.cloud/mcp",
"headers": {"Authorization": "Bearer ${ACEDATACLOUD_API_TOKEN}"}
}
}
}Cursor uses a different environment-variable syntax in ~/.cursor/mcp.json or an uncommitted project config:
{
"mcpServers": {
"luma": {
"url": "https://luma.mcp.acedata.cloud/mcp",
"headers": {"Authorization": "Bearer ${env:ACEDATACLOUD_API_TOKEN}"}
}
}
}In VS Code, run MCP: Open User Configuration and merge this server plus its masked input; ${input:...} is for VS Code's user/workspace format and is not portable to the Agent Host .mcp.json format:
{
"inputs": [
{"id": "acedata-luma-token", "type": "promptString", "description": "AceDataCloud API token", "password": true}
],
"servers": {
"luma": {
"type": "http",
"url": "https://luma.mcp.acedata.cloud/mcp",
"headers": {"Authorization": "Bearer ${input:acedata-luma-token}"}
}
}
}For Cline, use its MCP configuration UI or CLI file ~/.cline/data/settings/cline_mcp_settings.json; its remote transport value is streamableHttp. For JetBrains AI Assistant, add a remote URL from Settings → Tools → AI Assistant → Model Context Protocol (MCP). For Zed, use a context_servers entry with the URL only for OAuth or add a local Bearer header. These clients have different configuration schemas; follow their current UI rather than copying another client's JSON. Cline · JetBrains · Zed.
Local stdio
Install the package and give the local process an API token:
python -m pip install mcp-luma
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
mcp-lumaFor Claude Desktop local MCP, merge this entry into the file opened by its developer settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS). uvx requires uv on PATH:
{
"mcpServers": {
"luma": {
"command": "uvx",
"args": ["mcp-luma"],
"env": {"ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"}
}
}
}Keep this user-level file private. Self-hosted HTTP uses mcp-luma --transport http --port 8000; expose it only with suitable network and TLS controls. Local execution still calls the AceDataCloud API.
Check before using the service
https://luma.mcp.acedata.cloud/healthreturning{"status":"ok"}checks endpoint reachability only.Confirm that the MCP client loads tools.
luma_list_actionsis a reference tool; it does not verify downstream API access or balance.If you need a full API check, call
luma_generate_videowith your own valid input after reviewing current service documentation and displayed pricing. If the result contains a task ID, callluma_get_taskon that same ID until terminal success or failure. Do not resubmit the operation just to check progress.
For 401, check which auth route the client used and whether the token or OAuth session is valid. A 403 may mean an account permission or content moderation failure; read the returned error. Insufficient balance and downstream service failures need their own diagnosis. A listed tool or submitted task does not prove a successful result.
Available Tools
Video Generation
Tool | Description |
| Generate video from a text prompt |
| Generate video using reference images |
| Extend an existing video by ID |
| Extend an existing video by URL |
Tasks
Tool | Description |
| Query a single task status |
| Query multiple tasks at once |
Information
Tool | Description |
| List available aspect ratios |
| List available API actions |
Usage Examples
Generate Video from Prompt
User: Create a video of waves on a beach
Claude: I'll generate a beach wave video for you.
[Calls luma_generate_video with prompt="Ocean waves gently crashing on sandy beach, sunset"]Animate an Image
User: Animate this image: https://example.com/image.jpg
Claude: I'll create a video from your image.
[Calls luma_generate_video_from_image with start_image_url and appropriate prompt]Extend a Video
User: Continue this video with more action
Claude: I'll extend the video with additional content.
[Calls luma_extend_video with video_id and new prompt]Available Aspect Ratios
Aspect Ratio | Description | Use Case |
| Landscape (default) | YouTube, TV, presentations |
| Portrait | TikTok, Instagram Reels |
| Square | Instagram posts |
| Traditional | Classic video format |
| Portrait traditional | Portrait content |
| Ultrawide | Cinematic content |
| Tall ultrawide | Special vertical displays |
Configuration
Environment Variables
Variable | Description | Default |
| API token from AceDataCloud | Required |
| API base URL |
|
| OAuth client ID (hosted mode) | — |
| Platform base URL |
|
| Default aspect ratio |
|
| Request timeout in seconds |
|
| Logging level |
|
Command Line Options
mcp-luma --help
Options:
--version Show version
--transport Transport mode: stdio (default) or http
--port Port for HTTP transport (default: 8000)Development
Setup Development Environment
# Clone repository
git clone https://github.com/AceDataCloud/LumaMCP.git
cd LumaMCP
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # or `.venv\Scripts\activate` on Windows
# Install with dev dependencies
pip install -e ".[dev,test]"Run Tests
# Run unit tests
pytest
# Run with coverage
pytest --cov=core --cov=tools
# Run integration tests (requires API token)
pytest tests/test_integration.py -m integrationCode Quality
# Format code
ruff format .
# Lint code
ruff check .
# Type check
mypy core toolsBuild & Publish
# Install build dependencies
pip install -e ".[release]"
# Build package
python -m build
# Upload to PyPI
twine upload dist/*Project Structure
LumaMCP/
├── core/ # Core modules
│ ├── __init__.py
│ ├── client.py # HTTP client for Luma API
│ ├── config.py # Configuration management
│ ├── exceptions.py # Custom exceptions
│ ├── server.py # MCP server initialization
│ ├── types.py # Type definitions
│ └── utils.py # Utility functions
├── tools/ # MCP tool definitions
│ ├── __init__.py
│ ├── video_tools.py # Video generation tools
│ ├── task_tools.py # Task query tools
│ └── info_tools.py # Information tools
├── prompts/ # MCP prompts
│ └── __init__.py # Prompt templates
├── tests/ # Test suite
│ ├── conftest.py
│ ├── test_client.py
│ ├── test_config.py
│ ├── test_integration.py
│ └── test_utils.py
├── deploy/ # Deployment configs
│ └── production/
│ ├── deployment.yaml
│ ├── ingress.yaml
│ └── service.yaml
├── .env.example # Environment template
├── .gitignore
├── CHANGELOG.md
├── Dockerfile # Docker image for HTTP mode
├── docker-compose.yaml # Docker Compose config
├── LICENSE
├── main.py # Entry point
├── pyproject.toml # Project configuration
└── README.mdAPI Reference
This server wraps the AceDataCloud Luma API:
Luma Videos API - Video generation
Luma Tasks API - Task queries
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch (
git checkout -b feature/amazing)Commit your changes (
git commit -m 'Add amazing feature')Push to the branch (
git push origin feature/amazing)Open a Pull Request
Documentation
License
MIT License - see LICENSE for details.
Links
Made with love by AceDataCloud
Available Tools
8 toolsluma_extend_videoAInspect
Extend an existing video with additional content.
This allows you to continue a previously generated video, adding more motion
and content after the original video ends.
Use this when:
- A generated video is too short and you want to add more
- You want to continue the story or motion from a previous video
- You're building a longer video piece by piece
Returns:
Task ID and the extended video information.
Inputs: prompt (required), video_id (required), callback_url, end_image_url. Returns: result
luma_extend_video_from_urlAInspect
Extend an existing video using its URL.
Similar to luma_extend_video, but uses the video URL instead of video ID.
This is useful when you have the video URL but not the original video ID.
Use this when:
- You have the video URL from a previous generation
- You want to extend a video but don't have the video_id
Returns:
Task ID and the extended video information.
Inputs: prompt (required), video_url (required), callback_url, end_image_url. Returns: result
luma_generate_videoAInspect
Generate AI video from a text prompt using Luma Dream Machine.
This is the simplest way to create video - just describe what you want and Luma
will generate a high-quality AI video.
Use this when:
- You want to create a video from a text description
- You don't have reference images
- You want quick video generation
For using reference images (start/end frames), use luma_generate_video_from_image instead.
Returns:
Task ID and generated video information including URLs, dimensions, and thumbnail.
Inputs: prompt (required), loop, timeout, enhancement, +2 more. Returns: result
luma_generate_video_from_imageAInspect
Generate AI video using reference images as start and/or end frames.
This allows you to control the video by specifying what the first frame
and/or last frame should look like. Luma will generate smooth motion between them.
Use this when:
- You have a specific image you want to animate
- You want to create a video transition between two images
- You need precise control over the video's visual content
At least one of start_image_url or end_image_url must be provided.
Returns:
Task ID and generated video information including URLs, dimensions, and thumbnail.
Inputs: prompt (required), loop, timeout, enhancement, +4 more. Returns: result
luma_get_taskAInspect
Query the status and result of a video generation task.
Use this to check if a generation is complete and retrieve the resulting
video URLs, thumbnails, and other metadata.
Use this when:
- You want to check if a generation has completed
- You need to retrieve video URLs from a previous generation
- You want to get the full details of a generated video
Task states:
- 'pending': Generation is still in progress
- 'completed': Generation finished successfully
- 'failed': Generation failed (check error message)
Returns:
Task status and generated video information including URLs, dimensions, and thumbnail.
Inputs: task_id (required). Returns: result
luma_get_tasks_batchAInspect
Query multiple video generation tasks at once.
Efficiently check the status of multiple tasks in a single request.
More efficient than calling luma_get_task multiple times.
Use this when:
- You have multiple pending generations to check
- You want to get status of several videos at once
- You're tracking a batch of generations
Returns:
Status and video information for all queried tasks.
Inputs: task_ids (required). Returns: result
luma_list_actionsAInspect
List all available Luma API actions and corresponding tools.
Reference guide for what each action does and which tool to use.
Helpful for understanding the full capabilities of the Luma MCP.
Returns:
Categorized list of all actions and their corresponding tools.
Inputs: no named parameters. Returns: result
luma_list_aspect_ratiosAInspect
List all available aspect ratios for Luma video generation.
Shows all available aspect ratio options with their use cases.
Use this to understand which aspect ratio to choose for your video.
Returns:
Table of all aspect ratios with their descriptions and use cases.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools are clearly distinct: generation, image-based generation, status checks, and aspect ratio listing are unambiguous. The only potential confusion is luma_extend_video vs luma_extend_video_from_url, which perform the same operation but differ by input identifier; descriptions help but the overlap could still cause misselection.
All tools follow a consistent luma_<verb>_<object> snake_case pattern. Verbs are predictable (list, get, generate, extend) and names clearly map to their actions, making the set easy to navigate.
Eight tools is well-scoped for a video generation MCP server. Each tool earns its place, covering discovery, generation, extension, and status retrieval without unnecessary redundancy or bloat.
The core video generation lifecycle is covered: generate text-to-video, generate from images, extend videos, and query task status individually or in batch. Minor gaps exist, such as no cancellation or listing of all past tasks, but these are not critical to the primary workflow.
Maintenance
Related MCP Connectors
AI image, video & music generation. Flux, Veo 3.1, Suno V5. Free tier included.
AI image, video, music and speech generation: text-to-video, image-to-video, effects and upscaling.
AI video, images, music & SFX: Seedance 2.5, Veo 3.1, Kling 3.0, Nano Banana Pro, 20+ models.
Generate, extend and edit AI images and videos, then assemble clips on a timeline and render.
Related MCP Servers
- AlicenseAqualityBmaintenanceByteDance Seedance AI video generation with text-to-video, image-to-video, multiple models (1.5 Pro/1.0 Pro/Lite), synchronized audio, and flexible resolutions up to 1080p.7588 PyPI21MIT
- AlicenseAqualityBmaintenanceOpenAI Sora AI video generation with text-to-video, image-to-video, character reuse across scenes, and async webhook callbacks.10137 PyPIMIT
- AlicenseAqualityBmaintenanceGoogle Veo AI video generation with text-to-video, image-to-video, multi-image fusion, 1080p upscaling, and multiple quality/speed models.83MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for 4K video generation using Google VEO 3.1 — text-to-video, image-to-video, video extension, and frame interpolation.3MIT