# Viral Shorts
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
> MCP-powered YouTube Shorts discovery tool for finding viral videos using natural language in Claude Desktop
**[中文文档](README.zh.md)**
## 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](https://console.cloud.google.com/apis/credentials)
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:
```json
{
"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
### 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
---
## 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](LICENSE)
---
## Links
- **GitHub**: [https://github.com/Xeron2000/viral-shorts](https://github.com/Xeron2000/viral-shorts)
- **MCP Docs**: [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)
- **FastMCP**: [https://github.com/jlowin/fastmcp](https://github.com/jlowin/fastmcp)
---
**Start discovering viral videos with natural language!** 🚀
