# Viral Shorts

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](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!** 🚀