YouTube MCP Server Enhanced 🚀
A comprehensive Micro-Conversational Processor (MCP) server for extracting and analyzing YouTube data using yt-dlp.
🚀 Features
Core Extraction
- Video Information: Metadata, statistics, engagement metrics
- Channel Information: Stats, subscriber count, view count, verification status
- Playlist Details: Video lists, durations, total views
- Comments: Threaded comments with replies and engagement
- Transcripts: Auto-generated and manual subtitles
Advanced Capabilities
- YouTube Search: Search for videos, channels, and playlists
- Trending Videos: Get trending content by region
- Batch Processing: Extract from multiple URLs concurrently
- Intelligent Caching: Configurable TTL-based caching
- Automatic Retries: Exponential backoff for failed requests
- Health Monitoring: Real-time extractor status and configuration
🛠️ Installation
Prerequisites
- Python 3.10+
- uv package manager (required)
yt-dlp(automatically installed via uv)
⚠️ Important: This project requires uv to run properly. Install it first:
# Install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or via Homebrew (macOS)
brew install uv
# Or via pip
pip install uv
Setup
# Clone the repository
git clone <repository-url>
cd youtube-mcp-server-enhanced
# Install yt-dlp and all dependencies
uv add yt-dlp
uv sync
# Verify installation
uv run yt-dlp --version
⚙️ Configuration
Environment Variables (.env file)
Create a .env file in the project root to configure the server:
# Copy the example file
cp .env.example .env
# Edit with your preferred settings
nano .env
Example .env configuration:
# Rate limiting (e.g., "500K" for 500KB/s, "1M" for 1MB/s)
YOUTUBE_RATE_LIMIT=500K
# Retry configuration
YOUTUBE_MAX_RETRIES=5
YOUTUBE_RETRY_DELAY=2.0
YOUTUBE_TIMEOUT=600
# Caching
YOUTUBE_ENABLE_CACHE=true
YOUTUBE_CACHE_TTL=3600
# Logging level
LOG_LEVEL=INFO
MCP Client Configuration
Claude Desktop (macOS)
Add to your ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"youtube-mcp-server": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/youtube-mcp-server-enhanced",
"python",
"-m",
"src.youtube_mcp_server.server"
],
"env": {
"YOUTUBE_RATE_LIMIT": "500K",
"YOUTUBE_MAX_RETRIES": "5",
"YOUTUBE_RETRY_DELAY": "2.0",
"YOUTUBE_TIMEOUT": "600",
"YOUTUBE_ENABLE_CACHE": "true",
"YOUTUBE_CACHE_TTL": "3600"
}
}
}
}
Other MCP Clients
For other MCP clients, configure the server command as:
uv run --directory /path/to/youtube-mcp-server-enhanced python -m src.youtube_mcp_server.server
Default Values
- Rate Limit: None (uses YouTube's default)
- Max Retries: 5 (increased from 3 for better reliability)
- Retry Delay: 2.0 seconds (with exponential backoff)
- Timeout: 600 seconds (10 minutes)
- Cache TTL: 3600 seconds (1 hour)
- Cache: Enabled by default
🎯 Available MCP Tools
Data Extraction
| Tool | Description | Example |
|---|---|---|
get_video_info() | Extract comprehensive video metadata | get_video_info("https://youtube.com/watch?v=...") |
get_channel_info() | Extract channel information and stats (supports multiple URL formats) | get_channel_info("https://youtube.com/@channel") or get_channel_info("https://youtube.com/ChannelName") |
get_playlist_info() | Extract playlist details and video list | get_playlist_info("https://youtube.com/playlist?list=...") |
get_video_comments() | Extract video comments and replies | get_video_comments("https://youtube.com/watch?v=...", 50) |
get_video_transcript() | Extract video transcripts/subtitles | get_video_transcript("https://youtube.com/watch?v=...") |
Search & Discovery
| Tool | Description | Example |
|---|---|---|
search_youtube() | Search for videos, channels, or playlists | search_youtube("Python tutorials", "video", 20) |
get_trending_videos() | Get trending videos by region | get_trending_videos("US", 15) |
Analysis & Insights
| Tool | Description | Example |
|---|---|---|
analyze_video_engagement() | Analyze engagement metrics with benchmarks | analyze_video_engagement("https://youtube.com/watch?v=...") |
search_transcript() | Search for text within video transcripts | search_transcript("https://youtube.com/watch?v=...", "query") |
Batch Operations
| Tool | Description | Example |
|---|---|---|
batch_extract_urls() | Process multiple URLs concurrently | batch_extract_urls(["url1", "url2"], "video") |
System Management
| Tool | Description | Example |
|---|---|---|
get_extractor_health() | Monitor extractor health and status | get_extractor_health() |
get_extractor_config() | View current configuration | get_extractor_config() |
clear_extractor_cache() | Clear all cached data | clear_extractor_cache() |
MCP Prompts
| Prompt | Description | Example |
|---|---|---|
analyze-video | Comprehensive video analysis with optional comments/transcript | analyze-video(url, include_comments=true, include_transcript=true) |
compare-videos | Compare engagement metrics across multiple videos | compare-videos([url1, url2, url3]) |
📊 Data Models
VideoInfo
{
"metadata": {
"id": "video_id",
"title": "Video Title",
"description": "Video description...",
"uploader": "Channel Name",
"uploader_id": "channel_id",
"upload_date": "20240101",
"tags": ["tag1", "tag2"],
"categories": ["Entertainment"],
"thumbnail": "https://..."
},
"statistics": {
"view_count": 1000,
"like_count": 50,
"comment_count": 25,
"duration_seconds": 120,
"duration_string": "2:00"
},
"engagement": {
"like_to_view_ratio": 0.05,
"comment_to_view_ratio": 0.025,
"like_rate_percentage": "5.000%",
"comment_rate_percentage": "2.500%"
},
"technical": {
"age_limit": 0,
"availability": "public",
"live_status": "not_live"
}
}
ChannelInfo
{
"id": "channel_id",
"name": "Channel Name",
"url": "https://youtube.com/@channel",
"description": "Channel description...",
"avatar_url": "https://...",
"banner_url": "https://...",
"verified": true,
"country": "US",
"language": "en",
"tags": ["tag1", "tag2"],
"statistics": {
"subscriber_count": 10000,
"video_count": 150,
"view_count": 500000
}
}
PlaylistInfo
{
"id": "playlist_id",
"title": "Playlist Title",
"description": "Playlist description...",
"uploader": "Channel Name",
"uploader_id": "channel_id",
"video_count": 25,
"total_duration_seconds": 7200,
"total_duration_formatted": "2h 0m",
"total_views": 50000,
"videos": [
{
"video_id": "video_id",
"title": "Video Title",
"uploader": "Channel Name",
"duration": 300,
"view_count": 2000,
"playlist_index": 1
}
]
}
🔍 Usage Examples
Basic Video Analysis
# Get comprehensive video information
video_info = await get_video_info("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
# Extract video comments
comments = await get_video_comments("https://www.youtube.com/watch?v=dQw4w9WgXcQ", max_comments=50)
# Get video transcript
transcript = await get_video_transcript("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
# Search within transcript
results = await search_transcript("https://www.youtube.com/watch?v=dQw4w9WgXcQ", "never gonna")
Channel and Playlist Analysis
# Get channel information
channel_info = await get_channel_info("https://www.youtube.com/@RickAstleyYT")
# Get playlist details
playlist_info = await get_playlist_info("https://www.youtube.com/playlist?list=...")
Search and Discovery
# Search for videos
results = await search_youtube("Python programming tutorials", "video", 10)
# Get trending videos
trending = await get_trending_videos("US", 20)
Advanced Analysis
# Analyze video engagement with benchmarks
engagement = await analyze_video_engagement("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
# Compare multiple videos
comparison = await compare_videos([
"https://youtube.com/watch?v=video1",
"https://youtube.com/watch?v=video2"
])
Batch Processing
# Process multiple URLs concurrently
results = await batch_extract_urls([
"https://youtube.com/watch?v=video1",
"https://youtube.com/watch?v=video2"
], "video")
⚡ Performance Features
Caching
- In-Memory Cache: Configurable TTL-based caching
- Cache Keys: Unique keys for each request type and parameters
- Cache Management: View stats, clear cache, configure TTL
Retry Logic
- Automatic Retries: Configurable retry attempts
- Exponential Backoff: Increasing delay between retries
- Error Handling: Graceful degradation on failures
Batch Processing
- Concurrent Extraction: Process multiple URLs simultaneously using asyncio
- Async Operations: Non-blocking I/O for better performance
- Result Aggregation: Combined results with success/failure counts
🏥 Health Monitoring
Health Status
health = await get_extractor_health()
# Returns:
{
"health": {
"status": "healthy",
"yt_dlp_available": true,
"yt_dlp_version": "2025.6.30",
"cache": {"enabled": true, "size": 5, "ttl": 3600},
"config": {"rate_limit": "1M", "max_retries": 3, "timeout": 300}
},
"cache": {
"enabled": true,
"size": 5,
"ttl": 3600,
"keys": ["key1", "key2"],
"total_keys": 5
},
"server_version": "0.1.0",
"mcp_version": "1.0.0"
}
Configuration View
config = await get_extractor_config()
# Returns current extractor settings and status
🚨 Error Handling
Retry Strategy
- Automatic Retries: Up to 5 attempts by default (configurable)
- Exponential Backoff: 2s, 4s, 8s delays
- Rate Limiting: 500KB/s limit with 2-second sleep intervals
- Graceful Degradation: Return partial results when possible
Error Types
- YouTubeExtractorError: Extraction-specific errors
- InvalidURLError: Invalid YouTube URL format
- RuntimeError: General execution errors
Troubleshooting
Rate Limiting Issues
If you encounter rate limiting:
- Increase sleep intervals in
.env:YOUTUBE_RETRY_DELAY=3.0 - Lower rate limit:
YOUTUBE_RATE_LIMIT=300K - Reduce concurrent requests
yt-dlp Not Working
- Ensure uv is installed:
uv --version - Verify yt-dlp installation:
uv run yt-dlp --version - The server automatically uses
uv run yt-dlpif direct access fails
MCP Connection Issues
- Restart your MCP client after code changes
- Check logs for specific error messages
- Verify environment variables are loaded correctly
🔧 Development
Running the Server
⚠️ Always use uv run to ensure proper dependency management:
# Start the MCP server (recommended)
uv run python -m src.youtube_mcp_server.server
# Or if you have a run_server.py file
uv run python run_server.py
Testing
# Run all tests
uv run pytest tests/
# Run specific test file
uv run pytest tests/test_basic.py
# Run with coverage
uv run pytest --cov=src tests/
📈 Use Cases
Content Analysis
- Video Performance: Analyze view counts, engagement metrics
- Channel Growth: Track subscriber and view count trends
- Content Discovery: Find trending and popular content
Research & Analytics
- Market Research: Analyze competitor channels and content
- Trend Analysis: Identify trending topics and content types
- Audience Insights: Understand viewer preferences and behavior
Content Management
- Playlist Organization: Manage and analyze video collections
- Comment Moderation: Extract and analyze user feedback
- Transcript Analysis: Process and search video content
🤝 Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Submit a pull request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- yt-dlp: The core YouTube extraction engine
- FastMCP: The MCP server framework
- Pydantic: Data validation and serialization
📞 Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: info@labeveryday.com
🗺️ Roadmap
- Batch processing for multiple videos
- Caching layer for improved performance
- Advanced analytics (engagement analysis, benchmarks)
- Rate limiting and quota management
- Export functionality (JSON, CSV, etc.)
- WebSocket support for real-time updates
- Integration examples with popular MCP clients
Made with ❤️ by Du'An Lightfoot
Empowering developers to extract meaningful insights from YouTube content through the Model Context Protocol.