mcp-veo3-azure-blob 1.0.7

MCP Veo 3 Video Generator - A Model Context Protocol server for Veo 3 video generation and Azure Blob Upload

MCP Veo 3 Video Generation Server with Azure Blob Storage

A Model Context Protocol (MCP) server that provides video generation capabilities using Google's Veo 3 API through the Gemini API, with automatic upload to Azure Blob Storage. Generate high-quality videos from text prompts or images with realistic motion and audio, and store them securely in the cloud.

Features

• 🎬 Text-to-Video: Generate videos from descriptive text prompts
• 🖼️ Image-to-Video: Animate static images with motion prompts (supports local files and online URLs)
• 🎵 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
• ☁️ Azure Blob Storage: Automatic upload to Azure Blob Storage
• 🔗 Cloud URLs: Get direct URLs to your videos in the cloud
• 🗂️ Cloud Management: List, upload, and delete videos in Azure Blob Storage

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	❌

📦 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 keys and Azure:

   • Get your Gemini API key from Google AI Studio
   • Get your Azure Storage connection string from Azure Portal
   • Create .env file: cp env_example.txt .env
   • Edit .env and add your GEMINI_API_KEY and AZURE_STORAGE_CONNECTION_STRING
   • Or set environment variables:

     export GEMINI_API_KEY='your_gemini_key'
     export AZURE_STORAGE_CONNECTION_STRING='your_azure_connection_string'
     

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

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. Supports both local image files and online image URLs.

Parameters:

• prompt (required): Text description of the desired motion/action
• image_path (required): Path to local image file OR URL to online image
• model (optional): Model to use (default: veo-3.0-generate-preview)

Supported Image Sources:

• Local files: ./images/photo.jpg, /absolute/path/image.png
• Online URLs: https://example.com/image.jpg, http://site.com/photo.png

Example with local file:

{
  "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"
}

Example with online URL:

{
  "prompt": "The cat in the image starts playing with a ball of yarn",
  "image_path": "https://example.com/images/cat_sitting.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

5. upload_video_to_azure

Upload a video file to Azure Blob Storage.

Parameters:

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

Example:

{
  "video_path": "veo3_video_20241218_230000.mp4",
  "blob_name": "my_custom_video_name.mp4"
}

6. list_azure_blob_videos

List all videos in Azure Blob Storage container.

Parameters: None

Returns: List of videos with URLs, sizes, and metadata

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": "veo3_video_20241218_230000.mp4"
}

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 Local File

result = await mcp_client.call_tool("generate_video_from_image", {
    "prompt": "The ocean waves gently crash against the shore",
    "image_path": "./beach_scene.jpg",
    "model": "veo-3.0-generate-preview"
})

Image-to-Video with Online URL

result = await mcp_client.call_tool("generate_video_from_image", {
    "prompt": "The flowers in the garden sway gently in the breeze",
    "image_path": "https://example.com/images/garden_flowers.jpg",
    "model": "veo-3.0-generate-preview"
})

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"
})

Azure Blob Storage Management

# List videos in Azure Blob Storage
blob_videos = await mcp_client.call_tool("list_azure_blob_videos", {})

# Upload a specific video to Azure
upload_result = await mcp_client.call_tool("upload_video_to_azure", {
    "video_path": "my_video.mp4",
    "blob_name": "custom_name.mp4"
})

# Delete a video from Azure Blob Storage
delete_result = await mcp_client.call_tool("delete_azure_blob_video", {
    "blob_name": "old_video.mp4"
})

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

"Azure upload failed"

# Check your Azure connection string
echo $AZURE_STORAGE_CONNECTION_STRING

# Test Azure connection
python test_azure_blob.py

# Verify container permissions in Azure Portal

"Azure Storage SDK not available"

# Install Azure Storage SDK
pip install azure-storage-blob>=12.19.0

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
• Azure Connection Errors: Graceful fallback when Azure is not configured
• Azure Upload Failures: Detailed error messages with troubleshooting hints
• Container Creation: Automatic container creation if it doesn't exist

Development

Running Tests

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest tests/

# Test Azure Blob Storage functionality
python test_azure_blob.py

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.2 (Current)

• ☁️ Azure Blob Storage Integration: Automatic upload of generated videos to Azure Blob Storage
• 🔗 Cloud URLs: Get direct URLs to videos stored in Azure Blob Storage
• 🗂️ Cloud Management: New MCP tools for managing videos in Azure Blob Storage
  • upload_video_to_azure: Upload videos to Azure Blob Storage
  • list_azure_blob_videos: List all videos in Azure container
  • delete_azure_blob_video: Delete videos from Azure Blob Storage
• ⚙️ Enhanced Configuration: Added Azure-specific environment variables
• 🧪 Test Suite: Added comprehensive Azure Blob Storage testing script
• 📚 Updated Documentation: Complete Azure setup and usage guide

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