YouTube Trending MCP Server

Collect trending YouTube videos without web scraping! This MCP server provides stable, API-based YouTube data collection using yt-dlp. No web scraping, no API keys required, no quotas!

Features

• No Web Scraping - Uses yt-dlp's stable API access
• No API Keys - Completely free forever
• No Quotas - Unlimited data collection
• Category Filtering - Any topic: Music, Gaming, Cooking, Tech, etc.
• Daily Rankings - Track trending videos over time
• RSS Fallback - Alternative data source
• SQLite Storage - Built-in database support

Installation

pip install youtube-trending-mcp

Or install from source:

git clone https://github.com/AIKONG2024/youtube-trending-mcp.git
cd youtube-trending-mcp
pip install -e .

Quick Start

Claude Code

Add to your MCP config:

{
  "mcpServers": {
    "youtube-trending": {
      "command": "python",
      "args": ["-m", "youtube_trending_mcp"],
      "env": {
        "DATA_DIR": "/path/to/data"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "youtube-trending": {
      "command": "python",
      "args": ["-m", "youtube_trending_mcp"]
    }
  }
}

OpenAI Codex

{
  "mcpServers": {
    "youtube-trending": {
      "command": "python",
      "args": ["-m", "youtube_trending_mcp"],
      "env": {
        "DATA_DIR": "./data"
      }
    }
  }
}

LLM Tool Reference

Tools Overview

search_trending_videos

Parameters:
  category: string (default: "all") - "all", "pets", "music", "gaming", "entertainment", or any topic
  max_results: int (default: 20, range: 1-100)
  region: string (default: "US") - Country code

Returns: { success, count, category, videos: [VideoObject] }

search_custom_videos

Parameters:
  query: string (required) - Any search term
  max_results: int (default: 20)
  min_views: int (default: 0) - Filter by minimum views
  sort_by: string (default: "relevance") - "relevance", "views", "date"

Returns: { success, query, count, videos: [VideoObject] }

get_video_metadata

Parameters:
  video_id: string (required) - YouTube video ID (11 chars)

Returns: { success, video: VideoObject }

collect_daily_ranking

Parameters:
  category: string (default: "all")
  max_results: int (default: 50)
  save_to_db: bool (default: true)
  save_to_json: bool (default: true)

Returns: { success, count, output_paths: [...] }

get_youtube_rss_feed

Parameters:
  channel_id: string - Channel ID (starts with "UC...")
  playlist_id: string - Playlist ID
  (At least one required)

Returns: { success, count, feed_type, videos: [VideoObject] }

filter_videos

Parameters:
  videos: array (required) - List of VideoObjects
  min_views: int - Minimum view count
  min_likes: int - Minimum like count
  max_duration: int - Max duration in seconds
  exclude_keywords: array - Keywords to exclude

Returns: { success, original_count, filtered_count, videos: [VideoObject] }

VideoObject Schema

{
  "video_id": "dQw4w9WgXcQ",
  "title": "Video Title",
  "channel": "Channel Name",
  "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "views": 1500000000,
  "likes": 16000000,
  "upload_date": "20091025",
  "duration": 212,
  "description": "Description (max 1000 chars)",
  "categories": ["Music"],
  "tags": ["tag1", "tag2"],
  "thumbnail": "https://i.ytimg.com/vi/.../maxresdefault.jpg",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Common Workflows

# Find popular videos on any topic
search_custom_videos(query="machine learning", max_results=30, sort_by="views")

# Get trending by category
search_trending_videos(category="gaming", max_results=50, region="KR")

# Filter results
videos = search_custom_videos(query="cooking", max_results=100)
filter_videos(videos=videos, min_views=50000, max_duration=600)

# Save daily rankings
collect_daily_ranking(category="music", max_results=100)

Notes

• Video IDs: 11 characters (e.g., dQw4w9WgXcQ)
• Channel IDs: Start with UC + 22 characters
• Duration: In seconds
• Upload date: YYYYMMDD format

Why yt-dlp Instead of Web Scraping?

Development

git clone https://github.com/AIKONG2024/youtube-trending-mcp.git
cd youtube-trending-mcp
pip install -e ".[dev]"
pytest tests/ -v

Related Projects

• yt-dlp-mcp - Download videos and transcripts via MCP

License

MIT License - see LICENSE file for details.

Made with love by AIKONG2024