mcp-video-gen

Features

• 7 video providers — Volcengine Ark Seedance, DashScope/Wan, Kling, SiliconFlow, Vidu, MiniMax, Google Veo (2/3/3.1)

• Image-to-video — generate videos from reference images (Veo)

• TTS — text-to-speech via MiniMax (+ Google Chirp 3 HD with ADC)

• Music generation — MiniMax Music + Google Lyria (instrumental, ~33s, GCP credits)

• Speech-to-text — transcribe audio with word-level timestamps via Google Chirp 2 (for subtitle generation)

• Ark migration ready — Volcengine Ark Seedance is available via ARK_API_KEY / ARK_VIDEO_*

• Provider switching — choose the best provider per request via provider parameter

• Auto-download — generated videos/audio saved to local disk automatically

Architecture

How It Works

User Prompt → AI Assistant (Claude / Cursor) → MCP Server → Provider API
                                                    ↓
                                        generate_video() → task_id
                                        query_video_status(task_id) → download to disk

All video providers use an async pattern: submit a generation request, get a task ID, then poll until complete. The MCP server handles this transparently — the AI assistant calls generate_video, then query_video_status in a loop until the video is ready.

Supported Providers

Video Providers

Provider selection guide

Need a video?
  ├─ Using Volcengine Ark?
  │   └─ ark ✅ (Seedance video task API)
  │
  ├─ Need highest quality?
  │   ├─ minimax (best Chinese provider, paid)
  │   └─ veo (best international, GCP credits)
  │
  ├─ Have GCP credits to spend?
  │   ├─ Budget-conscious → veo-3.0-fast ($0.15/sec, 1080p)
  │   └─ Best quality → veo-2.0 ($0.50/sec) or veo-3.0 ($0.75/sec)
  │
  └─ Need long videos (10s)?
      ├─ dashscope / kling / minimax (support 10s)
      └─ veo max 8s

Audio Providers

Transcription

• MiniMax tools auto-enable when MINIMAX_API_KEY is set

• Google Lyria and STT auto-enable when GCP_PROJECT_ID is set (uses GEMINI_API_KEY)

• Google TTS requires ADC (gcloud auth application-default login)

Quick Start

1. Clone & install

git clone https://github.com/kevinten-ai/mcp-video-gen.git
cd mcp-video-gen
uv sync              # basic deps
uv sync --extra gcp  # add this if using Google Veo

2. Configure MCP

Only configure the providers you want to use. At least one API key is required.

# Minimal Ark setup
claude mcp add -s user mcp-video-gen \
  --env ARK_API_KEY=your_key \
  --env ARK_VIDEO_MODEL=doubao-seedance-2-0-fast-260128 \
  -- uv --directory /path/to/mcp-video-gen run video-gen

# Full (all current providers including Veo)
claude mcp add -s user mcp-video-gen \
  --env ARK_API_KEY=your_key \
  --env KLING_ACCESS_KEY=your_ak \
  --env KLING_SECRET_KEY=your_sk \
  --env MINIMAX_API_KEY=your_key \
  --env GCP_PROJECT_ID=your-project-id \
  --env GEMINI_API_KEY=your_gcp_api_key \
  -- uv --directory /path/to/mcp-video-gen run --extra gcp video-gen

Important: --extra gcp must come after run, not before it. This is a uv run option, not a global uv option.

{
  "mcpServers": {
    "mcp-video-gen": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-video-gen", "run", "--extra", "gcp", "video-gen"],
      "env": {
        "ARK_API_KEY": "your_key",
        "ARK_VIDEO_MODEL": "doubao-seedance-2-0-fast-260128",
        "GCP_PROJECT_ID": "your-project-id",
        "GEMINI_API_KEY": "your_gcp_api_key"
      }
    }
  }
}

3. Use it

Ask your AI assistant to generate a video:

"Generate a video of a cat playing piano"

The assistant will call generate_video, wait, then call query_video_status to download the result.

Tools (7 total)

Video

• generate_video — Text-to-video or image-to-video generation. Params: prompt, provider, duration (5/10), aspect_ratio (16:9/9:16/1:1), image_url (for img2vid, Ark/Veo), model (optional provider model ID).

• query_video_status — Poll generation status and auto-download. Params: task_id, provider.

For Veo image-to-video, reference images may be local files, gs:// URIs, or public HTTP(S) URLs. Localhost, .local, and private/loopback IP-literal URLs are rejected, remote TLS certificates are verified, and reference images are limited to 20 MiB.

Audio

• generate_speech — Text-to-speech. Params: text, provider (minimax/google-tts), voice_id, speed (0.5-2.0).

• generate_music — AI music generation. Params: prompt, provider (minimax/google-lyria), lyrics (optional, supports [Verse]/[Chorus]/[Bridge]).

Transcription

• transcribe_audio — Speech-to-text with word-level timestamps (Google Chirp 2). Params: audio_path, language_code (en-US/cmn-CN/ja-JP/...). Use with ffmpeg add_subtitles for full subtitle pipeline.

Utility

• list_providers — Show all configured video, TTS, music, and STT providers, including default video models.

• resources — Read providers://models/<provider> for a provider model catalog and supported model IDs.

API Key Registration Guide

Steps:

1. Create or reuse a Volcengine Ark API key.

2. Set ARK_API_KEY for shared Ark credentials, or ARK_VIDEO_API_KEY if you want a video-specific key.

3. Optional: set ARK_VIDEO_BASE_URL=https://ark.cn-beijing.volces.com/api/v3.

4. Optional: set ARK_VIDEO_MODEL=doubao-seedance-2-0-fast-260128.

The Ark video provider calls /contents/generations/tasks. It does not use the CodingPlan chat completions endpoint.

Steps:

1. Register at https://www.aliyun.com (phone/email)

2. Go to https://bailian.console.aliyun.com → activate DashScope

3. API-KEY 管理: https://bailian.console.aliyun.com/?apiKey=1#/api-key

4. Click "创建 API Key" → copy (format: sk-xxxxxxxxxxxxxxxx)

Steps:

1. Sign up at https://klingai.com

2. Developer Console: https://app.klingai.com/global/dev/document-api/quickStart/userManual

3. Settings > API Keys → create key pair (Access Key + Secret Key)

Important: 66 daily credits are web-only, NOT for API. API requires purchasing a resource pack.

Steps:

1. Register at https://cloud.siliconflow.cn/account/login (Chinese phone)

2. API Keys: https://cloud.siliconflow.cn/account/ak → "新建 API Key"

3. Copy (format: sk-xxxxxxxxxxxxxxxx)

Video download URLs expire in 10 minutes — the MCP server auto-downloads on query.

Steps:

1. Sign up at https://www.vidu.com → API Platform: https://platform.vidu.com

2. Create API key → copy

API credits are separate from web credits (800/month web credits don't apply to API).

Steps:

1. Register at https://platform.minimaxi.com (Chinese phone)

2. Complete real-name verification (实名认证)

3. Create API key (format: sk-api-xxxxxxxxxxxxxxxx)

4. Top up at billing center (min ~¥10)

Setting MINIMAX_API_KEY also enables TTS and music generation tools.

Prerequisites:

1. GCP project with billing: https://console.cloud.google.com/projectcreate

2. Enable Vertex AI API: https://console.cloud.google.com/apis/library/aiplatform.googleapis.com

3. GCP API Key: https://console.cloud.google.com/apis/credentials

Models:

Auth options:

1. GCP API Key (recommended) — set GEMINI_API_KEY=your_gcp_api_key. Simplest setup, no extra deps.

2. OAuth2 / ADC — run gcloud auth application-default login. Requires --extra gcp for google-auth.

Optional env vars:

Environment Variables

Troubleshooting

Common Errors

Provider-Specific Errors

Veo-Specific Notes

• API Key vs ADC: GEMINI_API_KEY is the simplest auth method. Same key works for both mcp-image-gen and mcp-video-gen.

• --extra gcp placement: Must come after run in the uv command: uv --directory /path run --extra gcp video-gen (NOT uv --directory /path --extra gcp run video-gen)

• Base64 mode: Without VEO_GCS_BUCKET, videos are returned as base64 in the API response and decoded locally. Works well for videos under 8s.

• Cost control: The default is veo-3.1-fast-generate-001 for lower-cost 1080p output. Override VEO_MODEL or pass model to generate_video for a specific request.

Download Issues

Project Structure

src/video_gen/
├── __init__.py
├── server.py              # MCP server + tool handlers
├── providers/
│   ├── __init__.py        # BaseProvider abstract class + registry
│   ├── dashscope.py       # 阿里 通义万相 Wan 2.6
│   ├── kling.py           # 可灵 Kling AI (JWT auth)
│   ├── siliconflow.py     # 硅基流动 SiliconFlow
│   ├── vidu.py            # 生数 Vidu
│   ├── minimax.py         # MiniMax 海螺
│   └── veo.py             # Google Veo (Vertex AI, API key + ADC)
└── audio/
    ├── __init__.py        # BaseTTSProvider + BaseMusicProvider + registry
    ├── minimax_tts.py     # MiniMax TTS (speech-2.6-hd)
    ├── minimax_music.py   # MiniMax Music (music-2.0)
    ├── google_lyria.py    # Google Lyria 2 instrumental music (Vertex AI)
    ├── google_tts.py      # Google Cloud TTS Chirp 3 HD (ADC only)
    └── google_stt.py      # Google Cloud STT Chirp 2 (transcription)

Adding a New Provider

1. Create src/video_gen/providers/your_provider.py

2. Implement BaseProvider (properties: name, description, free_tier_info; methods: generate(), query())

3. Register in server.py:_init_providers() with env var check

4. Provider appears automatically in list_providers, providers://models/<provider>, and the generate_video tool schema

Local Development

git clone https://github.com/kevinten-ai/mcp-video-gen.git
cd mcp-video-gen
uv sync --extra gcp  # all deps including google-auth

# Run directly
uv run video-gen

# Debug with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory . run --extra gcp video-gen

Related Projects

• mcp-image-gen — AI image generation MCP server (Gemini + Imagen)

• mcp-3d-gen — AI 3D model generation MCP server

License

MIT — see LICENSE for details.