# 🎬 Veo 3.1 MCP Server
**Token-Efficient AI Video Generation with Google's Veo 3.1**
## 🎯 What is This?
An MCP server for **Google's Veo 3.1** - the state-of-the-art AI video generation model. Generate stunning videos from text prompts, reference images, or interpolate between first/last frames.
### Key Features
- ✅ **Text-to-Video** - Generate videos from descriptions
- ✅ **Reference Images** - Up to 3 images for style guidance
- ✅ **Frame Interpolation** - First + last frame → coherent video
- ✅ **Video Extension** - Extend Veo-generated videos
- ✅ **Batch Generation** - Generate multiple videos with concurrency control
- ✅ **Cost Estimation** - Know costs before generating
- ✅ **Token-Efficient** - Auto-upload refs to Files API (97% token savings!)
---
## 🚀 Quick Start
### 1. Installation
```bash
cd veo-mcp
npm install
npm run build
```
### 2. Get API Key
1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey)
2. Create API key
3. **Enable Veo 3.1** in your project (billing required)
### 3. Configure
```bash
cp environment.template .env
# Edit .env and add your key
```
### 4. Add to Cursor
Add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"veo": {
"command": "node",
"args": ["C:\\Users\\woute\\Githubs\\MCP\\veo-mcp\\dist\\index.js"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
}
```
Restart Cursor. Done! ✅
---
## 🛠️ Tools
### 1. `start_video_generation` - Generate Video
**Basic text-to-video:**
```json
{
"prompt": "A serene Zen garden at sunrise, cherry blossoms falling, cinematic"
}
```
**With reference images (token-efficient!):**
```json
{
"prompt": "A futuristic cityscape at night, neon lights",
"referenceImages": [{
"source": "url",
"url": "https://example.com/style.jpg"
}],
"durationSeconds": 8,
"resolution": "1080p"
}
```
**First/last frame interpolation:**
```json
{
"prompt": "Smooth transition between these scenes",
"firstFrame": {
"source": "file_path",
"filePath": "C:\\first.jpg"
},
"lastFrame": {
"source": "file_path",
"filePath": "C:\\last.jpg"
}
}
```
**Parameters:**
- `model` - `veo-3.1-generate-001` (quality) or `veo-3.1-fast-generate-001` (speed)
- `durationSeconds` - 4, 6, or 8
- `aspectRatio` - `16:9` or `9:16`
- `resolution` - `720p` or `1080p`
- `generateAudio` - Include synchronized audio (2x cost)
- `seed` - For reproducibility
- `sampleCount` - Generate 1-4 videos
### 2. `get_video_job` - Check Status
```json
{
"operationName": "operations/xyz"
}
```
Returns status and video URLs when complete.
### 3. `upload_image` - Pre-Upload References
```json
{
"source": "file_path",
"filePath": "C:\\style-ref.jpg"
}
```
Returns `fileUri` valid for 48 hours. Reuse across multiple generations!
### 4. `extend_video` - Extend Videos
```json
{
"videoFileUri": "files/abc123",
"additionalSeconds": 7,
"prompt": "Continue with the character walking into the sunset"
}
```
### 5. `start_batch_video_generation` - Batch Generate
```json
{
"jobs": [
{"key": "scene1", "request": {"prompt": "..."}},
{"key": "scene2", "request": {"prompt": "..."}}
],
"concurrency": 3
}
```
### 6. `estimate_veo_cost` - Cost Estimation
```json
{
"model": "veo-3.1-fast-generate-001",
"durationSeconds": 8,
"sampleCount": 1,
"generateAudio": false
}
```
Returns estimated cost in USD.
---
## 💰 Pricing
| Model | Video Only | Video + Audio |
|-------|------------|---------------|
| **veo-3.1-generate-001** (quality) | $0.20/sec | $0.40/sec |
| **veo-3.1-fast-generate-001** (speed) | $0.10/sec | $0.15/sec |
**Example Costs:**
- 8s video (fast, no audio): **$0.80**
- 8s video (quality, with audio): **$3.20**
- 4s video (fast, no audio): **$0.40**
---
## 📊 Limits & Constraints
| Parameter | Limit |
|-----------|-------|
| Duration | 4, 6, or 8 seconds |
| Reference images | 0-3 images |
| Sample count | 1-4 videos |
| Resolutions | 720p, 1080p |
| Aspect ratios | 16:9, 9:16 |
| Rate limit | ~50 requests/min |
---
## 💡 Usage Examples
### Simple Text-to-Video
```
Generate an 8-second video of a peaceful forest scene with morning mist
```
### With Style Reference
```
Create a video of a tech startup office, using this image for style: C:\ref.jpg
```
### Frame Interpolation
```
Generate a smooth transition between first.jpg and last.jpg, 8 seconds, cinematic camera movement
```
### Batch Generation
```
Generate 5 different video variations of a product showcase with different angles
```
---
## 🔍 How Token Efficiency Works
### ❌ Naive Approach (Base64)
```json
{
"referenceImages": [{
"base64": "iVBORw0KGgo..." // 500KB → ~50,000 tokens!
}]
}
```
**Cost:** Massive token usage per call
### ✅ Token-Efficient (This MCP)
```json
{
"referenceImages": [{
"source": "url",
"url": "https://example.com/ref.jpg" // ~20 tokens
}]
}
```
**What Happens:**
1. Server downloads image (no tokens)
2. Computes SHA-256 hash
3. Checks cache (48h validity)
4. Uploads to Files API if needed (~1s)
5. Uses short `files/abc123` URI (~5 tokens)
**Savings:** 97%+ fewer tokens! 🎉
---
## ⏱️ Generation Times
| Configuration | Typical Time |
|---------------|-------------|
| 4s, 720p, no audio | 30-60 sec |
| 8s, 1080p, no audio | 60-120 sec |
| 8s, 1080p, with audio | 90-150 sec |
| With references | +10-30 sec |
| Frame interpolation | +20-40 sec |
**Note:** Times vary based on prompt complexity and server load.
---
## 🎨 Best Practices
### 1. Start Small, Scale Up
```
Step 1: Generate 1 video at 720p
Step 2: If good, regenerate at 1080p
Step 3: Use batch for variations
```
### 2. Use Fast Model for Testing
```json
{
"model": "veo-3.1-fast-generate-001", // Testing
"resolution": "720p"
}
```
Switch to quality model for final:
```json
{
"model": "veo-3.1-generate-001", // Final
"resolution": "1080p"
}
```
### 3. Pre-Upload Frequently Used References
```json
// Step 1: Upload once
upload_image {"source": "file_path", "filePath": "brand-style.jpg"}
// Returns: files/xyz123
// Step 2: Reuse many times
{
"referenceImages": [{"source": "file_uri", "fileUri": "files/xyz123"}]
}
```
### 4. Leverage Batch for Variations
```json
{
"jobs": [
{"key": "v1", "request": {"prompt": "Scene 1...", "seed": 1}},
{"key": "v2", "request": {"prompt": "Scene 1...", "seed": 2}},
{"key": "v3", "request": {"prompt": "Scene 1...", "seed": 3}}
]
}
```
### 5. Monitor Costs
Always estimate before large batches:
```json
estimate_veo_cost {
"model": "veo-3.1-fast-generate-001",
"durationSeconds": 8,
"sampleCount": 10
}
// Returns: $8.00 estimate
```
---
## 🎬 Async Operation Flow
Veo uses async long-running operations:
```
1. start_video_generation
↓ Returns operationName immediately
2. get_video_job (poll every 10-30s)
↓ Returns {done: false, status: "RUNNING"}
3. get_video_job (after 60-120s)
↓ Returns {done: true, videos: [{videoUri: "..."}]}
4. Download video from videoUri
```
**Tip:** Don't poll too frequently (< 10s intervals).
---
## 🆘 Troubleshooting
### "API not enabled" (403)
1. Go to Google Cloud Console
2. Enable "Generative Language API"
3. Enable billing
4. Wait 5-10 minutes for propagation
### "Rate limit exceeded"
- Veo allows ~50 requests/min
- Use batch tool with `concurrency: 3`
- Add delays between requests
### "Invalid aspect ratio with references"
- 9:16 may not work with reference images
- Use 16:9 for reference mode
- Check Veo 3.1 docs for updates
### "Video extension failed"
- Only Veo-generated videos can be extended
- Cannot extend arbitrary MP4s
- Input must be from previous Veo job
### Long generation times
- 1080p takes longer than 720p
- Audio generation adds time
- Reference images add processing
- Frame interpolation is slowest
---
## 📚 Resources
- [Veo 3.1 Documentation](https://ai.google.dev/gemini-api/docs/video)
- [Vertex AI Pricing](https://cloud.google.com/vertex-ai/generative-ai/pricing)
- [Google AI Studio](https://aistudio.google.com/)
- [Files API Guide](https://ai.google.dev/gemini-api/docs/files)
---
## 🎯 Status: Production Ready ✅
- ✅ All 6 tools implemented
- ✅ Token-efficient file handling
- ✅ Async operation support
- ✅ Batch generation with concurrency control
- ✅ Cost estimation
- ✅ Comprehensive validation
- ✅ Error handling
- ✅ Full documentation
**Ready to generate amazing videos!** 🚀
---
**Built with 🎬 for AI video generation**
