mcp-luma

LumaMCP

Model Context Protocol（MCP） を使用し、AceDataCloud API を通じて Luma Dream Machine で AI 動画を生成する 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 のアクションと対応するツールをすべて一覧表示します。

接続方法：ホスト型 OAuth、API トークン、またはローカル stdio

ホスト型エンドポイントは https://luma.mcp.acedata.cloud/mcp です。MCP クライアントに使用する接続方法を 1 つ選択してください。

接続方法	使用する場合	認証情報の設定
ホスト型 OAuth	クライアントがリモート MCP OAuth に対応している場合	URL のみを追加し、AceDataCloud にサインインしてアクセスを承認します。クライアントの設定にトークンを貼り付ける必要はありません。
ホスト型 API トークン	クライアントで OAuth を完了できない場合、または明示的な連携用認証情報が必要な場合	Authorization: Bearer … ヘッダーで AceDataCloud API トークンを送信します。ローカルのシークレットストアまたは環境変数に保存してください。
ローカル stdio	クライアントがローカルの MCP プロセスを実行する場合	mcp-luma をインストールし、そのプロセスに ACEDATACLOUD_API_TOKEN を渡します。この場合も AceDataCloud API を呼び出します。

ホスト型サービスは OAuth メタデータと Dynamic Client Registration（DCR）を提供します。DCR はクライアントアプリケーションを登録するものであり、API キーではありません。 OAuth でサインインすると、クライアントは発行された Bearer トークンを送信します。アカウントの API 認証情報が再利用または新規作成される場合があります。ブラウザーでサインインするには、引き続き AceDataCloud アカウントが必要です。ホスト型サービスは従量課金となる場合があります。実際に操作する前に、最新のサービスドキュメントと表示されている料金を確認してください。同じサーバーに OAuth ログインと固定の Authorization ヘッダーを両方設定しないでください。

ホスト型 OAuth の例

• Claude と Claude Desktop のチャット： Customize → Connectors → Add custom connector からリモートのカスタムコネクターを追加し、https://luma.mcp.acedata.cloud/mcp を入力してサインインを選択します。Claude から OAuth クライアントの登録方法を尋ねられた場合は、Register automatically を選択します。同意手続きを完了してください。Claude Desktop のローカルな claude_desktop_config.json は別途設定が必要です。Claude コネクターガイド。
• Claude Code： claude mcp add --transport http --scope user luma https://luma.mcp.acedata.cloud/mcp を実行し、続けて claude mcp login luma を実行します。/mcp で確認してください。Claude Code MCP ガイド。
• Cursor： https://luma.mcp.acedata.cloud/mcp のみを指定してリモートサーバーを追加します。プロジェクトで使用する場合は、以下のエントリーを <project>/.cursor/mcp.json にマージします。個人用の場合は ~/.cursor/mcp.json を使用します。Cursor MCP ガイド。
• VS Code / Copilot： MCP: Add Server を実行し、HTTP を選択して https://luma.mcp.acedata.cloud/mcp を入力し、ブラウザーでのサインインを完了します。新しいポータブルなワークスペース設定では <project>/.mcp.json を使用します。以下の VS Code 固有の形式では <project>/.vscode/mcp.json またはユーザープロファイルを使用します。MCP: List Servers で確認してください。VS Code MCP のセットアップ。
• Codex： codex mcp add luma --url https://luma.mcp.acedata.cloud/mcp を実行し、続けて codex mcp login luma を実行します。ユーザー設定は ~/.codex/config.toml にあります。Codex 公式 MCP ガイド。

Cursor プロジェクト設定（OAuth）：

{
  "mcpServers": {
    "luma": {"url": "https://luma.mcp.acedata.cloud/mcp"}
  }
}

VS Code 固有のワークスペース設定（OAuth）：

{
  "servers": {
    "luma": {"type": "http", "url": "https://luma.mcp.acedata.cloud/mcp"}
  }
}

ホスト型 API トークン

1. Ace Data Cloud → Applications を開きます。サインインするか、先にアカウントを登録します。
2. General application を探します。まだ作成されていない場合は、Initialize General Application を選択します。汎用キーではアカウントで利用できるサービスを使用できますが、専用アプリケーションのキーはそのサービスに限定されます。必要なサービス／モデルへのアクセス権と現在の料金を確認します。
3. アプリケーションカードから API Key をコピーするか、Keys / Manage Keys → Create を開いて、この連携専用のキーを作成します。個別に失効またはローテーションできるよう、見分けやすい名前を付けます。
4. キーの作成時に、Expiration Time、Set Usage Limitation、Allowed APIs を確認します。必要な制限だけを有効にし、呼び出す操作を許可してから、Create をクリックし、キーの一覧からトークンをコピーします。タスクの照会権限があっても、生成を送信する権限が付与されるわけではありません。最初のリクエストを実行できる残高がアプリケーションにあることを確認します。トライアルの利用枠がある場合、その内容は現在アカウントに表示されているものが適用されます。
5. トークン値だけをコピーします。引用符、空白、Bearer は含めません。API Key／API Token フィールドにはこの値をそのまま入力します。手動で HTTP Authorization ヘッダーを設定する場合に限り、Bearer 接頭辞が必要です。platform-... のアカウント管理トークンを生成 API キーの代わりに使用することはできません。

キーはクライアントの認証情報ストア、または下記の環境変数に保存します。プロンプト、共有ワークフロー、スクリーンショット、Git コミットには絶対に含めないでください。認証に失敗した場合は、別のキーを作成する前に、コピーした値全体、アプリケーション／サービスのアクセス権、有効期限、利用制限、残高を確認してください。

固定の Bearer ヘッダーは OAuth を迂回します。ヘッダーが無効な場合は、ブラウザーでのサインインを試す前に削除してください。保存した認証情報は非公開にしてください。

Claude Code では、サーバーの追加時にシェルがトークンを展開します。保存したユーザー MCP 設定は秘密情報として扱ってください。

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"

Claude Code のプロジェクト設定では、<project>/.mcp.json に変数参照を記述し、Claude Code を起動する環境でその変数を設定します。

{
  "mcpServers": {
    "luma": {
      "type": "http",
      "url": "https://luma.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

Cursor では、~/.cursor/mcp.json またはコミットしないプロジェクト設定に、異なる環境変数構文を使用します。

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

VS Code では、MCP: Open User Configuration を実行し、このサーバーとマスクされた入力をマージします。${input:...} は VS Code のユーザー／ワークスペース形式用であり、Agent Host の .mcp.json 形式では使用できません。

{
  "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}"}
    }
  }
}

Cline では、MCP 設定 UI または CLI ファイル ~/.cline/data/settings/cline_mcp_settings.json を使用します。リモートトランスポートの値は streamableHttp です。JetBrains AI Assistant では、Settings → Tools → AI Assistant → Model Context Protocol (MCP) からリモート URL を追加します。Zed では、OAuth の場合は URL のみを指定する context_servers エントリーを使用するか、ローカルの Bearer ヘッダーを追加します。これらのクライアントでは設定スキーマがそれぞれ異なるため、別のクライアントの JSON をコピーせず、各クライアントの最新の UI に従ってください。Cline · JetBrains · Zed.

ローカル stdio

パッケージをインストールし、ローカルプロセスに API トークンを渡します。

python -m pip install mcp-luma
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
mcp-luma

Claude Desktop のローカル MCP では、開発者設定から開くファイル（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）にこのエントリをマージします。uvx を使用するには、uv が PATH に必要です。

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

このユーザーレベルのファイルは非公開にしてください。セルフホストの HTTP では mcp-luma --transport http --port 8000 を使用し、適切なネットワーク制御と TLS 制御の下でのみ公開してください。ローカルで実行する場合も、AceDataCloud API が呼び出されます。

サービスを使用する前に確認すること

1. https://luma.mcp.acedata.cloud/health が {"status":"ok"} を返す場合、確認できるのはエンドポイントへの到達性のみです。
2. MCP クライアントがツールを読み込むことを確認してください。luma_list_actions は参照用のツールであり、下流 API へのアクセスや残高を確認するものではありません。
3. API を完全に確認する必要がある場合は、最新のサービスドキュメントと表示価格を確認したうえで、有効な入力を使って luma_generate_video を呼び出してください。結果にタスク ID が含まれている場合は、同じ ID に対して luma_get_task を呼び出し、成功または失敗の終端状態になるまで確認してください。進行状況を確認するためだけに操作を再送信しないでください。

401 が発生した場合は、クライアントがどの認証方法を使用したか、トークンまたは OAuth セッションが有効かどうかを確認してください。403 は、アカウントの権限またはコンテンツのモデレーションによる失敗を示している可能性があります。返されたエラーを確認してください。残高不足や下流サービスの障害には、それぞれ個別の診断が必要です。ツールが一覧に表示されていることやタスクが送信されたことは、処理が成功した証明にはなりません。

利用可能なツール

動画生成

ツール	説明
luma_generate_video	テキストプロンプトから動画を生成します
luma_generate_video_from_image	参照画像を使って動画を生成します
luma_extend_video	ID を指定して既存の動画を延長します
luma_extend_video_from_url	URL を指定して既存の動画を延長します

タスク

ツール	説明
luma_get_task	1 件のタスクの状態を照会します
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、テレビ、プレゼンテーション
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 - タスクの照会

コントリビューション

コントリビューションを歓迎します。以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing）
5. プルリクエストを作成します

ドキュメント

ドキュメント

ライセンス

MIT ライセンスです。詳細は LICENSE をご覧ください。

リンク

• AceDataCloud Platform
• Luma Dream Machine
• Model Context Protocol
• MCP Python SDK

---

AceDataCloud が心を込めて作成しました