youtube-shorts-viral-agent 0.3.0

MCP-powered YouTube Shorts discovery tool for finding viral videos using VPH and engagement analysis

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: Invidious API (Free) • Official YouTube API (Optional) • VPH (Views Per Hour) • Engagement Rate • MCP Protocol

---

Quick Start

Prerequisites

• Python 3.11+ (optional, uvx auto-manages)
• Claude Desktop or MCP client
• No API keys required! ✨ (uses free Invidious API by default)

1. Configure Claude Desktop

Edit Claude Desktop config:

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

Option A: Free API Only (Recommended)

{
  "mcpServers": {
    "viral-shorts": {
      "command": "uvx",
      "args": ["--from", "youtube-shorts-viral-agent", "shorts-server"]
    }
  }
}

Option B: With Official YouTube API (Optional)

If you want to enable the official YouTube API as a fallback:

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

Note:

• Default: Uses free Invidious API (no API keys needed)
• Optional: Set YOUTUBE_API_KEY to enable official API as fallback
• uvx auto-downloads from PyPI
• No manual installation needed

2. 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

---

Data Sources

Primary: Invidious API (Free)

• Free: No API keys required
• Unlimited: No quota restrictions
• Fast: Optimized for search and trending
• Privacy-focused: Alternative YouTube API
• Default: Always used first

Fallback: Official YouTube API (Optional)

• Requires: YouTube Data API v3 key
• Fallback: Only used if Invidious fails
• Enabled: Only when YOUTUBE_API_KEY is set
• Quota: Limited by Google's quota system

Automatic Fallback Strategy

1. First attempt: Invidious API (free, no quota)
2. If fails: Official YouTube API (if configured)
3. If both fail: Returns error with helpful message

This ensures reliable operation while keeping costs at zero by default.

Rate Limiting

• Invidious: Generous rate limits with automatic backoff
• Official API: Respects Google's quota system
• Exponential Backoff: Automatic retry with jitter

---

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          # PyPI config
├── uv.lock                 # Dependency lock
├── src/
│   ├── server.py           # MCP Server (annotated)
│   ├── youtube/
│   │   ├── client.py       # YouTube API client
│   │   └── analyzer.py     # Viral analysis
│   ├── models/
│   │   └── video.py        # Data models
│   └── utils/
│       └── config.py       # Config (env vars)
└── tests/
    └── test_youtube.py     # Unit tests

---

FAQ

Q: "No search results" error

1. Expand time range (e.g., 12h → 24h)
2. Use broader keywords
3. Lower min_views threshold
4. Check internet connection

Q: Claude can't find tools

1. Verify claude_desktop_config.json format is correct
2. Fully restart Claude Desktop
3. Check Claude Desktop logs for errors

Q: Invidious API is slow or unavailable

1. The system automatically falls back to yt-dlp
2. Try again - fallback sources are being used
3. Check your internet connection

Q: Why no API key needed?

1. Uses free Invidious API (no authentication required)
2. Falls back to yt-dlp for reliability
3. No quota limits or costs
4. Unlimited requests

---

Tech Stack

• Python: 3.11+
• MCP: FastMCP 2.13.1+
• Primary API: Invidious (free)
• Fallback API: Official YouTube API v3 (optional)
• HTTP Client: httpx 0.25.0+
• Validation: Pydantic 2.12.4+

---

License

MIT License - see LICENSE

---

Links

• GitHub: https://github.com/Xeron2000/viral-shorts
• MCP Docs: https://modelcontextprotocol.io/
• FastMCP: https://github.com/jlowin/fastmcp

---

Start discovering viral videos with natural language! 🚀