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,
uvxauto-manages) - YouTube Data API Key
- Claude Desktop or MCP client
1. Get YouTube API Key
- Visit Google Cloud Console
- Create a new project
- Enable YouTube Data API v3
- Create API Key
- (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-herewith your actual API key uvxauto-downloads from PyPI- No manual installation needed
3. Start Using
- Restart Claude Desktop completely
- 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 trendshours_ago(int): Time range in hours, default 24max_results(int): Result count, default 10min_views(int): Min view threshold, default 100,000search_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/allhours_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 24min_videos(int): Min videos per niche, default 3top_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 ≤ 10per search - Limit to ~50 calls/day
- Use
min_viewsto 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
- Check
claude_desktop_config.jsonhasenv.YOUTUBE_API_KEYset - Ensure no extra spaces or quotes in API key
- Fully restart Claude Desktop
Q: "API quota exhausted" error
- Wait for quota reset (Pacific Time midnight)
- Request quota increase in Google Cloud Console
- Reduce search frequency or lower
max_results
Q: Claude can't find tools
- Verify
claude_desktop_config.jsonformat is correct - Fully restart Claude Desktop
- Check Claude Desktop logs for errors
Q: No search results
- Expand time range (e.g., 12h → 24h)
- Use broader keywords
- Lower
min_viewsthreshold
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/viral-shorts
- MCP Docs: https://modelcontextprotocol.io/
- FastMCP: https://github.com/jlowin/fastmcp
Start discovering viral videos with natural language! 🚀