Veo 3.1 MCP Server

# 🚀 Veo 3.1 MCP - Setup Guide ## Prerequisites Before starting, ensure you have: 1. ✅ **Node.js 18+** installed 2. ✅ **Google AI Studio API key** ([Get one here](https://aistudio.google.com/app/apikey)) 3. ✅ **Veo 3.1 enabled** in your Google Cloud project 4. ✅ **Billing enabled** (Veo is a paid API) --- ## Quick Setup (5 Minutes) ### Step 1: Install Dependencies ```bash cd C:\Users\woute\Githubs\MCP\veo-mcp npm install ``` Output should show: ``` ✅ added 106 packages ✅ 0 vulnerabilities ``` ### Step 2: Create Environment File ```bash copy environment.template .env notepad .env ``` Add your API key: ```env GEMINI_API_KEY=your_regenerated_api_key_here DEBUG=false ``` **Important:** Make sure you've regenerated your API key since the original one was exposed in chat! ### Step 3: Build the Project ```bash npm run build ``` Should complete without errors and create `dist/` folder. ### Step 4: Configure Cursor Edit `~/.cursor/mcp.json` or create it if it doesn't exist: **Windows path:** `C:\Users\woute\.cursor\mcp.json` Add this configuration: ```json { "mcpServers": { "veo": { "command": "node", "args": ["C:\\Users\\woute\\Githubs\\MCP\\veo-mcp\\dist\\index.js"], "env": { "GEMINI_API_KEY": "your_api_key_here" } } } } ``` **Important:** Use double backslashes (`\\`) in Windows paths! ### Step 5: Restart Cursor Close and reopen Cursor completely for MCP changes to take effect. ### Step 6: Test It! In Cursor chat, try: ``` @veo estimate_veo_cost { "model": "veo-3.1-fast-generate-001", "durationSeconds": 4, "sampleCount": 1, "generateAudio": false } ``` Should return: ```json { "estimatedCostUsd": 0.40, "unitPricePerSec": 0.10, "secondsBilled": 4, "breakdown": "..." } ``` ✅ **If you see this, setup is complete!** --- ## Enable Veo 3.1 API If you get "403 API not enabled" errors: ### Option 1: Google AI Studio (Easier) 1. Go to https://aistudio.google.com/ 2. Click on your project 3. Navigate to "APIs & Services" 4. Enable "Generative Language API" 5. Enable billing if prompted ### Option 2: Google Cloud Console 1. Go to https://console.cloud.google.com/ 2. Select your project 3. Go to "APIs & Services" → "Library" 4. Search "Generative Language API" 5. Click "Enable" 6. Enable billing in "Billing" section ### Wait for Propagation After enabling, wait **5-10 minutes** for the API to become active. --- ## Test the MCP Server ### Test 1: Cost Estimation (No API Call) ``` @veo estimate_veo_cost { "model": "veo-3.1-fast-generate-001", "durationSeconds": 8, "sampleCount": 1 } ``` Expected: `{"estimatedCostUsd": 0.80, ...}` ✅ This tests the MCP server itself (no API call) ### Test 2: Upload an Image ``` @veo upload_image { "source": "file_path", "filePath": "C:\\Users\\woute\\Githubs\\MCP\\nanobanana-mcp\\Usecaseslide1.png" } ``` Expected: `{"success": true, "file": {"uri": "files/...", ...}}` ✅ This tests Files API integration ### Test 3: Start Video Generation ``` @veo start_video_generation { "prompt": "A peaceful zen garden at sunrise with gentle morning mist", "durationSeconds": 4, "resolution": "720p", "model": "veo-3.1-fast-generate-001" } ``` Expected: `{"operationName": "operations/...", "done": false}` ✅ This starts your first video! ### Test 4: Poll for Completion Wait 60 seconds, then: ``` @veo get_video_job { "operationName": "operations/xyz" } ``` If still running: `{"done": false, "status": "RUNNING"}` Wait another 30s and try again. When done: ```json { "done": true, "status": "SUCCEEDED", "videos": [{ "videoUri": "https://...", "mimeType": "video/mp4" }] } ``` ✅ Copy the `videoUri` and paste in browser to download! --- ## Troubleshooting ### "GEMINI_API_KEY not found" **Fix:** ```bash # Check .env exists dir .env # Verify content type .env # Should show: # GEMINI_API_KEY=AIzaSy... ``` ### "403 Forbidden" or "API not enabled" **Fix:** 1. Enable "Generative Language API" in Cloud Console 2. Enable billing 3. Wait 10 minutes 4. Try again ### "404 Model not found" **Possible causes:** - Veo 3.1 not available in your region - API key project doesn't have access - Model name typo **Fix:** - Check you're using: `veo-3.1-fast-generate-001` or `veo-3.1-generate-001` - Verify Veo 3.1 is enabled for your project ### "Rate limit exceeded (429)" **Fix:** - Wait 60 seconds - Use batch tool with `concurrency: 2-3` - Don't exceed ~50 requests/min ### MCP Server Not Found in Cursor **Fix:** 1. Check `mcp.json` path is correct 2. Use double backslashes: `C:\\path\\to\\file.js` 3. Restart Cursor completely 4. Check MCP logs in Cursor settings ### Generation Takes Forever **Normal:** - 4s video: 30-60 seconds - 8s video: 60-120 seconds - With audio: +30-60 seconds - With references: +10-30 seconds **If > 3 minutes:** - Check Cloud Console for errors - Verify billing is active - Try simpler prompt --- ## Verification Checklist Before using in production, verify: - [ ] `.env` file exists with valid API key - [ ] Project built successfully (`npm run build`) - [ ] `dist/` folder contains `.js` files - [ ] `mcp.json` configured correctly - [ ] Cursor restarted after config change - [ ] Cost estimation works (test 1) - [ ] Image upload works (test 2) - [ ] Video generation starts (test 3) - [ ] Job polling works (test 4) - [ ] Billing enabled in Google Cloud --- ## Next Steps Once setup is complete: 1. **Read the docs:** - `README.md` - Comprehensive guide - `QUICK-REFERENCE.md` - Quick commands - `TOOLS-REFERENCE.md` - Detailed tool documentation 2. **Try examples:** - Simple text-to-video - Video with reference images - Frame interpolation - Video extension 3. **Build workflows:** - Content creation pipelines - Marketing campaigns - Product showcases --- ## Support ### Resources - [Veo 3.1 Docs](https://ai.google.dev/gemini-api/docs/video) - [Google AI Studio](https://aistudio.google.com/) - [Pricing Calculator](https://cloud.google.com/vertex-ai/generative-ai/pricing) - [Files API Guide](https://ai.google.dev/gemini-api/docs/files) ### Common Issues Check `README.md` troubleshooting section for: - API enablement issues - Rate limiting - Cost management - Quality optimization --- **Setup Complete! Start generating amazing videos! 🎬**