Skip to main content
Glama

Viral Shorts

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


Related MCP server: YouTube Insights MCP Server

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

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

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

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: "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! ๐Ÿš€

Available Tools

5 tools
analyze_video_potentialC

ๆทฑๅบฆๅˆ†ๆžๅ•ไธช YouTube Shorts ่ง†้ข‘็š„่กจ็Žฐใ€‚ๆไพ›่ฏฆ็ป†็š„ๆ’ญๆ”พ้‡ใ€ไบ’ๅŠจ็އ็ญ‰ๆ ธๅฟƒๆŒ‡ๆ ‡ใ€‚

Inputs: video_url (required).

summarize_video_storyC

ๆ็‚ผ YouTube Shorts ่ง†้ข‘็š„ๆ•…ไบ‹ๆข—ๆฆ‚ๅ’Œๆ ธๅฟƒๅ†…ๅฎนใ€‚ๅŸบไบŽ่ง†้ข‘ๆ ‡้ข˜ๅ’Œๆ่ฟฐ,ๅˆ†ๆž่ง†้ข‘็š„ไธป้ข˜ใ€ๆƒ…่Š‚ๅ’Œๅˆ›ไฝœๆ‰‹ๆณ•ใ€‚

Inputs: video_url (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    B3.1/5.0

    Scored across 5 tools

    Disambiguation2/5

    Multiple tools have unclear boundaries and overlapping purposes. 'get_trending_topics' and 'get_youtube_shorts_trends' both focus on discovering trends/hot content with similar descriptions, while 'analyze_video_potential' and 'summarize_video_story' both analyze individual videos but with different aspects (performance metrics vs. content/story). This overlap could cause agent misselection confusion.

    Naming Consistency4/5

    The naming is mostly consistent with a clear verb_noun pattern (e.g., analyze_video_potential, discover_niche_trends). All tools use snake_case and descriptive names, with only minor deviations like 'get_youtube_shorts_trends' being slightly redundant compared to 'get_trending_topics'.

    Tool Count5/5

    With 5 tools, the count is well-scoped and appropriate for the server's purpose of YouTube Shorts analysis. Each tool appears to serve a distinct function within the domain, and the number is manageable without being too thin or overwhelming.

    Completeness3/5

    The tool surface covers analysis, trend discovery, and summarization for YouTube Shorts, but there are notable gaps. It lacks CRUD/lifecycle operations (e.g., no tools for creating, updating, or managing content), and the focus is primarily on reading/analyzing existing data, which may limit agent workflows for content creation or optimization.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables interaction with the YouTube Data API, allowing users to search videos, get video and channel details, analyze trends, and fetch video transcripts.
      -
    • A
      license
      A
      quality
      C
      maintenance
      An MCP server for intelligent YouTube video analysis that provides token-optimized summaries, sentiment analysis, and entity extraction from transcripts. It enables AI assistants to perform video reporting, channel monitoring, and comprehensive YouTube searches through structured data tools.
      10
      53
      Apache 2.0