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

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/ for a provider model catalog and supported model IDs.

API Key Registration Guide

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