videogen-mcp

A unified MCP server for video generation that intelligently routes requests to either HeyGen (for avatar/presenter videos) or Google Veo (for creative/cinematic content).

Generated by GRIMLOCK MCP Factory.

Features

• Intelligent Routing: Automatically selects the best service based on prompt content
• HeyGen Integration: Avatar-based videos, custom voices, templates
• Google Veo Integration: Cinematic content, image-to-video, creative visuals
• Unified Interface: Single generate_video tool with automatic service selection
• Full Control: Direct access to service-specific tools when needed

Installation

# Clone or download the MCP
cd videogen-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -e ".[dev]"

Configuration

Create a .env file with your API keys:

# HeyGen API key from Space Settings > API
HEYGEN_API_KEY=your_heygen_api_key_here

# Google AI Studio API key with Veo access
GEMINI_API_KEY=your_gemini_api_key_here

Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "videogen": {
      "command": "python",
      "args": ["-m", "videogen_mcp.server"],
      "cwd": "/path/to/videogen-mcp",
      "env": {
        "HEYGEN_API_KEY": "your_heygen_key",
        "GEMINI_API_KEY": "your_gemini_key"
      }
    }
  }
}

Or using the installed entry point:

{
  "mcpServers": {
    "videogen": {
      "command": "videogen-mcp",
      "env": {
        "HEYGEN_API_KEY": "your_heygen_key",
        "GEMINI_API_KEY": "your_gemini_key"
      }
    }
  }
}

Available Tools

Unified Interface (3 tools)

Tool	Description
generate_video	Generate video with intelligent routing to HeyGen or Veo
get_video_status	Check job status (works for both services)
download_video	Get download URL for completed video

HeyGen-Specific (6 tools)

Tool	Description
list_avatars	List available avatars (stock + custom)
list_voices	List available voices for avatar videos
create_avatar_video	Create video with specific avatar/voice
list_templates	List available video templates
get_template_details	Get template variables and details
generate_from_template	Generate video from template

Veo-Specific (2 tools)

Tool	Description
generate_creative_video	Generate cinematic video with full Veo controls
generate_video_from_image	Animate a static image into video

Usage Examples

Automatic Routing

"Create a video where someone presents our Q4 results"
→ Routes to HeyGen (presenter/speaking content)

"Cinematic aerial shot of mountains at sunset"
→ Routes to Veo (creative/visual content)

Explicit Service Selection

# Force HeyGen
generate_video(
    prompt="Create any video",
    service_hint="heygen"
)

# Force Veo
generate_video(
    prompt="A tutorial video",
    service_hint="veo"
)

HeyGen Avatar Video

# 1. List avatars and voices
avatars = list_avatars(filter_gender="female")
voices = list_voices(filter_language="en")

# 2. Create video
job = create_avatar_video(
    script="Hello! Welcome to our company.",
    avatar_id="Angela-inblackskirt-20220820",
    voice_id="1bd001e7e50f421d891986aad5158bc8",
    background={"type": "color", "value": "#0066CC"},
    aspect_ratio="16:9"
)

# 3. Poll for completion
status = get_video_status(job_id=job["job_id"], service="heygen")

# 4. Download when complete
result = download_video(job_id=job["job_id"], service="heygen")

Veo Creative Video

# Generate cinematic content
job = generate_creative_video(
    prompt="A slow dolly shot through a neon-lit Tokyo alley at night, rain reflections, cinematic color grading",
    negative_prompt="blurry, low quality, text overlays",
    aspect_ratio="16:9",
    duration=8,
    model="veo-3.1-generate-preview"
)

# Poll and download
status = get_video_status(job_id=job["job_id"], service="veo")
result = download_video(job_id=job["job_id"], service="veo")

Image to Video

# Animate a still image
job = generate_video_from_image(
    image_url="https://example.com/product-photo.jpg",
    prompt="Slow zoom in with subtle product rotation",
    duration=6
)

Routing Logic

The generate_video tool uses keyword detection to route requests:

HeyGen triggers (avatar/presenter content):

• speak, present, explain, tutorial, avatar, host, narrator
• talking, announce, introduce, walk through, demo, spokesperson

Veo triggers (creative/cinematic content):

• cinematic, scene, visual, b-roll, animation, shot, footage
• landscape, abstract, artistic, dramatic, aerial, timelapse

Ambiguous prompts default to Veo unless avatar/presenter language is detected.

Video Wait Times

• HeyGen: 1-5 minutes (varies by content length)
• Veo: 2-10 minutes (varies by complexity)

Poll get_video_status until status is completed or failed.

Error Handling

All tools return structured error objects:

{
  "error": true,
  "code": "QUOTA_EXCEEDED",
  "message": "API credits exhausted. Check your account."
}

Common error codes:

• AUTH_FAILED - Invalid API key
• QUOTA_EXCEEDED - API credits exhausted
• INVALID_AVATAR / INVALID_VOICE - ID not found
• CONTENT_BLOCKED - Safety filter triggered
• VIDEO_NOT_READY - Generation still in progress
• JOB_NOT_FOUND - Invalid job ID

Development

# Run tests
pytest

# Run tests with coverage
pytest --cov=videogen_mcp

# Type checking
mypy src/

# Linting
ruff check src/ tests/

License

MIT License

Credits

• HeyGen API
• Google Veo API
• Generated by GRIMLOCK MCP Factory