mcp-veo3 1.0.1
MCP Veo 3 Video Generator - A Model Context Protocol server for Veo 3 video generation
License: MIT
Requires Python: >=3.10
Keywords: ai, fastmcp, gemini, generation, google, mcp, model-context-protocol, veo, video

# 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

| 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

```bash
# 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)
```bash
# No installation needed - run directly with uvx
uvx mcp-veo3 --output-dir ~/Videos/Generated
```

### Option 2: Development Setup
1. **Clone this directory**:
   ```bash
   git clone https://github.com/dayongd1/mcp-veo3
   cd mcp-veo3
   ```

2. **Install with uv**:
   ```bash
   uv sync
   ```
   
   Or use the automated setup:
   ```bash
   python setup.py
   ```

3. **Set up API key**:
   - Get your Gemini API key from [Google AI Studio](https://makersuite.google.com/app/apikey)
   - 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:

```bash
# 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)
```json
{
  "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)
```json
{
  "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
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```python
# 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

```python
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

```python
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"**
```bash
# 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"**
```bash
# Ensure the output directory exists and is writable
mkdir -p ~/Videos/Generated
chmod 755 ~/Videos/Generated
```

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

**"Import errors"**
```bash
# 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

```bash
# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest tests/
```

### Code Formatting

```bash
# 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](https://ai.google.dev/gemini-api/docs/video)
- **API Key**: [Get your Gemini API key](https://makersuite.google.com/app/apikey)
- **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**