dayongd1/mcp-veo3

MCP Veo 3 Video Generation Server

A Model Context Protocol (MCP) server that provides video generation capabilities using Google's Veo 3 API through the Gemini API. Generate high-quality videos from text prompts or images with realistic motion and audio.

Features

• 🎬 Text-to-Video: Generate videos from descriptive text prompts
• 🖼️ Image-to-Video: Animate static images with motion prompts
• 🎵 Audio Generation: Native audio generation with Veo 3 models
• 🎨 Multiple Models: Support for Veo 3, Veo 3 Fast, and Veo 2
• 📐 Aspect Ratios: Widescreen (16:9) and portrait (9:16) support
• ❌ Negative Prompts: Specify what to avoid in generated videos
• 📁 File Management: List and manage generated videos
• ⚡ Async Processing: Non-blocking video generation with progress tracking

Supported Models

📦 Installation Options

# Run without installing (recommended)
uvx mcp-veo3 --output-dir ~/Videos/Generated

# Install globally
pip install mcp-veo3

# Development install
git clone && cd mcp-veo3 && uv sync

Installation

Option 1: Direct Usage (Recommended)

# No installation needed - run directly with uvx
uvx mcp-veo3 --output-dir ~/Videos/Generated

Option 2: Development Setup

1. Clone this directory:

   git clone https://github.com/dayongd1/mcp-veo3
   cd mcp-veo3
   

2. Install with uv:

   uv sync
   

   Or use the automated setup:

   python setup.py
   

3. Set up API key:

   • Get your Gemini API key from Google AI Studio
   • Create .env file: cp env_example.txt .env
   • Edit .env and add your GEMINI_API_KEY
   • Or set environment variable: export GEMINI_API_KEY='your_key'

Configuration

Environment Variables

Create a .env file with the following variables:

# Required
GEMINI_API_KEY=your_gemini_api_key_here

# Optional
DEFAULT_OUTPUT_DIR=generated_videos
DEFAULT_MODEL=veo-3.0-generate-preview
DEFAULT_ASPECT_RATIO=16:9
PERSON_GENERATION=dont_allow
POLL_INTERVAL=10
MAX_POLL_TIME=600

MCP Client Configuration

Option 1: Using uvx (Recommended - after PyPI publication)

{
  "mcpServers": {
    "veo3": {
      "command": "uvx",
      "args": ["mcp-veo3", "--output-dir", "~/Videos/Generated"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option 2: Using uv run (Development)

{
  "mcpServers": {
    "veo3": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-veo3", "mcp-veo3", "--output-dir", "~/Videos/Generated"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option 3: Direct Python

{
  "mcpServers": {
    "veo3": {
      "command": "python",
      "args": ["/path/to/mcp-veo3/mcp_veo3.py", "--output-dir", "~/Videos/Generated"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here"
      }
    }
  }
}

CLI Arguments:

• --output-dir (required): Directory to save generated videos
• --api-key (optional): Gemini API key (overrides environment variable)

Available Tools

1. generate_video

Generate a video from a text prompt.

Parameters:

• prompt (required): Text description of the video
• model (optional): Model to use (default: veo-3.0-generate-preview)
• negative_prompt (optional): What to avoid in the video
• aspect_ratio (optional): 16:9 or 9:16 (default: 16:9)
• output_dir (optional): Directory to save videos (default: generated_videos)

Example:

{
  "prompt": "A close up of two people staring at a cryptic drawing on a wall, torchlight flickering. A man murmurs, 'This must be it. That's the secret code.' The woman looks at him and whispering excitedly, 'What did you find?'",
  "model": "veo-3.0-generate-preview",
  "aspect_ratio": "16:9"
}

2. generate_video_from_image

Generate a video from a starting image and motion prompt.

Parameters:

• prompt (required): Text description of the desired motion/action
• image_path (required): Path to the starting image file
• model (optional): Model to use (default: veo-3.0-generate-preview)
• negative_prompt (optional): What to avoid in the video
• aspect_ratio (optional): 16:9 or 9:16 (default: 16:9)
• output_dir (optional): Directory to save videos (default: generated_videos)

Example:

{
  "prompt": "The person in the image starts walking forward with a confident stride",
  "image_path": "./images/person_standing.jpg",
  "model": "veo-3.0-generate-preview"
}

3. list_generated_videos

List all generated videos in the output directory.

Parameters:

• output_dir (optional): Directory to list videos from (default: generated_videos)

4. get_video_info

Get detailed information about a video file.

Parameters:

• video_path (required): Path to the video file

Usage Examples

Basic Text-to-Video Generation

# Through MCP client
result = await mcp_client.call_tool("generate_video", {
    "prompt": "A majestic waterfall in a lush forest with sunlight filtering through the trees",
    "model": "veo-3.0-generate-preview"
})

Image-to-Video with Negative Prompt

result = await mcp_client.call_tool("generate_video_from_image", {
    "prompt": "The ocean waves gently crash against the shore",
    "image_path": "./beach_scene.jpg",
    "negative_prompt": "people, buildings, artificial structures",
    "aspect_ratio": "16:9"
})

Creative Animation

result = await mcp_client.call_tool("generate_video", {
    "prompt": "A stylized animation of a paper airplane flying through a colorful abstract landscape",
    "model": "veo-3.0-fast-generate-preview",
    "aspect_ratio": "16:9"
})

Prompt Writing Tips

Effective Prompts

• Be specific: Include details about lighting, mood, camera angles
• Describe motion: Specify the type of movement you want
• Set the scene: Include environment and atmospheric details
• Mention style: Cinematic, realistic, animated, etc.

Example Prompts

Cinematic Realism:

A tracking drone view of a red convertible driving through Palm Springs in the 1970s, warm golden hour sunlight, long shadows, cinematic camera movement

Creative Animation:

A stylized animation of a large oak tree with leaves blowing vigorously in strong wind, peaceful countryside setting, warm lighting

Dialogue Scene:

Close-up of two people having an intense conversation in a dimly lit room, dramatic lighting, one person gesturing emphatically while speaking

Negative Prompts

Describe what you don't want to see:

• ❌ Don't use "no" or "don't": "no cars"
• ✅ Do describe unwanted elements: "cars, vehicles, traffic"

Limitations

• Generation Time: 11 seconds to 6 minutes depending on complexity
• Video Length: 8 seconds maximum
• Resolution: 720p output
• Storage: Videos are stored on Google's servers for 2 days only
• Regional Restrictions: Person generation defaults to "dont_allow" in EU/UK/CH/MENA
• Watermarking: All videos include SynthID watermarks

🚨 Troubleshooting

"API key not found"

# Set your Gemini API key
export GEMINI_API_KEY='your_api_key_here'
# Or add to .env file
echo "GEMINI_API_KEY=your_api_key_here" >> .env

"Output directory not accessible"

# Ensure the output directory exists and is writable
mkdir -p ~/Videos/Generated
chmod 755 ~/Videos/Generated

"Video generation timeout"

# Try using the fast model for testing
uvx mcp-veo3 --output-dir ~/Videos
# Then use: model="veo-3.0-fast-generate-preview"

"Import errors"

# Install/update dependencies
uv sync
# Or with pip
pip install -r requirements.txt

Error Handling

The server handles common errors gracefully:

• Invalid API Key: Clear error message with setup instructions
• File Not Found: Validation for image paths in image-to-video
• Generation Timeout: Configurable timeout with progress updates
• Model Errors: Fallback error handling with detailed messages

Development

Running Tests

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest tests/

Code Formatting

# Format code
black mcp_veo3.py

# Check linting
flake8 mcp_veo3.py

# Type checking
mypy mcp_veo3.py

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📚 Links

• PyPI: https://pypi.org/project/mcp-veo3/
• GitHub: https://github.com/dayongd1/mcp-veo3
• MCP Docs: https://modelcontextprotocol.io/
• Veo 3 API: https://ai.google.dev/gemini-api/docs/video

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: Google Veo 3 API Docs
• API Key: Get your Gemini API key
• Issues: Report bugs and feature requests in the GitHub issues

Changelog

v1.0.1

• 🔧 API Fix: Updated to match official Veo 3 API specification
• Removed unsupported parameters: aspect_ratio, negative_prompt, person_generation
• Simplified API calls: Now using only model and prompt parameters as per official docs
• Fixed video generation errors: Resolved "unexpected keyword argument" issues
• Updated documentation: Added notes about current API limitations

v1.0.0

• Initial release
• Support for Veo 3, Veo 3 Fast, and Veo 2 models
• Text-to-video and image-to-video generation
• FastMCP framework with progress tracking
• Comprehensive error handling and logging
• File management utilities
• uv/uvx support for easy installation

Built with FastMCP | Python 3.10+ | MIT License