youtube-shorts-viral-agent 0.2.1

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

YouTube Shorts Viral Agent

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": {
    "youtube-shorts-viral": {
      "command": "uvx",
      "args": ["youtube-shorts-viral-agent"],
      "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

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

Operation	Cost	Description
search.list	100 units	Search videos
videos.list	1 unit	Get video details
channels.list	1 unit	Get channel info

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

shorts/
├── .env.example            # MCP config example
├── .gitignore              # Git ignore rules
├── LICENSE                 # MIT License
├── README.md               # 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: "YOUTUBE_API_KEY not set" error

1. Check claude_desktop_config.json has env.YOUTUBE_API_KEY set
2. Ensure no extra spaces or quotes in API key
3. Fully restart Claude Desktop

Q: "API quota exhausted" error

1. Wait for quota reset (Pacific Time midnight)
2. Request quota increase in Google Cloud Console
3. Reduce search frequency or lower max_results

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: No search results

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

---

Tech Stack

• Python: 3.11+
• MCP: FastMCP 2.13.1+
• API: google-api-python-client 2.187.0+
• Validation: Pydantic 2.12.4+

---

License

MIT License - see LICENSE

---

Links

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

---

Start discovering viral videos with natural language! 🚀