Metadata-Version: 2.4
Name: veo-mcp-server
Version: 1.1.2
Summary: MCP server for 4K video generation using Google VEO 3.1 -- text-to-video, image-to-video, video extension
Project-URL: Homepage, https://github.com/u2n4/gemini-media-mcp
Project-URL: Repository, https://github.com/u2n4/gemini-media-mcp
Author: u2n4
License-Expression: MIT
Keywords: 4k,ai-video,claude,gemini,mcp,model-context-protocol,text-to-video,veo,video-generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Requires-Dist: google-genai>=1.5.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# VEO 3.1 MCP Server

<!-- mcp-name: io.github.u2n4/veo-mcp-server -->

Professional-grade MCP server for Google VEO 3.1 video generation with async job pattern, API key rotation, and multi-fallback download.

## Quick Install

```bash
pip install veo-mcp-server
# or
uvx veo-mcp-server --help
```

**Claude Desktop (`claude_desktop_config.json`):**

```json
{
  "mcpServers": {
    "veo": {
      "command": "uvx",
      "args": ["veo-mcp-server"],
      "env": {
        "GEMINI_API_KEY": "your_key_here"
      }
    }
  }
}
```

| Variable | Description | Default |
|----------|-------------|---------|
| `GEMINI_API_KEY` | Gemini API key — required for all generation | -- |
| `GEMINI_API_KEY_BACKUP` | Backup key for automatic rotation on 429 | -- |
| `VIDEO_OUTPUT_DIR` | Directory where generated videos are saved | `~/veo-videos` |

## What It Does

Generates AI videos using Google's VEO 3.1 model. Supports text-to-video, image-to-video, video extension, and frame interpolation. Uses an async job pattern where generation starts immediately in the background and returns a job ID for polling.

## Tools (9)

| Tool | Description |
|------|-------------|
| `veo_generate_video` | Generate video from a text prompt. Supports resolution (720p/1080p/4K), aspect ratio (16:9/9:16), duration (4/6/8s), negative prompts, reference images, seed control, and batch generation (1-4 videos). |
| `veo_image_to_video` | Animate a reference image with a text prompt. Supports resolution, aspect ratio, reference images, and seed control. |
| `veo_interpolate_video` | Create a smooth video transition between a first frame and a last frame image. |
| `veo_extend_video` | Extend an existing VEO-generated video by ~7 seconds. 720p only, max 148 seconds total. Source must be from a previous VEO generation (tracks provenance server-side). |
| `veo_check_job` | Check the status of an async video generation job. Call repeatedly until status is 'completed' or 'failed'. |
| `veo_list_jobs` | List all video generation jobs and their current status. |
| `veo_api_status` | Show current API key rotation status — keys configured, active key, keys remaining. |
| `veo_pricing_info` | Show VEO 3.1 pricing per second of generated video for both standard and fast models at all resolutions. |
| `veo_show_output_stats` | Display statistics about generated videos and active/recent jobs. |

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `GEMINI_API_KEY` | Primary Gemini API key (required) | -- |
| `GEMINI_API_KEY_BACKUP` | Backup key for automatic rotation on 429 | -- |
| `VIDEO_OUTPUT_DIR` | Directory where generated videos are saved | `~/veo-videos` |

## Architecture

- **Async Job Pattern**: All generation tools return a job ID instantly. Background threads handle the long-running Google API calls, so each MCP call returns in under 5 seconds.
- **API Key Rotation**: On 429/RESOURCE_EXHAUSTED, automatically switches to the backup key and retries.
- **3-Layer Download Fallback**: SDK download -> URI fallback -> Wait-for-ACTIVE state. Handles Google's Files API edge cases.
- **Preventive Cleanup**: Deletes stuck PROCESSING files before each generation to prevent cascading 500 errors.

## Models

| Tier | Model ID | Use Case |
|------|----------|----------|
| Standard | `veo-3.1-generate-preview` | Higher quality output |
| Fast | `veo-3.1-fast-generate-preview` | Quicker generation |

## License

MIT
