Skip to main content
Glama
youtube-gemini-mcp
by aigentive

YouTube Gemini MCP Hero

YouTube Gemini MCP Server

PyPI version

A Model Context Protocol (MCP) server that provides conversational YouTube video analysis capabilities using Gemini 2.5 Pro. Analyze videos through multi-turn conversations with advanced visual understanding.

๐ŸŽฏ What Problems Does This Solve?

Traditional Video Analysis Pain Points

โŒ Transcript-only limitations - Missing visual context and scene understanding
โŒ No conversation memory - Each analysis starts from scratch
โŒ Manual workflows - Complex download/upload processes

Our Solution

โœ… Full video analysis - Visual, audio, and contextual understanding
โœ… Session memory - Builds on previous analysis automatically
โœ… Integrated workflows - YouTube URL to analysis in one step

Related MCP server: yt-analysis-mcp

๐Ÿš€ Key Capabilities

๐Ÿ”„ Session-Based Video Conversations

Create persistent sessions for multi-turn video analysis:

# Create session
create_video_session(
    description="Analyze machine learning lecture",
    video_source="https://youtube.com/watch?v=abc123",
    source_type="youtube_url"
)

# Continue conversation
analyze_video_in_session(session_id="uuid", prompt="What are the key concepts?")
analyze_video_in_session(session_id="uuid", prompt="Explain the neural networks part")

๐Ÿ“น Direct YouTube Processing

No downloads required - process YouTube videos directly:

analyze_youtube_video(
    youtube_url="https://youtube.com/watch?v=abc123",
    prompt="Summarize this video's main points"
)

๐Ÿ’พ Local Video Support

Upload and analyze local video files (48-hour retention):

analyze_local_video(
    video_path="/path/to/video.mp4",
    prompt="What happens in this video?"
)

๐Ÿ› ๏ธ Installation

Prerequisites

  • Python 3.10+

  • Google AI API key

  • Poetry (recommended) or pip

Setup

# Clone repository
git clone https://github.com/aigentive/youtube-gemini-mcp
cd youtube-gemini-mcp

# Install with Poetry
poetry install

# Or with pip
pip install -e .

# Set environment variable
export GOOGLE_API_KEY="your_google_api_key_here"

๐Ÿ”ง Claude Desktop Integration

Quick Setup

  1. Get Google AI API Key: Visit Google AI Studio to get your free API key

  2. Add to Claude Desktop: Copy the configuration below to your Claude Desktop settings

Production Configuration

Add to your Claude Desktop MCP configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "youtube-gemini-mcp": {
      "command": "youtube-gemini-mcp",
      "env": {
        "GOOGLE_API_KEY": "your_google_api_key_here"
      }
    }
  }
}

Development Configuration

For development work, use the Poetry configuration:

{
  "mcpServers": {
    "youtube-gemini-mcp-dev": {
      "command": "poetry",
      "args": ["run", "python", "-m", "youtube_gemini_mcp.server"],
      "cwd": "/absolute/path/to/youtube-gemini-mcp",
      "env": {
        "GOOGLE_API_KEY": "your_google_api_key_here",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Configuration Templates

We provide ready-to-use configuration files:

  • Development: mcp-config.poetry.json - For local development

  • Production: mcp-config.private.json.example - Copy and customize

๐Ÿ“š Available Tools

Tool

Description

create_video_session

Create new conversational analysis session

analyze_video_in_session

Analyze video within session context

analyze_youtube_video

Single-shot YouTube video analysis

analyze_local_video

Single-shot local video analysis

get_session_status

Get session information and history

list_active_sessions

List all active sessions

close_session

Close session and cleanup resources

validate_youtube_url

Validate and normalize YouTube URLs

get_usage_guide

Comprehensive documentation

get_server_stats

Server health and statistics

๐ŸŽฏ Use Cases

Educational Content Analysis

Analyze lectures, tutorials, and educational videos with follow-up questions.

Content Research

Research documentaries, interviews, and informational content systematically.

Video Summarization

Extract key insights and create summaries from long-form content.

Training Material Development

Analyze existing training videos to extract learning objectives and key points.

โšก Quick Examples

Analyze a YouTube Video

# Direct analysis - perfect for quick insights
analyze_youtube_video(
    youtube_url="https://youtube.com/watch?v=dQw4w9WgXcQ",
    prompt="What is this video about? Provide a comprehensive summary."
)

Session-Based Analysis

# Create persistent session for multi-turn conversation
session = create_video_session(
    description="Learning about machine learning fundamentals",
    video_source="https://youtube.com/watch?v=abc123",
    session_name="ML Fundamentals Study"
)

# Build understanding through conversation
analyze_video_in_session(
    session_id=session["session_id"], 
    prompt="What are the main topics covered in this lecture?"
)

analyze_video_in_session(
    session_id=session["session_id"], 
    prompt="Focus on the neural networks section - how are they explained?"
)

analyze_video_in_session(
    session_id=session["session_id"], 
    prompt="What practical examples or demonstrations are shown?"
)

analyze_video_in_session(
    session_id=session["session_id"], 
    prompt="Based on our discussion, what are the key takeaways for beginners?"
)

Local Video Analysis

# Upload and analyze private content
analyze_local_video(
    video_path="/path/to/your/presentation.mp4",
    prompt="Extract the key business metrics and recommendations from this quarterly review"
)

Advanced: Timestamp-Specific Analysis

# Focus on specific video segments
analyze_video_in_session(
    session_id="your-session-id",
    prompt="Analyze the demonstration shown in this segment",
    timestamp_range="5:30-8:45"
)

๐Ÿ” Configuration

Environment Variables

Required:

Optional Configuration:

MCP_MAX_SESSIONS=50               # Maximum concurrent sessions
MCP_SESSION_TIMEOUT=7200          # Session timeout in seconds (2 hours)
GEMINI_MODEL_DEFAULT="gemini-2.5-pro-preview-05-06"  # Default Gemini model
MAX_VIDEO_DURATION=7200           # Max video length in seconds
AUTO_CLEANUP_FILES=true           # Auto-cleanup uploaded files
LOG_LEVEL=INFO                    # Logging level (DEBUG, INFO, WARNING, ERROR)

System Requirements

  • Python: 3.10+ (3.11+ recommended)

  • Memory: 4GB RAM minimum for video processing

  • Storage: 500MB for session data and temporary files

  • Network: High-speed internet for video processing

Limitations & Constraints

YouTube Videos (Unlimited Sessions)

  • โœ… No file size limits - Direct URL processing

  • โœ… Unlimited session duration - No 48-hour restriction

  • โš ๏ธ 2-hour video limit - Recommended maximum for optimal performance

  • โš ๏ธ Public videos only - Private/unlisted may not be accessible

Local Videos (48-Hour Sessions)

  • โš ๏ธ 2GB file size limit - Google Files API restriction

  • โš ๏ธ 48-hour auto-deletion - Files automatically deleted after 48 hours

  • โš ๏ธ 20GB project limit - Total storage quota per Google project

  • โŒ No retention extension - Cannot extend file lifespan beyond 48 hours

Performance Guidelines

  • Concurrent sessions: Default maximum 50 active sessions

  • Session timeout: 2 hours of inactivity before cleanup

  • Memory usage: ~100MB per active session

  • Response time: 10-30 seconds for typical analysis requests

๐Ÿงช Testing

# Run tests
poetry run pytest

# With coverage
poetry run pytest --cov=youtube_gemini_mcp

# Type checking
poetry run mypy src/

๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

๐Ÿ“š Documentation

๐Ÿค Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Start for Contributors

  1. Fork the repository

  2. Set up development environment: poetry install

  3. Run tests: poetry run pytest

  4. Make your changes and add tests

  5. Submit a pull request

๐Ÿ“ž Support & Community

Getting Help

  1. Check Documentation: Start with LLM.md for usage questions

  2. Search Issues: Look for existing solutions in GitHub Issues

  3. Create Issue: Provide clear details and reproduction steps

  4. Community: Join discussions for general questions and ideas

Available Tools

10 tools
analyze_local_videoA

Single-shot or session-integrated local video analysis using Files API.

Args: video_path: Local video file path prompt: Analysis instruction model: Gemini model to use session_id: Optional session for context

Inputs: video_path (required), prompt (required), model, session_id. Returns: result

analyze_video_in_sessionB

Analyze video within session context.

Args: session_id: UUID of existing session prompt: Analysis question/instruction timestamp_range: Optional "MM:SS-MM:SS" for segment analysis

Inputs: session_id (required), prompt (required), timestamp_range. Returns: result

analyze_youtube_videoA

Single-shot or session-integrated YouTube video analysis using direct URL method.

Args: youtube_url: YouTube video URL or ID prompt: Analysis instruction model: Gemini model to use session_id: Optional session for context

Inputs: youtube_url (required), prompt (required), model, session_id. Returns: result

close_sessionC

Close session and cleanup resources.

Inputs: session_id (required). Returns: result

create_video_sessionB

Create new conversational video analysis session.

Args: description: Session context/purpose video_source: YouTube URL or local video file path model: Gemini model to use session_name: Optional friendly name source_type: "youtube_url" (default) or "local_file"

Inputs: description (required), video_source (required), model, session_name, +1 more. Returns: result

get_server_statsA

Server statistics and health monitoring.

Inputs: no named parameters. Returns: result

get_session_statusC

Get current session status and history.

Inputs: session_id (required). Returns: result

get_usage_guideB

Comprehensive tool documentation and examples.

Inputs: no named parameters. Returns: result

list_active_sessionsB

List all active video analysis sessions.

Inputs: no named parameters. Returns: result

validate_youtube_urlB

Validate and normalize YouTube URLs/IDs.

Inputs: url (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelogโ€ฆ

    TDQS

    B3.3/5.0

    Scored across 10 tools

    Disambiguation3/5

    The three analysis tools (analyze_local_video, analyze_video_in_session, analyze_youtube_video) have overlapping purposes, as the first and third can also work with sessions. Although descriptions clarify differences, an agent might struggle to select the correct tool without careful reading.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, such as 'analyze_local_video', 'create_video_session', and 'list_active_sessions'. No mixing of conventions or irregular names.

    Tool Count5/5

    The server has 10 tools, which is well-scoped for its domain of video analysis and session management. Each tool serves a distinct purpose without unnecessary clutter.

    Completeness4/5

    The tool set covers core workflows: creating sessions, analyzing videos (local or YouTube), managing sessions, and utilities (validation, stats, guide). Minor gaps like lacking explicit update for sessions are mitigated by session lifecycle tools.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI-powered YouTube video analysis including transcript management, video summaries, chapter generation, keyword extraction, and playback control. Supports searching videos, retrieving channel/playlist information, and translating transcripts using Google Gemini AI.
      14
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables analysis of YouTube videos using the Gemini API to generate summaries and answer specific questions via direct URLs. It supports standard videos and shorts, allowing users to interact with video content without requiring manual downloads.
      5
      13
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI clients like Codex, Claude Code, and Kimi Code to analyze public video URLs by downloading media, uploading it to Gemini, and returning timestamped production breakdowns covering shots, visual design, animation, motion, narration, music, sound effects, and editing, with follow-up Q&A and session management tools.
      5
      14 npm
      MIT