Skip to main content

YouTube Shorts Viral Agent

License: MIT Python 3.11+

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

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

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

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

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



Start discovering viral videos with natural language! 🚀

Metadata

Release files for youtube-shorts-viral-agent 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for youtube-shorts-viral-agent 0.2.1
File Size Uploaded Provenance Actions
youtube_shorts_viral_agent-0.2.1.tar.gz 22.3 kB Without provenance Details for youtube_shorts_viral_agent-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for youtube-shorts-viral-agent 0.2.1
File Interpreter ABI Platform Actions
youtube_shorts_viral_agent-0.2.1-py3-none-any.whl Python 3 none any Details for youtube_shorts_viral_agent-0.2.1-py3-none-any.whl

Total release size: 42.6 kB

Release files / youtube_shorts_viral_agent-0.2.1.tar.gz

Download URL youtube_shorts_viral_agent-0.2.1.tar.gz
Size 22.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4cfbbbfb2402909fd6dbcc41d1a2ef9d543d6947bc4825f3f54b48ea2ddb9608
BLAKE2b-256 checksum
How to use checksums
53925a7880e64c65959010076c2f8c65045276923f4f92bcb2e467a196359db6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.6.12

Release files / youtube_shorts_viral_agent-0.2.1-py3-none-any.whl

Download URL youtube_shorts_viral_agent-0.2.1-py3-none-any.whl
Size 20.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9a1e29a6d458ddb705dcd63f45ccf4a28d8e93bc218bd3b8688ca079066b942a
BLAKE2b-256 checksum
How to use checksums
79430f129f7b433a2b75e4506c952164865bae1089a8766eacff516001a6879e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.6.12

Security for youtube-shorts-viral-agent 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page