VideoGenerationMCP

A FastMCP server that gives agents a validated interface to Kling Omni + Seedance 2 video generation (via PiAPI) and ElevenLabs voiceover — with every provider constraint enforced locally (Pydantic) before any paid API call.

Tools

Tool	Purpose
generate_kling_video	Kling Omni single- or multi-shot generation
generate_seedance_video	Seedance 2 generation; auto-chains the Hebrew BVAC lipsync pipeline
generate_seedance_first_last	Seedance first/last-frame interpolation
verify_generated_audio	Scribe QA gate on a finished task's video (async jobs)
generate_elevenlabs_voiceover	ElevenLabs TTS with character-level timestamps
transliterate_hebrew	Hebrew → Latin (LLM-backed) for lipsync prompts
list_voices	List ElevenLabs voices
get_task	Poll any PiAPI task
upload_asset · list_assets · get_asset · delete_asset	PiAPI private asset library (reusable asset:// persona refs)
split_audio	Cut a master voiceover at timestamps → per-clip segments
extract_frame	Grab a frame (default: last) for first/last-frame clip bridging
stitch_videos	Concat clips (normalized) into the final multi-clip ad
trim_video	Frame-accurate cut of a clip to an exact span (re-encode)
retime_video	Stretch/compress a clip to a target duration (PTS, optional interpolation)
mix_narration	Lay a voiceover as primary audio over (silent) video, optional ducked bed
host_file	Host a local file on a temporary public URL (non-persona refs)
burn_captions	Word-timed captions via Scribe (RTL-correct Hebrew) burned onto a video
generate_music	Eleven Music instrumental bed from a text prompt (3–600s)
generate_sound_effect	ElevenLabs Text-to-Sound-Effects ambient/diegetic bed (0.5–30s)
mix_music_into_video	Lay a music bed under speech: low gain + side-chain ducking

Highlights: Hebrew BVAC lipsync (ElevenLabs eleven_v3 → ffmpeg black-video carrier → Seedance omni_reference) with two Scribe audio gates; @-tag reference validation; a content gate (blocks minor/real-person prompts); private-asset support on the less-restriction tier; 720p default (1080p on request).

Requirements

• Python ≥ 3.12 and uv
• ffmpeg on PATH (brew install ffmpeg / apt install ffmpeg)
• PIAPI_KEY and ELEVENLABS_KEY (see .env.example)
• Optional: OPENROUTER_API_KEY (fallback for Hebrew transliteration; primary is a local LMStudio model, default google/gemma-4-e4b)

Connect to Claude Code

No clone needed — uvx installs and runs the server straight from this repo:

claude mcp add video \
  --env PIAPI_KEY=your_piapi_key \
  --env ELEVENLABS_KEY=your_elevenlabs_key \
  --env OPENROUTER_API_KEY=your_openrouter_key \
  -- uvx --from git+https://github.com/AvivK5498/VideoGenerationMCP video-mcp

Or add it to a project .mcp.json:

{
  "mcpServers": {
    "video": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/AvivK5498/VideoGenerationMCP", "video-mcp"],
      "env": { "PIAPI_KEY": "…", "ELEVENLABS_KEY": "…", "OPENROUTER_API_KEY": "…" }
    }
  }
}

Verify with /mcp inside Claude Code.

Connect to Codex

Add to ~/.codex/config.toml:

[mcp_servers.video]
command = "uvx"
args = ["--from", "git+https://github.com/AvivK5498/VideoGenerationMCP", "video-mcp"]
env = { PIAPI_KEY = "…", ELEVENLABS_KEY = "…", OPENROUTER_API_KEY = "…" }

(or codex mcp add video -- uvx --from git+https://github.com/AvivK5498/VideoGenerationMCP video-mcp). Codex MCP servers communicate over stdio; restart Codex to pick up the config.

Local development

git clone [email protected]:AvivK5498/VideoGenerationMCP.git
cd VideoGenerationMCP
uv sync
cp .env.example .env   # fill in PIAPI_KEY + ELEVENLABS_KEY
uv run pytest -q       # 203 tests

Run standalone (stdio): uv run video-mcp. To wire a local checkout instead of the git install, swap the command for uv run --directory /ABSOLUTE/PATH/TO/VideoGenerationMCP video-mcp.

More

• CONTRACT.md — full interface spec for every module.
• samples/payloads.md — ready-to-use tool-call examples.
• scripts/ — live end-to-end drivers used to validate against PiAPI/ElevenLabs.