pmind-veo-mcp

PMIND Veo MCP Server

⚠️ Experimental: This MCP server is in an experimental state and may have rough edges. Please report any issues you encounter.

A Python implementation of an MCP (Model Context Protocol) server using FastMCP that provides tools for generating videos with Google's Veo AI models through the Gemini API. This server uses a subprocess-based architecture for reliable long-running video generation tasks with the official google-genai Python SDK.

🎯 Features

Core Capabilities

• Video Generation: Generate videos from text prompts using Veo models
• Image-to-Video: Animate images with Veo 3 models
• Fast Generation: Veo 3 Fast model for speed-optimized video creation
• Subprocess Architecture: Non-blocking video generation with isolated subprocess handling
• Progress Tracking: Real-time status updates via state file monitoring
• Video Downloads: Download completed videos using the official google-genai SDK
• Multiple Generations: Track and manage multiple concurrent video generations
• Process Management: Graceful cancellation and cleanup of generation processes

Installation & Setup

Step 1: Clone the Repository

git clone https://github.com/yourusername/pmind-veo-mcp.git
cd pmind-veo-mcp

Step 2: Install Dependencies

# Install dependencies using uv
uv sync

Step 3: Set Up API Key

1. Get a Gemini API key from Google AI Studio
2. Create a .env file in the project root:

cp .env.example .env

1. Edit .env and add your configuration:

# Required: Your Gemini API key for Veo access
GEMINI_API_KEY=your_api_key_here

# Required: Default Veo model to use
# Options: veo-2.0-generate-001, veo-3.0-generate-preview, veo-3.0-fast-generate-preview
VEO_MODEL=veo-3.0-generate-preview

# Optional: Configuration directory (default: ~/.pmind-veo-mcp)
# CONFIG_DIR=/path/to/config

Step 4: Configure with Your Client

Add the MCP server to your client's MCP configuration:

{
  "mcpServers": {
    "pmind-veo": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pmind-veo-mcp", "pmind-veo-mcp"]
    }
  }
}

Configuration

Required Environment Variables

• GEMINI_API_KEY: Your Gemini API key with video generation access
• VEO_MODEL: Default model (must be full API name):
• veo-2.0-generate-001 for Veo 2
• veo-3.0-generate-preview for Veo 3
• veo-3.0-fast-generate-preview for Veo 3 Fast (speed-optimized)

Optional Environment Variables

• CONFIG_DIR: Directory for state files and downloads (default: ~/.pmind-veo-mcp)

MCP Tools Reference

• veo_generate_video - Start video generation with a text prompt
• veo_check_generation - Check the status of a video generation
• veo_download_video - Download a completed video
• veo_list_sessions - List all video generation sessions
• veo_cleanup_sessions - Clean up old generation sessions