Viral Shorts MCP Server

Viral Shorts

MCP-powered YouTube Shorts discovery tool for finding viral videos using natural language in Claude Desktop

中文文档

Features

• 🔥 Discover trending Shorts
• 📊 Analyze viral potential
• 🎯 Track trending topics
• 🔍 Find niche trends
• 📝 Summarize video stories

Tech Stack: YouTube Data API v3 • VPH (Views Per Hour) • Engagement Rate • MCP Protocol

Quick Start

Prerequisites

• Python 3.11+ (optional, uvx auto-manages)
• YouTube Data API Key
• Claude Desktop or MCP client

1. Get YouTube API Key

1. Visit Google Cloud Console
2. Create a new project
3. Enable YouTube Data API v3
4. Create API Key
5. (Recommended) Restrict key to YouTube Data API v3 only

2. Configure Claude Desktop

Edit Claude Desktop config:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add:

{
  "mcpServers": {
    "viral-shorts": {
      "command": "uvx",
      "args": ["--from", "youtube-shorts-viral-agent", "shorts-server"],
      "env": {
        "YOUTUBE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Note:

• Replace your-api-key-here with your actual API key
• uvx auto-downloads from PyPI
• No manual installation needed

3. Start Using

1. Restart Claude Desktop completely
2. Use natural language:

Find trending AI Shorts from the last 24 hours

Usage Examples

Example 1: Discover Trends

Show me viral AI Shorts from the last 24 hours

Returns Markdown table with:

• Title, Channel, Views, VPH, Engagement Rate, Viral Score, Age

Example 2: Analyze Video

Analyze this video's potential: https://www.youtube.com/shorts/abc123

Example 3: Find Topics

What's trending in tech category?

Example 4: Custom Parameters

Find programming Shorts from last 12 hours with 500k+ views

Claude auto-extracts:

• Keyword: "programming"
• Time range: 12 hours
• Min views: 500,000

Available Tools

1. `get_youtube_shorts_trends`

Discover trending YouTube Shorts.

Parameters:

• keyword (string): Search keyword, empty for global trends
• hours_ago (int): Time range in hours, default 24
• max_results (int): Result count, default 10
• min_views (int): Min view threshold, default 100,000
• search_by_tag (boolean): Search by exact tag match, default false

2. `analyze_video_potential`

Deep analysis of a single video.

Parameters:

• video_url (string): YouTube Shorts URL

3. `get_trending_topics`

Find trending topics.

Parameters:

• category (string): tech/entertainment/education/gaming/all
• hours_ago (int): Time range, default 24

4. `summarize_video_story`

Extract video story and core content.

Parameters:

• video_url (string): YouTube Shorts URL

5. `discover_niche_trends`

Find niche viral trends within a topic.

Parameters:

• main_topic (string): Main keyword (e.g., "AI", "tutorial")
• hours_ago (int): Time range, default 24
• min_videos (int): Min videos per niche, default 3
• top_niches (int): Top N niches to return, default 10

Core Metrics

VPH (Views Per Hour)

• Formula: Total Views ÷ Hours Since Published
• Meaning: Growth velocity
• Thresholds:
  • ≥ 10,000: 🔥 Super viral
  • ≥ 5,000: ⭐ High potential
  • ≥ 1,000: ✨ Potential

Engagement Rate

• Formula: (Likes + Comments) ÷ Views × 100
• Meaning: Content quality
• Thresholds:

  • 10%: Excellent

  • 5%: Good

  • 2%: Average

Viral Score

• Formula: VPH × Time Weight × (1 + Engagement Boost)
• Meaning: Comprehensive ranking score
• Features:
  • Newer videos weighted higher
  • High engagement significantly boosts score

API Quota Management

YouTube Data API v3 Quota

• Default: 10,000 units/day
• Reset: Daily at Pacific Time midnight

Cost Breakdown

Best Practices

• Keep max_results ≤ 10 per search
• Limit to ~50 calls/day
• Use min_views to filter results
• Use view count for overall popularity
• Use VPH for fast-growing new videos

Project Structure

viral-shorts/
├── .env.example            # MCP config example
├── .gitignore              # Git ignore rules
├── LICENSE                 # MIT License
├── README.md               # English documentation
├── README.zh.md            # Chinese documentation
├── MCP_EXPLAINED.md        # MCP protocol explained
├── pyproject.toml          #