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

| Tool | Description | |------|-------------| | search_trending_videos | Search trending videos by category | | search_custom_videos | Search any topic with custom query | | get_video_metadata | Get detailed metadata for a video | | collect_daily_ranking | Collect and save daily rankings | | get_youtube_rss_feed | Fetch RSS feed from channel/playlist | | filter_videos | Filter videos by views, likes, duration |

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?

| Web Scraping | yt-dlp Approach | |--------------|-----------------| | Requires Playwright (heavy) | No browser needed | | Breaks with site changes | Stable internal APIs | | Anti-bot protection issues | Community maintained (143k+ stars) | | Legal concerns (ToS) | Weekly updates | | High maintenance | Reliable & fast |

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

MCP Servers