Video MCP Server

A Model Context Protocol (MCP) server for video understanding powered by Google Gemini. Analyze YouTube videos and local video files through natural language prompts.

Features

• YouTube Videos: Analyze public YouTube videos directly via URL
• Local Files: Process local video files (mp4, webm, mov, avi, etc.)
• Video Clipping: Focus on specific sections using start/end offsets
• Custom FPS: Adjust frame sampling rate for different use cases
• Multimodal Analysis: Gemini processes both visual and audio content

Quick Start

# Install dependencies
bun install

# Set your Gemini API key
export GEMINI_API_KEY="your-api-key"

# Optional: Allow local file access (comma-separated paths)
export VIDEO_PATHS="/path/to/videos,/another/path"

# Run in development mode
bun run dev

# Test with MCP Inspector
bun run inspector

Configuration

Variable	Default	Description
GEMINI_API_KEY	required	Google Gemini API key
GEMINI_MODEL	gemini-3-flash-preview	Gemini model to use
VIDEO_PATHS	(empty)	Comma-separated allowed paths for local files. If not set, local file access is disabled.
MCP_NAME	video-mcp	Server name
MCP_VERSION	1.0.0	Server version
LOG_LEVEL	info	Log level: debug, info, warning, error

Local File Security

Local file access is disabled by default. To enable it, set VIDEO_PATHS to a comma-separated list of directories where video files can be read from:

# Single directory
export VIDEO_PATHS="/home/user/videos"

# Multiple directories
export VIDEO_PATHS="/home/user/videos,/shared/media,/tmp/uploads"

Files outside these directories will be rejected with a FORBIDDEN error.

Tools

video_understand

Analyze and understand video content.

Parameters:

Parameter	Type	Required	Description
source	string	Yes	YouTube URL or local file path
prompt	string	Yes	What to analyze/ask about the video
startOffset	number	No	Start time in seconds (for clipping)
endOffset	number	No	End time in seconds (for clipping)
fps	number	No	Frame rate sampling (default: 1fps)

Examples:

// Summarize a YouTube video
{
  "source": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "prompt": "Summarize this video in 3 sentences."
}

// Ask about a specific timestamp
{
  "source": "https://www.youtube.com/watch?v=example",
  "prompt": "What happens at 01:30?"
}

// Analyze a portion of a local video
{
  "source": "/path/to/video.mp4",
  "prompt": "Describe what's happening",
  "startOffset": 60,
  "endOffset": 120
}

// High FPS for action sequences
{
  "source": "/path/to/action.mp4",
  "prompt": "Describe the fast action sequence in detail",
  "fps": 5
}

Prompts

video_summary

Generate a video summary prompt.

Arguments:

• source: YouTube URL or local file path
• style: brief, detailed, or bullet_points
• includeTimestamps: Include timestamps for key moments

video_qa

Generate a Q&A prompt for video content.

Arguments:

• source: YouTube URL or local file path
• questions: Array of questions to answer

Resources

config://server

Current server configuration (model, version, etc.)

config://formats

Supported video formats and limitations.

Supported Formats

Extension	MIME Type	Description
.mp4	video/mp4	MPEG-4 Part 14
.webm	video/webm	WebM Video
.mov	video/mov	QuickTime Movie
.avi	video/avi	Audio Video Interleave
.mpeg / .mpg	video/mpeg	MPEG Video
.flv	video/x-flv	Flash Video
.wmv	video/wmv	Windows Media Video
.3gp	video/3gpp	3GPP Multimedia

Limitations

• YouTube: Public videos only, max 8 hours/day (free tier)
• Local files: Up to 1 hour at default resolution
• File size: Files >20MB are uploaded to Gemini's Files API
• Frame rate: Default 1 FPS (configurable)
• Tokens: ~300 tokens/second (default) or ~100 tokens/second (low resolution)

Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "video-mcp": {
      "command": "bun",
      "args": ["run", "/path/to/video-mcp/src/index.ts"],
      "env": {
        "GEMINI_API_KEY": "your-api-key",
        "VIDEO_PATHS": "/home/user/videos,/shared/media"
      }
    }
  }
}

Cursor

Add to MCP settings:

{
  "video-mcp": {
    "command": "bun",
    "args": ["run", "/path/to/video-mcp/src/index.ts"],
    "env": {
      "GEMINI_API_KEY": "your-api-key",
      "VIDEO_PATHS": "/home/user/videos"
    }
  }
}

Development

# Lint
bun run lint

# Type check
bun run typecheck

# Build for distribution
bun run build

License

MIT