YouTube Search MCP Server
A fast and comprehensive MCP (Model Context Protocol) server that provides YouTube search functionality using the YouTube Data API v3.
Features
- Comprehensive Search: Search videos, channels, and playlists
- Advanced Filtering: Duration, quality, date range, region, and language filters
- Pagination Support: Handle large result sets with pagination tokens
- Multiple Search Types: Specialized tools for different content types
- Error Handling: Robust error handling and validation
- Rate Limiting Aware: Optimized for YouTube API quota management
Installation
- Install dependencies:
pip install -r requirements.txt
- Set up your YouTube API key:
export YOUTUBE_API_KEY="your_youtube_api_key_here"
- Run the server:
python youtube_search_mcp.py
API Setup
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the YouTube Data API v3
- Create an API key in the credentials section
- Set the API key as an environment variable
Available Tools
Main Search Tool
search_youtube- Full-featured search with all available filters
Specialized Search Tools
search_youtube_videos- Video-specific search with video filterssearch_youtube_channels- Channel-specific searchsearch_youtube_playlists- Playlist-specific searchsearch_youtube_by_channel- Search within a specific channel
Resource
youtube-search-help- Comprehensive help documentation
Usage Examples
Basic Video Search
# Search for programming videos
search_youtube_videos("python programming", max_results=10, order="date")
Advanced Video Search
# Search for short programming videos from last month
search_youtube_videos(
"machine learning",
max_results=20,
duration="short",
order="viewCount",
published_after="2024-01-01T00:00:00Z"
)
Channel Search
# Find channels about data science
search_youtube_channels("data science", max_results=15)
Search Within Channel
# Search within a specific channel
search_youtube_by_channel(
"UC_x5XG1OV2P6uZZ5FSM9Ttw",
query="tutorial",
max_results=25
)
Parameters
Common Parameters
query: Search query stringmax_results: Number of results (0-50, default: 25)order: Sort order (relevance, date, rating, viewCount, title)region_code: Geographic region (ISO 3166-1 alpha-2 country code)
Video-Specific Parameters
duration: Video length (any, short, medium, long)definition: Video quality (any, high, standard)published_after/before: Date filtering (RFC 3339 format)
Response Format
All search results include:
- Search metadata (total results, pagination tokens)
- Processed items with titles, descriptions, URLs
- Channel information and publication dates
- Thumbnail URLs in multiple sizes
Rate Limiting
- Daily quota: 10,000 units (default)
- Search cost: 100 units per request
- Maximum searches: ~100 requests per day
- Best practices: Implement caching and use specific filters
Error Handling
The server handles various error conditions:
- Invalid API key
- Quota exceeded
- Invalid parameters
- Network errors
- Rate limiting
Best Practices
- Use specific filters to get relevant results
- Implement caching for frequently searched terms
- Monitor quota usage in Google Cloud Console
- Use pagination tokens for large result sets
- Handle errors gracefully with retry logic
Security
- Store API keys in environment variables
- Never expose API keys in client-side code
- Implement proper rate limiting
- Validate and sanitize search queries
License
This project is open source and available under the MIT License.