KnightMode/youtube-mcp

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

1. Install dependencies:

pip install -r requirements.txt

2. Set up your YouTube API key:

export YOUTUBE_API_KEY="your_youtube_api_key_here"

3. Run the server:

python youtube_search_mcp.py

API Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the YouTube Data API v3
4. Create an API key in the credentials section
5. 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 filters
• search_youtube_channels - Channel-specific search
• search_youtube_playlists - Playlist-specific search
• search_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 string
• max_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

1. Use specific filters to get relevant results
2. Implement caching for frequently searched terms
3. Monitor quota usage in Google Cloud Console
4. Use pagination tokens for large result sets
5. 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.