youtube-gemini-mcp
Leverages Google Gemini API (Gemini 2.5 Pro) for conversational video analysis and visual understanding.
Provides tools for analyzing YouTube videos, including full video visual and audio understanding via direct URL processing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@youtube-gemini-mcp Analyze and summarize https://youtube.com/watch?v=abc123"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.

YouTube Gemini MCP Server
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
Get Google AI API Key: Visit Google AI Studio to get your free API key
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 developmentProduction:
mcp-config.private.json.example- Copy and customize
๐ Available Tools
Tool | Description |
| Create new conversational analysis session |
| Analyze video within session context |
| Single-shot YouTube video analysis |
| Single-shot local video analysis |
| Get session information and history |
| List all active sessions |
| Close session and cleanup resources |
| Validate and normalize YouTube URLs |
| Comprehensive documentation |
| 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:
GOOGLE_API_KEY- Get your free API key from Google AI Studio
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.
๐ Related Projects
๐ Documentation
LLM.md - Comprehensive usage guide for AI systems
DEVELOPMENT.md - Development setup and architecture
CONTRIBUTING.md - How to contribute to the project
PRD.md - Complete product requirements document
๐ค Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Quick Start for Contributors
Fork the repository
Set up development environment:
poetry installRun tests:
poetry run pytestMake your changes and add tests
Submit a pull request
๐ Support & Community
๐ Bug Reports: GitHub Issues
๐ก Feature Requests: GitHub Issues
๐ฌ Discussions: GitHub Discussions
๐ Documentation: Check our comprehensive docs above
Getting Help
Check Documentation: Start with LLM.md for usage questions
Search Issues: Look for existing solutions in GitHub Issues
Create Issue: Provide clear details and reproduction steps
Community: Join discussions for general questions and ideas
Available Tools
10 toolsanalyze_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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Summarize YouTube videos, playlists and channels, ask about a video, and get key moments.
Personal YouTube AI knowledge base powered by RAG. Query your subscribed YouTube channels.
Fetch YouTube transcripts with timestamps, search history, and export data for AI models.
Your YouTube library in Claude, ChatGPT and Cursor: transcripts, breakdowns, summaries, search.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.14MIT
- AlicenseAqualityDmaintenanceEnables 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.513MIT
- AlicenseAqualityDmaintenanceAnalyzes YouTube videos using Google's Gemini API, allowing users to get summaries or ask questions about video content via direct URL input.52MIT
- AlicenseAqualityDmaintenanceEnables 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.514 npmMIT