Metadata-Version: 2.4
Name: youtube-shorts-viral-agent
Version: 0.2.2
Summary: MCP-powered YouTube Shorts discovery tool for finding viral videos using VPH and engagement analysis
Author: Xeron
License: MIT License
        
        Copyright (c) 2025 Xeron
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: youtube,shorts,mcp,viral,analytics,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.13.1
Requires-Dist: google-api-python-client>=2.187.0
Requires-Dist: pydantic>=2.12.4
Dynamic: license-file

# YouTube Shorts Viral Agent

[![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

## 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": {
    "youtube-shorts-viral": {
      "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

### 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

```
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](LICENSE)

---

## Links

- **GitHub**: [https://github.com/Xeron2000/shorts](https://github.com/Xeron2000/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!** 🚀
