LumaMCP

Name: LumaMCP
Author: AceDataCloud

PyPI version PyPI downloads Python 3.10+ License: MIT MCP

AceDataCloud API를 통해 Luma Dream Machine을 사용하는 Model Context Protocol (MCP) 서버입니다.

Claude, VS Code 또는 MCP 호환 클라이언트에서 직접 AI 비디오를 생성하세요.

기능

텍스트-비디오 - 텍스트 프롬프트로 AI 생성 비디오 제작
이미지-비디오 - 시작/종료 프레임 제어로 이미지 애니메이션화
비디오 확장 - 기존 비디오에 콘텐츠 추가
다양한 화면 비율 - 16:9, 9:16, 1:1 등 지원
루프 비디오 - 끊김 없는 루프 애니메이션 생성
선명도 향상 - 선택적 비디오 품질 향상
작업 추적 - 생성 진행 상황 모니터링 및 결과 검색

도구 참조

도구	설명
`luma_generate_video`	Luma Dream Machine을 사용하여 텍스트 프롬프트로 AI 비디오 생성.
`luma_generate_video_from_image`	참조 이미지를 시작/종료 프레임으로 사용하여 AI 비디오 생성.
`luma_extend_video`	기존 비디오에 콘텐츠 추가.
`luma_extend_video_from_url`	URL을 사용하여 기존 비디오 확장.
`luma_get_task`	비디오 생성 작업의 상태 및 결과 조회.
`luma_get_tasks_batch`	여러 비디오 생성 작업을 한 번에 조회.
`luma_list_aspect_ratios`	Luma 비디오 생성에 사용 가능한 모든 화면 비율 나열.
`luma_list_actions`	사용 가능한 모든 Luma API 작업 및 해당 도구 나열.

빠른 시작

1. API 토큰 받기

AceDataCloud 플랫폼에 가입하세요.
API 문서 페이지로 이동하세요.
**"Acquire"**를 클릭하여 API 토큰을 받으세요.
아래에서 사용할 토큰을 복사하세요.

2. 호스팅 서버 사용 (권장)

AceDataCloud는 관리형 MCP 서버를 호스팅하므로 로컬 설치가 필요 없습니다.

엔드포인트: https://luma.mcp.acedata.cloud/mcp

모든 요청에는 Bearer 토큰이 필요합니다. 1단계에서 받은 API 토큰을 사용하세요.

Claude.ai

OAuth를 사용하여 Claude.ai에 직접 연결하세요 (API 토큰 불필요):

Claude.ai 설정 → 통합 → 더 추가하기로 이동하세요.
서버 URL 입력: https://luma.mcp.acedata.cloud/mcp
OAuth 로그인 절차를 완료하세요.
대화에서 도구 사용을 시작하세요.

Claude Desktop

설정 파일에 추가하세요 (~/Library/Application Support/Claude/claude_desktop_config.json - macOS 기준):

{
  "mcpServers": {
    "luma": {
      "type": "streamable-http",
      "url": "https://luma.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Cursor / Windsurf

MCP 설정에 추가하세요 (.cursor/mcp.json 또는 .windsurf/mcp.json):

{
  "mcpServers": {
    "luma": {
      "type": "streamable-http",
      "url": "https://luma.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

VS Code (Copilot)

VS Code MCP 설정에 추가하세요 (.vscode/mcp.json):

{
  "servers": {
    "luma": {
      "type": "streamable-http",
      "url": "https://luma.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

또는 VS Code용 Ace Data Cloud MCP 확장을 설치하세요. 15개의 MCP 서버가 번들로 제공되어 클릭 한 번으로 설정할 수 있습니다.

JetBrains IDEs

**설정 → 도구 → AI Assistant → Model Context Protocol (MCP)**로 이동하세요.
추가 → HTTP를 클릭하세요.
다음을 붙여넣으세요:

{
  "mcpServers": {
    "luma": {
      "url": "https://luma.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Claude Code

Claude Code는 MCP 서버를 기본적으로 지원합니다:

claude mcp add luma --transport http https://luma.mcp.acedata.cloud/mcp \
  -h "Authorization: Bearer YOUR_API_TOKEN"

또는 프로젝트의 .mcp.json에 추가하세요:

{
  "mcpServers": {
    "luma": {
      "type": "streamable-http",
      "url": "https://luma.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Cline

Cline의 MCP 설정에 추가하세요 (.cline/mcp_settings.json):

{
  "mcpServers": {
    "luma": {
      "type": "streamable-http",
      "url": "https://luma.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Amazon Q Developer

MCP 구성에 추가하세요:

{
  "mcpServers": {
    "luma": {
      "type": "streamable-http",
      "url": "https://luma.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Roo Code

Roo Code MCP 설정에 추가하세요:

{
  "mcpServers": {
    "luma": {
      "type": "streamable-http",
      "url": "https://luma.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Continue.dev

.continue/config.yaml에 추가하세요:

mcpServers:
  - name: luma
    type: streamable-http
    url: https://luma.mcp.acedata.cloud/mcp
    headers:
      Authorization: "Bearer YOUR_API_TOKEN"

Zed

Zed 설정에 추가하세요 (~/.config/zed/settings.json):

{
  "language_models": {
    "mcp_servers": {
      "luma": {
        "url": "https://luma.mcp.acedata.cloud/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_TOKEN"
        }
      }
    }
  }
}

cURL 테스트

# Health check (no auth required)
curl https://luma.mcp.acedata.cloud/health

# MCP initialize
curl -X POST https://luma.mcp.acedata.cloud/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

3. 로컬 실행 (대안)

서버를 자신의 컴퓨터에서 실행하려면:

# Install from PyPI
pip install mcp-luma
# or
uvx mcp-luma

# Set your API token
export ACEDATACLOUD_API_TOKEN="your_token_here"

# Run (stdio mode for Claude Desktop / local clients)
mcp-luma

# Run (HTTP mode for remote access)
mcp-luma --transport http --port 8000

Claude Desktop (로컬)

{
  "mcpServers": {
    "luma": {
      "command": "uvx",
      "args": ["mcp-luma"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_token_here"
      }
    }
  }
}

Docker (셀프 호스팅)

docker pull ghcr.io/acedatacloud/mcp-luma:latest
docker run -p 8000:8000 ghcr.io/acedatacloud/mcp-luma:latest

클라이언트는 자신의 Bearer 토큰으로 연결하며, 서버는 각 요청의 Authorization 헤더에서 토큰을 추출합니다.

사용 가능한 도구

비디오 생성

도구	설명
`luma_generate_video`	텍스트 프롬프트로 비디오 생성
`luma_generate_video_from_image`	참조 이미지를 사용하여 비디오 생성
`luma_extend_video`	ID로 기존 비디오 확장
`luma_extend_video_from_url`	URL로 기존 비디오 확장

작업

도구	설명
`luma_get_task`	단일 작업 상태 조회
`luma_get_tasks_batch`	여러 작업 한 번에 조회

정보

도구	설명
`luma_list_aspect_ratios`	사용 가능한 화면 비율 나열
`luma_list_actions`	사용 가능한 API 작업 나열

사용 예시

프롬프트로 비디오 생성

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"]

이미지 애니메이션화

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]

비디오 확장

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]

사용 가능한 화면 비율

화면 비율	설명	사용 사례
`16:9`	가로형 (기본값)	YouTube, TV, 프레젠테이션
`9:16`	세로형	TikTok, Instagram Reels
`1:1`	정사각형	Instagram 게시물
`4:3`	전통적	클래식 비디오 형식
`3:4`	전통적 세로형	세로형 콘텐츠
`21:9`	울트라와이드	영화 같은 콘텐츠
`9:21`	긴 울트라와이드	특수 세로 디스플레이

구성

환경 변수

변수	설명	기본값
`ACEDATACLOUD_API_TOKEN`	AceDataCloud API 토큰	필수
`ACEDATACLOUD_API_BASE_URL`	API 기본 URL	`https://api.acedata.cloud`
`ACEDATACLOUD_OAUTH_CLIENT_ID`	OAuth 클라이언트 ID (호스팅 모드)	—
`ACEDATACLOUD_PLATFORM_BASE_URL`	플랫폼 기본 URL	`https://platform.acedata.cloud`
`LUMA_DEFAULT_ASPECT_RATIO`	기본 화면 비율	`16:9`
`LUMA_REQUEST_TIMEOUT`	요청 시간 제한 (초)	`1800`
`LOG_LEVEL`	로그 수준	`INFO`

명령줄 옵션

mcp-luma --help

Options:
  --version          Show version
  --transport        Transport mode: stdio (default) or http
  --port             Port for HTTP transport (default: 8000)

개발

개발 환경 설정

# 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 unit tests
pytest

# Run with coverage
pytest --cov=core --cov=tools

# Run integration tests (requires API token)
pytest tests/test_integration.py -m integration

코드 품질

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy core tools

빌드 및 배포

# Install build dependencies
pip install -e ".[release]"

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

프로젝트 구조

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.md

API 참조

이 서버는 AceDataCloud Luma API를 래핑합니다:

Luma Videos API - 비디오 생성
Luma Tasks API - 작업 쿼리

기여

기여를 환영합니다! 다음 절차를 따라주세요:

저장소 포크
기능 브랜치 생성 (git checkout -b feature/amazing)
변경 사항 커밋 (git commit -m 'Add amazing feature')
브랜치 푸시 (git push origin feature/amazing)
Pull Request 열기

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE를 참조하세요.

링크

AceDataCloud에서 사랑을 담아 제작함