Mcp Video Gen

mcp-video-gen

Multi-provider AI video, speech, music & transcription MCP server. 7 video providers + image-to-video + TTS + music + STT — one unified interface. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

中文文档

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 | Model | Free Tier | Quality | Duration | Best for | |---|---|---|---|---|---| | Volcengine Ark Seedance | doubao-seedance-2.0 | Paid video API | 720p+ | 5-10s | Ark migration, Doubao/Seedance workflows | | DashScope / Wan (通义万相) | wan2.6-t2v | 50s free (90 days) | Up to 1080P | 5-10s | High quality, Chinese content | | Kling AI (可灵) | kling-v2-master | 66 credits/day (web only) | 720p | 5-10s | Good quality, daily free credits | | SiliconFlow (硅基流动) | Wan2.1-T2V-14B | $1 signup bonus | 720p | varies | Quick testing | | Vidu (生数科技) | vidu-2.0 | 200 promo credits | 720p | 4s | Short clips | | MiniMax Hailuo (海螺) | Hailuo 2.3 | Paid | Up to 1080P | 6-10s | Highest quality | | Google Veo (Vertex AI) | veo-2.0/3.0/3.1 | GCP credits | 720p-4K | 5-8s | Production quality, GCP users |

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

| Provider | Capability | Model | Pricing | Env Var | |---|---|---|---|---| | MiniMax TTS | Text-to-Speech | speech-2.6-hd | ~¥0.01/req | MINIMAX_API_KEY | | Google TTS | Text-to-Speech | Chirp 3 HD (52 languages) | ~$30/1M chars | ADC only | | MiniMax Music | Music Generation (with lyrics) | music-2.0 | ~¥0.1/song | MINIMAX_API_KEY | | Google Lyria | Instrumental Music | lyria-002 (~33s WAV) | ~$0.06/clip | GCP_PROJECT_ID |

Transcription

| Provider | Capability | Model | Pricing | Env Var | |---|---|---|---|---| | Google STT | Speech-to-Text + timestamps | Chirp 2 | ~$0.016/min | GCP_PROJECT_ID |

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

Claude Code (CLI) — recommended

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

Claude Desktop / Cursor (JSON config)

{
  "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).
• queryvideostatus — 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/ for a provider model catalog and supported model IDs.

API Key Registration Guide

1. Volcengine Ark Seedance — Recommended Ark migration path

| Item | Detail | |---|---| | Platform | Volcengine Ark | | URL | https://console.volcengine.com/ark | | Pricing | Ark video generation billing; may not be covered by CodingPlan chat quota | | Env Var | ARK_API_KEY or ARK_VIDEO_API_KEY |

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.

1. DashScope / Wan (通义万相) — 50s Free

| Item | Detail | |---|---| | Platform | 阿里云百炼 (Alibaba Bailian) | | URL | https://bailian.console.aliyun.com | | Free Tier | 50 seconds free (valid 90 days) | | Env Var | DASHSCOPE_API_KEY |

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)

1. Kling AI (可灵) — 66 Credits/Day

| Item | Detail | |---|---| | Platform | Kling AI Developer Platform | | URL | https://klingai.com/global/dev | | Free Tier | 66 credits/day (web only); API requires purchased resource pack | | Env Vars | KLING_ACCESS_KEY, KLING_SECRET_KEY |

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.

1. SiliconFlow (硅基流动) — $1 Signup Bonus

| Item | Detail | |---|---| | Platform | SiliconFlow | | URL | https://siliconflow.cn | | Free Tier | $1 bonus (~3 videos at $0.29/video) | | Env Var | SILICONFLOW_API_KEY |

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.

1. Vidu (生数科技) — Promotional Credits

| Item | Detail | |---|---| | Platform | Vidu Platform | | URL | https://platform.vidu.com | | Free Tier | Apply for 200 free API credits (promotional) | | Env Var | VIDU_API_KEY |

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

1. MiniMax Hailuo (海螺) — Paid (Best Quality)

| Item | Detail | |---|---| | Platform | MiniMax Open Platform | | URL | https://platform.minimaxi.com | | Free Tier | None. ~¥0.7/video (512P 6s) to ~¥3.7/video (1080P 6s) | | Env Vars | MINIMAX_API_KEY, MINIMAX_API_HOST (optional) |

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.

1. Google Veo (Vertex AI) — GCP Credits

| Item | Detail | |---|---| | Platform | Google Cloud Vertex AI | | URL | https://console.cloud.google.com | | Free Tier | No free tier. Uses GCP credits/billing. | | Env Vars | GCP_PROJECT_ID, GEMINI_API_KEY (recommended) |

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:

| Model | Resolution | Pricing | Best for | |---|---|---|---| | veo-2.0-generate-001 | 720p | ~$0.50/sec | Stable, GA | | veo-3.0-generate-001 | 1080p | ~$0.75/sec | High quality | | veo-3.0-fast-generate-001 | 1080p | ~$0.15/sec | Cost-effective | | veo-3.1-generate-001 | 4K | ~$0.75/sec | Highest quality | | veo-3.1-fast-generate-001 (default) | 1080p | ~$0.10/sec | Best value ✅ |

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:

| Variable | Default | Description | |---|---|---| | VEO_MODEL | veo-3.1-fast-generate-001 | Model to use | | VEO_GCS_BUCKET | — | GCS bucket for output (omit for base64 inline) | | GCP_REGION | us-central1 | Vertex AI region | | GEMINI_API_KEY | — | GCP API key (shared with mcp-image-gen) |

Environment Variables

| Variable | Provider | Required | |---|---|---| | ARK_API_KEY | Volcengine Ark Seedance | At least one provider | | ARK_VIDEO_API_KEY | Volcengine Ark Seedance | Optional video-specific override | | ARK_VIDEO_BASE_URL | Volcengine Ark Seedance | Optional, default: https://ark.cn-beijing.volces.com/api/v3 | | ARK_VIDEO_MODEL | Volcengine Ark Seedance | Optional, default: doubao-seedance-2-0-fast-260128 | | ARK_VIDEO_RESOLUTION | Volcengine Ark Seedance | Optional, default: 720p | | DEFAULT_VIDEO_PROVIDER | All providers | Optional, default prefers ark when configured | | DASHSCOPE_API_KEY | Wan / DashScope (阿里) | must be configured | | KLING_ACCESS_KEY | Kling AI (可灵) | | | KLING_SECRET_KEY | Kling AI (可灵) | | | SILICONFLOW_API_KEY | SiliconFlow (硅基流动) | | | VIDU_API_KEY | Vidu (生数) | | | MINIMAX_API_KEY | MiniMax (海螺 + TTS + Music) | | | MINIMAX_API_HOST | MiniMax | Optional, default: https://api.minimax.chat | | GCP_PROJECT_ID | Google Veo | Required for Veo | | GEMINI_API_KEY | Google Veo | Recommended for Veo (or use ADC) | | GCP_REGION | Google Veo | Optional, default: us-central1 | | VEO_MODEL | Google Veo | Optional, default: veo-3.1-fast-generate-001 | | VEO_GCS_BUCKET | Google Veo | Optional, GCS bucket for video output | | VIDEO_OUTPUT_DIR | All providers | Optional, default: ./output |

Troubleshooting

Common Errors

| Error | Provider | Root Cause | Solution | |---|---|---|---| | No providers configured | All | No API keys set | Set at least one provider's API key in MCP env config | | Unknown provider: xxx | All | Typo or provider not configured | Check list_providers for available options | | Still processing | All | Video not ready yet | Normal — call query_video_status again in 30 seconds |

Provider-Specific Errors

| Error | Provider | Solution | |---|---|---| | JWT token error | Kling | Check both KLING_ACCESS_KEY and KLING_SECRET_KEY are set | | base_resp.status_code != 0 | MiniMax | Check API key, ensure account has balance | | Auth failed: credentials not found | Veo | Set GEMINI_API_KEY or run gcloud auth application-default login | | 429 quota exceeded | Veo | Vertex AI rate limit (10 RPM). Wait 1 min or switch model via VEO_MODEL | | Video blocked by safety filter | Veo | Content flagged — rephrase prompt to avoid restricted content |

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

| Issue | Solution | |---|---| | Auto-download failed | Video URL may have expired. SiliconFlow URLs expire in 10 min. | | Video file is 0 bytes | Provider returned empty response. Retry generation. | | SSL verification errors | Server disables SSL verify for downloads (some providers use self-signed certs) |

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)

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kevinten-ai](https://github.com/kevinten-ai)
- **Source:** [kevinten-ai/mcp-video-gen](https://github.com/kevinten-ai/mcp-video-gen)
- **License:** MIT

Install and usage instructions live in the source repository linked above.