Skip to main content
Glama
Sign In
pmind-veo-mcp

pmind-veo-mcp

by piotrkandziora
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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

Related MCP server: Veo 3.1 MCP Server

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

Available Tools

6 tools
veo_check_generationA

Check the status of a video generation subprocess.

This monitors the subprocess that is handling the video generation, not the Gemini API directly. The subprocess handles all API polling.

If the generation has an operation_id, you can also use veo_check_operation to directly query Google's API for the operation status.

Inputs: session_id (required). Returns: object

veo_cleanup_sessionsA

Clean up old generation sessions and their files.

Removes state files and optionally downloaded videos for old sessions.

Inputs: completed_only, older_than_days. Returns: object

veo_download_videoA

Download a generated video from a completed generation session.

Use this tool to:

  • Download videos after generation completes

  • Download a specific video from multiple samples

  • Re-download previously generated videos

Note: Due to current SDK limitations, this downloads placeholder data. The actual video generation API requires allowlist access.

Returns:

  • file_path: Path to the downloaded video file

  • file_size: Size of the downloaded file

  • success: Whether download was successful

Inputs: session_id (required), output_dir, video_index. Returns: object

veo_generate_videoA

Generate videos using Google's Veo models.

Supports:

  • Text-to-video: Provide a text prompt (all models)

  • Image-to-video: Provide an image path (Veo 3 only)

  • Both: Provide both image and prompt for guided animation (Veo 3 only)

This tool starts a background video generation process that:

  1. Initiates video generation with the specified parameters

  2. Monitors progress in the background

To download generated videos, use veo_download_video after generation completes.

Returns:

  • session_id: Use with veo_check_generation to monitor progress

  • status: Current generation status

  • pid: Process ID of the background worker

Examples: Text-to-video: "Serene waterfall in a lush forest, cinematic lighting" Image-to-video: Use image_path="/path/to/image.jpg" with optional prompt

Inputs: fps, seed, model, prompt, +10 more. Returns: object

veo_list_generationsA

List all video generation sessions.

Shows all subprocess-based generation sessions with their current status.

Inputs: active_only. Returns: object

veo_list_sessionsB

List all video generation sessions.

Shows all subprocess-based generation sessions with their current status.

Inputs: active_only. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.8/5.0

    Scored across 6 tools

    Disambiguation2/5

    The tools are mostly distinct, but veo_list_generations and veo_list_sessions have identical descriptions, making them impossible to differentiate. This redundancy creates clear ambiguity for an agent selecting which to use.

    Naming Consistency5/5

    All six tools follow the veo_verb_noun pattern consistently, with clear verbs like generate, check, list, cleanup, and download. There is no mixing of styles or vague naming.

    Tool Count5/5

    With six tools, the server is well-scoped for video generation workflows. The count covers generation, status checking, listing, downloading, and cleanup without being excessive or thin.

    Completeness3/5

    The core lifecycle (generate, check, list, download, cleanup) is covered, but there is no cancel/delete operation, and the description mentions veo_check_operation which is not actually exposed. These gaps could frustrate agents needing abort or granular API status.

    Resources

    Related MCP Connectors

    Related MCP Servers