video-mcp

Phase 2a skeleton — stubs only, no live API wiring yet. Live Veo wiring lands in Phase 2a.2.

An async video generation MCP server with multi-provider support.

Status

⚠️ This is a Phase 2a skeleton. All providers return stub responses — fake job IDs that advance from submitted → pending → complete after ~2 seconds of wall-clock time. No real video bytes are generated. Live Veo 3.1 wiring is the next milestone (Phase 2a.2).

Purpose

Provides an MCP interface for async video generation using multiple backend providers. Designed for use with the amplifier-bundle-creative orchestration bundle.

Related Links

• Spec + decisions log: https://github.com/michaeljabbour/amplifier-bundle-creative/blob/main/spec/DECISIONS.md
  • D018: Async pattern — generate_video returns a job_id immediately; callers poll via get_job_status
  • D021: VideoProvider ABC shape (this repo's src/providers/base.py)
• Sibling image MCP: https://github.com/michaeljabbour/imagen-mcp (image generation)

Providers

Provider	Status	Notes
Veo 3.1 Standard	Stub — live wiring pending	$0.40/sec, 4K, best lip-sync
Veo 3.1 Fast	Stub — live wiring pending	$0.15/sec, 1080p, faster iteration
Veo 3.1 Lite	Stub — live wiring pending	$0.05/sec, 720p/1080p, high volume
Grok Imagine Video	Stub only — raises NotImplementedError	D019: xAI DPA/MSA pending
Sora 2 Pro	Stub only — raises NotImplementedError	D010: API EOL 2026-09-24

Stub behavior: Veo stubs return a fake job_id (e.g. stub_veo_standard_abc123). A call to get_job_status with that ID will return status: pending for ~2 seconds, then status: complete with a placeholder output_url. No real video is produced.

Setup

Required environment variables:

Variable	Purpose
GEMINI_API_KEY	Veo 3.1 provider (live wiring pending)

Optional:

Variable	Default	Purpose
XAI_API_KEY	—	Grok Imagine Video (gated — see D019)
OUTPUT_DIR	~/Downloads/videos/	Base output directory
VIDEO_MCP_REQUEST_TIMEOUT	300	Request timeout in seconds
VIDEO_MCP_LOG_PROMPTS	false	Log full prompts to events log

Quickstart

generate_video

Submit a video generation job (returns immediately with a job_id):

{
  "tool": "generate_video",
  "params": {
    "prompt": "A serene mountain lake at golden hour, camera slowly panning right",
    "provider": "veo-3.1-standard",
    "duration": 8.0,
    "aspect_ratio": "16:9"
  }
}

Response:

## ✅ Video Job Submitted

**Provider:** veo-3.1-standard
**Job ID:** `stub_veo_standard_a1b2c3d4e5f6`
**Status:** submitted

### ⏰ Polling Instructions
Call `get_job_status` with job_id `stub_veo_standard_a1b2c3d4e5f6` every ~15 seconds.
Typical completion: 30–120s for live Veo calls (2s for stubs).

get_job_status

Poll for completion:

{
  "tool": "get_job_status",
  "params": {
    "job_id": "stub_veo_standard_a1b2c3d4e5f6"
  }
}

Response (after ~2s with stubs):

## ✅ Video Complete

**Job ID:** `stub_veo_standard_a1b2c3d4e5f6`
**Status:** complete
**Progress:** 100%
**Output URL:** https://stub.example.com/video/stub_veo_standard_a1b2c3d4e5f6.mp4

Project Structure

video-mcp/
├── src/
│   ├── server.py              # MCP entry point — generate_video, get_job_status
│   ├── config/
│   │   ├── constants.py       # VEO_MODELS, STUBBED_PROVIDERS, limits
│   │   ├── settings.py        # Env-var settings (GEMINI_API_KEY, XAI_API_KEY, ...)
│   │   ├── paths.py           # Output path resolution
│   │   └── dotenv.py          # .env loader shim
│   ├── providers/
│   │   ├── base.py            # VideoProvider ABC, VideoCapabilities, VideoJobResult, JobStore
│   │   ├── veo_provider.py    # Veo 3.1 Standard/Fast/Lite stubs
│   │   ├── sora_provider.py   # Sora 2 stub (D010)
│   │   ├── grok_provider.py   # Grok Imagine stub (D019)
│   │   ├── selector.py        # Provider routing (override + default)
│   │   └── registry.py        # Provider factory + JobStore routing
│   ├── models/
│   │   └── input_models.py    # Pydantic models for MCP tools
│   ├── exceptions.py          # VideoError hierarchy
│   └── services/
│       └── logging_config.py  # Structured JSONL event logging
└── tests/
    ├── test_providers.py
    └── test_server.py

Development

# Clone and install
git clone https://github.com/michaeljabbour/video-mcp.git
cd video-mcp
python3 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Verify server loads
python3 -c "from src.server import mcp; print('Server loads OK')"

# Start server (waits for MCP stdio)
python -m src.server

License

MIT