MCP Veo 3 Azure Blob Video Generator

A powerful Model Context Protocol (MCP) server that provides professional video generation capabilities using Google's state-of-the-art Veo 3 API through the Gemini API, with seamless Azure Blob Storage integration. Generate high-quality 8-second videos with native audio from text prompts or images, and automatically store them in the cloud.

✨ Key Features

• 🎬 Text-to-Video Generation: Create videos from descriptive text prompts
• 🖼️ Image-to-Video Animation: Animate static images with motion prompts
  • 📁 Local Files: Support for local image files (JPG, PNG, GIF, WebP, BMP)
  • 🌐 Online URLs: Direct support for online image URLs
• 🎵 Native Audio: Automatic audio generation with Veo 3 models
• 🎨 Multiple Models: Veo 3, Veo 3 Fast, and Veo 2 support
• ⚡ Real-time Progress: Live progress tracking with detailed status updates
• ☁️ Azure Integration: Automatic upload to Azure Blob Storage
• 🔗 Cloud URLs: Instant access to cloud-hosted videos
• 🗂️ Cloud Management: Complete Azure Blob Storage management tools
• 🛡️ Robust Error Handling: Comprehensive error handling and recovery
• ⏱️ Extended Timeout: 45-minute timeout for complex video generation

Supported Models

Model	Description	Speed	Quality	Audio
veo-3.0-generate-preview	Latest Veo 3 with highest quality	Slower	Highest	✅
veo-3.0-fast-generate-preview	Optimized for speed and business use	Faster	High	✅
veo-2.0-generate-001	Previous generation model	Medium	Good	❌

🚀 Quick Start

Option 1: Install from PyPI (Recommended)

# Install the package
pip install mcp-veo3-azure-blob

# Set up environment variables
export GEMINI_API_KEY='your_gemini_api_key_here'
export AZURE_STORAGE_CONNECTION_STRING='your_azure_connection_string_here'

Option 2: Development Setup

# Clone the repository
git clone https://github.com/ctoicqtao/mcp-veo3-azure-blob
cd mcp-veo3-azure-blob

# Install dependencies
pip install -r requirements.txt

# Set up environment
cp env_example.txt .env
# Edit .env file with your API keys

🔑 API Keys Setup

1. Get Gemini API Key

1. Visit Google AI Studio
2. Create a new API key
3. Copy the key for configuration

2. Set up Azure Blob Storage

1. Go to Azure Portal
2. Create a Storage Account
3. Get the connection string from "Access keys"
4. Create a container for videos (optional - will be auto-created)

Configuration

Environment Variables

Create a .env file with the following variables:

# Required
GEMINI_API_KEY=your_gemini_api_key_here

# Azure Blob Storage (Required for cloud upload)
AZURE_STORAGE_CONNECTION_STRING=your_azure_storage_connection_string_here
AZURE_BLOB_CONTAINER_NAME=generated-videos
AZURE_UPLOAD_ENABLED=true

# 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

Add this to your MCP client configuration file:

{
  "mcpServers": {
    "veo3-azure-blob": {
      "command": "python",
      "args": ["mcp_veo3_azure_blob.py", "--output-dir", "~/Videos/Generated"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}",
        "AZURE_STORAGE_CONNECTION_STRING": "${AZURE_STORAGE_CONNECTION_STRING}",
        "AZURE_BLOB_CONTAINER_NAME": "${AZURE_BLOB_CONTAINER_NAME:-generated-videos}",
        "AZURE_UPLOAD_ENABLED": "${AZURE_UPLOAD_ENABLED:-true}"
      }
    }
  }
}

CLI Arguments:

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

🛠️ Available MCP Tools

1. generate_video

Generate a video from a text prompt with automatic Azure upload.

Parameters:

• prompt (required): Detailed text description of the video
• model (optional): Model to use (default: veo-3.0-generate-preview)

Example:

{
  "prompt": "A cinematic drone shot of a red sports car driving through winding mountain roads at golden hour, with dramatic shadows and warm sunlight filtering through pine trees",
  "model": "veo-3.0-generate-preview"
}

Returns:

{
  "video_path": "/path/to/veo3_video_20250919_151806.mp4",
  "filename": "veo3_video_20250919_151806.mp4",
  "azure_video_url": "https://yourstorageaccount.blob.core.windows.net/generated-videos/veo3_video_20250919_151806.mp4",
  "file_size": 15728640,
  "generation_time": 127.5,
  "azure_upload_success": true
}

2. generate_video_from_image

Animate a static image with motion prompts. Supports both local files and online URLs.

Parameters:

• prompt (required): Description of the desired motion/animation
• image_path (required): Local file path OR online image URL
• model (optional): Model to use (default: veo-3.0-generate-preview)

Supported Image Formats:

• Local files: JPG, PNG, GIF, WebP, BMP, TIFF
• Online URLs: Direct image URLs from any accessible server

Example with local file:

{
  "prompt": "生成一段这个运动员运动的视频，在跑步吧。",
  "image_path": "./images/athlete.jpg",
  "model": "veo-3.0-generate-preview"
}

Example with online URL:

{
  "prompt": "The flowers in the garden gently sway in a warm breeze",
  "image_path": "https://example.com/images/garden.jpg",
  "model": "veo-3.0-fast-generate-preview"
}

3. list_generated_videos

List all locally generated videos.

Parameters:

• output_dir (optional): Directory to scan (default: configured output directory)

Returns: Array of video files with metadata

4. get_video_info

Get detailed information about a specific video file.

Parameters:

• video_path (required): Path to the video file

Returns: Video metadata including size, duration, and creation time

5. upload_video_to_azure

Manually upload a video to Azure Blob Storage.

Parameters:

• video_path (required): Path to video file (relative to output directory)
• blob_name (optional): Custom blob name (defaults to filename)

Example:

{
  "video_path": "veo3_video_20250919_151806.mp4",
  "blob_name": "my_awesome_video.mp4"
}

6. list_azure_blob_videos

List all videos stored in Azure Blob Storage.

Parameters: None

Returns:

{
  "videos": [
    {
      "name": "veo3_video_20250919_151806.mp4",
      "url": "https://storage.blob.core.windows.net/container/video.mp4",
      "size": 15728640,
      "last_modified": "2025-09-19T15:18:06Z"
    }
  ],
  "total_count": 1,
  "total_size": 15728640
}

7. delete_azure_blob_video

Delete a video from Azure Blob Storage.

Parameters:

• blob_name (required): Name of the blob to delete

Example:

{
  "blob_name": "old_video.mp4"
}

💡 Usage Examples

Text-to-Video Generation

# Generate a cinematic video
result = await mcp_client.call_tool("generate_video", {
    "prompt": "A majestic eagle soaring over snow-capped mountains at sunrise, cinematic wide shot with golden lighting",
    "model": "veo-3.0-generate-preview"
})

# Result includes local path and Azure URL
print(f"Video saved locally: {result['video_path']}")
print(f"Azure URL: {result['azure_video_url']}")

Image-to-Video Animation

# Animate a local image
result = await mcp_client.call_tool("generate_video_from_image", {
    "prompt": "The person starts walking forward with confident steps",
    "image_path": "./portrait.jpg",
    "model": "veo-3.0-generate-preview"
})

# Animate from online URL
result = await mcp_client.call_tool("generate_video_from_image", {
    "prompt": "生成一段这个运动员运动的视频，在跑步吧。",
    "image_path": "https://example.com/athlete.jpg",
    "model": "veo-3.0-fast-generate-preview"
})

Azure Blob Management

# List all cloud videos
videos = await mcp_client.call_tool("list_azure_blob_videos", {})
print(f"Found {videos['total_count']} videos in cloud storage")

# Upload a specific video
upload_result = await mcp_client.call_tool("upload_video_to_azure", {
    "video_path": "special_video.mp4",
    "blob_name": "presentation_video.mp4"
})

# Clean up old videos
await mcp_client.call_tool("delete_azure_blob_video", {
    "blob_name": "old_video.mp4"
})

🎨 Prompt Writing Guide

Best Practices

• Be descriptive: Include lighting, mood, camera angles, and atmosphere
• Specify motion: Describe the exact type of movement or action
• Set the scene: Include environmental details and context
• Choose style: Mention cinematic, realistic, animated, artistic styles
• Use active language: Focus on what IS happening, not what isn't

Effective Prompt Examples

Cinematic Shots:

A sweeping drone shot of a lone figure walking across a vast desert at sunset, dramatic golden lighting casting long shadows, cinematic wide-angle perspective

Nature Scenes:

A gentle waterfall cascading over moss-covered rocks in a serene forest, with dappled sunlight filtering through green leaves and creating dancing light patterns

Urban Environments:

A bustling city street at night with neon lights reflecting on wet pavement, people walking with umbrellas, rain creating atmospheric mood lighting

Character Animation:

A person in a cozy café slowly turning pages of a book while steam rises from their coffee cup, warm ambient lighting creating a peaceful atmosphere

⚡ Technical Specifications

Video Output

• Duration: 8 seconds per video
• Resolution: 720p (1280x720) or 1080p (1920x1080)
• Audio: Native audio generation with Veo 3 models
• Format: MP4 with H.264 encoding
• Watermark: SynthID digital watermark included

Performance

• Generation Time: 30 seconds to 10 minutes (depending on complexity)
• Timeout: 45 minutes maximum (3x extended from default)
• Concurrent Requests: Handled asynchronously
• Progress Tracking: Real-time status updates

Storage

• Local: Videos saved to specified output directory
• Cloud: Automatic upload to Azure Blob Storage
• Retention: Google servers store videos for 2 days
• Azure: Permanent storage with configurable retention policies

🚨 Troubleshooting

Common Issues

API Key Problems

# Set environment variable
export GEMINI_API_KEY='your_api_key_here'

# Or add to .env file
echo "GEMINI_API_KEY=your_api_key_here" >> .env

# Verify key is set
echo $GEMINI_API_KEY

Azure Connection Issues

# Check connection string format
echo $AZURE_STORAGE_CONNECTION_STRING

# Test Azure connectivity
python -c "from azure.storage.blob import BlobServiceClient; print('Azure SDK working')"

# Verify container exists in Azure Portal

Video Generation Timeouts

• Use veo-3.0-fast-generate-preview for faster generation
• Current timeout is 45 minutes (3x extended)
• Check network connectivity
• Monitor progress logs for status updates

Image Format Issues

• Supported formats: JPG, PNG, GIF, WebP, BMP, TIFF
• Online URLs must be directly accessible
• Check image file size (recommended < 10MB)
• Verify MIME type detection in logs

Permission Errors

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

# Check file permissions
ls -la ~/Videos/Generated

Error Recovery

The server includes comprehensive error handling:

• Auto-retry: Network failures are automatically retried
• Graceful fallback: Azure upload failures don't stop video generation
• Detailed logging: All operations are logged with request IDs
• Progress tracking: Real-time status updates during generation
• Cleanup: Temporary files are automatically cleaned up
• Validation: Input validation prevents common errors

🔧 Development

Testing

# Test basic functionality
python test_direct_call.py

# Test Azure Blob Storage
python test_azure_blob.py

# Test image URL functionality
python test_url_image.py

Building and Publishing

# Build the package
uv build

# Publish to PyPI
uv publish

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test thoroughly
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📚 Resources

• PyPI Package: https://pypi.org/project/mcp-veo3-azure-blob/
• GitHub Repository: https://github.com/ctoicqtao/mcp-veo3-azure-blob
• MCP Documentation: https://modelcontextprotocol.io/
• Google Veo 3 API: https://ai.google.dev/gemini-api/docs/video
• Azure Blob Storage: https://docs.microsoft.com/en-us/azure/storage/blobs/

📄 License

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

🆘 Support

• API Key Setup: Get your Gemini API key
• Azure Setup: Azure Blob Storage Documentation
• Issues: Report bugs and feature requests in GitHub Issues
• Discussions: Join the conversation in GitHub Discussions

📋 Changelog

v1.0.18 (Current)

• ⏱️ Extended Timeout: Increased default timeout to 45 minutes (3x original) for complex video generation
• 🛡️ Enhanced Error Handling: Improved error recovery and retry mechanisms
• 📊 Better Progress Tracking: More detailed progress updates during generation

v1.0.17

• 🔧 API Format Fix: Fixed Google Gemini API image format issues
• 📥 Download Fix: Corrected video download method for proper file saving
• 🎯 Image Processing: Enhanced image handling with proper MIME type detection

v1.0.16

• 🖼️ Image Format Support: Fixed image-to-video generation with correct API format
• 🌐 URL Image Support: Enhanced support for online image URLs
• 🔄 Improved Retry Logic: Better handling of network failures

v1.0.15

• ☁️ Azure Blob Storage Integration: Complete Azure cloud storage integration
• 🔗 Cloud URLs: Direct access to cloud-hosted videos
• 🗂️ Cloud Management Tools: Full suite of Azure Blob Storage management tools
• 📱 Progress Tracking: Real-time progress updates with detailed status
• 🛡️ Error Recovery: Comprehensive error handling and graceful fallbacks

v1.0.0 - v1.0.14

• Initial releases with core video generation functionality
• Text-to-video and image-to-video generation
• FastMCP framework integration
• Basic file management utilities

---

🚀 Built with FastMCP | 🐍 Python 3.10+ | 📄 MIT License | ☁️ Azure Powered