Metadata-Version: 2.4
Name: youtube-shorts-viral-agent
Version: 0.3.1
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
Requires-Dist: httpx>=0.25.0
Dynamic: license-file

# 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**: Invidious API (Free) • Official YouTube API (Optional) • VPH (Views Per Hour) • Engagement Rate • MCP Protocol

---

## Quick Start

### Prerequisites

- Python 3.11+ (optional, `uvx` auto-manages)
- Claude Desktop or MCP client
- No API keys required! ✨ (uses free Invidious API by default)

### 1. Configure Claude Desktop

Edit Claude Desktop config:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

#### Option A: Free API Only (Recommended)

```json
{
  "mcpServers": {
    "viral-shorts": {
      "command": "uvx",
      "args": ["--from", "youtube-shorts-viral-agent", "shorts-server"]
    }
  }
}
```

#### Option B: With Official YouTube API (Optional)

If you want to enable the official YouTube API as a fallback:

```json
{
  "mcpServers": {
    "viral-shorts": {
      "command": "uvx",
      "args": ["--from", "youtube-shorts-viral-agent", "shorts-server"],
      "env": {
        "YOUTUBE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

**Note:** 
- Default: Uses free Invidious API (no API keys needed)
- Optional: Set `YOUTUBE_API_KEY` to enable official API as fallback
- `uvx` auto-downloads from PyPI
- No manual installation needed

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

---

## Data Sources

### Primary: Invidious API (Free)

- **Free**: No API keys required
- **Unlimited**: No quota restrictions
- **Fast**: Optimized for search and trending
- **Privacy-focused**: Alternative YouTube API
- **Default**: Always used first

### Fallback: Official YouTube API (Optional)

- **Requires**: YouTube Data API v3 key
- **Fallback**: Only used if Invidious fails
- **Enabled**: Only when `YOUTUBE_API_KEY` is set
- **Quota**: Limited by Google's quota system

### Automatic Fallback Strategy

1. **First attempt**: Invidious API (free, no quota)
2. **If fails**: Official YouTube API (if configured)
3. **If both fail**: Returns error with helpful message

This ensures reliable operation while keeping costs at zero by default.

### Rate Limiting

- **Invidious**: Generous rate limits with automatic backoff
- **Official API**: Respects Google's quota system
- **Exponential Backoff**: Automatic retry with jitter

---

## 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: "No search results" error

1. Expand time range (e.g., 12h → 24h)
2. Use broader keywords
3. Lower `min_views` threshold
4. Check internet connection

### 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: Invidious API is slow or unavailable

1. The system automatically falls back to yt-dlp
2. Try again - fallback sources are being used
3. Check your internet connection

### Q: Why no API key needed?

1. Uses free Invidious API (no authentication required)
2. Falls back to yt-dlp for reliability
3. No quota limits or costs
4. Unlimited requests

---

## Tech Stack

- **Python**: 3.11+
- **MCP**: FastMCP 2.13.1+
- **Primary API**: Invidious (free)
- **Fallback API**: Official YouTube API v3 (optional)
- **HTTP Client**: httpx 0.25.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!** 🚀
