# Viral Shorts
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
> 基于 MCP 协议的 YouTube Shorts 爆款视频发现工具，支持在 Claude Desktop 中使用自然语言查询
**[English](README.md)**
## 功能特性
- 🔥 发现热门 Shorts
- 📊 分析爆款潜力
- 🎯 追踪热门话题
- 🔍 发现细分趋势
- 📝 提炼视频故事
**技术栈**: YouTube Data API v3 • VPH (每小时播放量) • 互动率 • MCP 协议
---
## 快速开始
### 前置条件
- Python 3.11+ (可选，`uvx` 自动管理)
- YouTube Data API Key
- Claude Desktop 或 MCP 客户端
### 1. 获取 YouTube API Key
1. 访问 [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. 创建新项目
3. 启用 **YouTube Data API v3**
4. 创建 **API Key**
5. (推荐) 限制 API Key 仅用于 YouTube Data API v3
### 2. 配置 Claude Desktop
编辑 Claude Desktop 配置文件：
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
添加以下内容：
```json
{
"mcpServers": {
"viral-shorts": {
"command": "uvx",
"args": ["--from", "youtube-shorts-viral-agent", "shorts-server"],
"env": {
"YOUTUBE_API_KEY": "your-api-key-here"
}
}
}
}
```
**注意：**
- 将 `your-api-key-here` 替换为你的实际 API Key
- `uvx` 会自动从 PyPI 下载
- 无需手动安装
### 3. 开始使用
1. 完全重启 Claude Desktop
2. 使用自然语言查询：
```
找出最近 24 小时内的热门 AI Shorts
```
---
## 使用示例
### 示例 1: 发现热门视频
```
显示我最近 24 小时内的热门 AI Shorts
```
返回 Markdown 表格，包含：
- 标题、频道、播放量、VPH、互动率、爆款指数、发布时间
### 示例 2: 分析视频
```
分析这个视频的爆款潜力: https://www.youtube.com/shorts/abc123
```
### 示例 3: 查找热门话题
```
科技分类中有什么热门话题？
```
### 示例 4: 自定义参数
```
找出最近 12 小时内播放量超过 50 万的编程 Shorts
```
Claude 会自动提取：
- 关键词: "编程"
- 时间范围: 12 小时
- 最低播放量: 500,000
---
## 可用工具
### 1. `get_youtube_shorts_trends`
发现 YouTube Shorts 热门视频。
**参数：**
- `keyword` (字符串): 搜索关键词，留空表示全局趋势
- `hours_ago` (整数): 时间范围(小时)，默认 24
- `max_results` (整数): 返回结果数，默认 10
- `min_views` (整数): 最低播放量阈值，默认 100,000
- `search_by_tag` (布尔值): 是否按标签精确匹配，默认 false
### 2. `analyze_video_potential`
深度分析单个视频的爆款潜力。
**参数：**
- `video_url` (字符串): YouTube Shorts 视频链接
### 3. `get_trending_topics`
发现热门话题。
**参数：**
- `category` (字符串): 分类 (tech/entertainment/education/gaming/all)
- `hours_ago` (整数): 时间范围，默认 24
### 4. `summarize_video_story`
提炼视频故事梗概和核心内容。
**参数：**
- `video_url` (字符串): YouTube Shorts 视频链接
### 5. `discover_niche_trends`
发现某个主题下的细分爆款领域。
**参数：**
- `main_topic` (字符串): 主题关键词 (如 "AI", "教程")
- `hours_ago` (整数): 时间范围，默认 24
- `min_videos` (整数): 细分领域最少视频数，默认 3
- `top_niches` (整数): 返回前 N 个细分领域，默认 10
---
## 核心指标
### VPH (每小时播放量)
- **计算公式**: 总播放量 ÷ 发布时长(小时)
- **含义**: 增长速度
- **阈值**:
- ≥ 10,000: 🔥 超级爆款
- ≥ 5,000: ⭐ 高潜力
- ≥ 1,000: ✨ 有潜力
### 互动率
- **计算公式**: (点赞数 + 评论数) ÷ 播放量 × 100
- **含义**: 内容质量
- **阈值**:
- > 10%: 优秀
- > 5%: 良好
- > 2%: 一般
### 爆款指数
- **计算公式**: VPH × 时间权重 × (1 + 互动加成)
- **含义**: 综合排名分数
- **特点**:
- 新视频权重更高
- 高互动率显著提升分数
---
## API 配额管理
### YouTube Data API v3 配额
- **默认**: 10,000 单位/天
- **重置**: 每日太平洋时间午夜
### 成本明细
| 操作 | 成本 | 说明 |
|------|------|------|
| `search.list` | 100 单位 | 搜索视频 |
| `videos.list` | 1 单位 | 获取视频详情 |
| `channels.list` | 1 单位 | 获取频道信息 |
### 最佳实践
- 每次搜索保持 `max_results ≤ 10`
- 每天限制约 50 次调用
- 使用 `min_views` 过滤结果
- 用播放量判断整体热度
- 用 VPH 判断快速增长的新视频
---
## 项目结构
```
viral-shorts/
├── .env.example # MCP 配置示例
├── .gitignore # Git 忽略规则
├── LICENSE # MIT 许可证
├── README.md # 英文文档
├── README.zh.md # 中文文档
├── MCP_EXPLAINED.md # MCP 协议说明
├── pyproject.toml # PyPI 配置
├── uv.lock # 依赖锁定
├── src/
│ ├── server.py # MCP 服务器 (含详细注释)
│ ├── youtube/
│ │ ├── client.py # YouTube API 客户端
│ │ └── analyzer.py # 爆款分析引擎
│ ├── models/
│ │ └── video.py # 数据模型
│ └── utils/
│ └── config.py # 配置管理
└── tests/
└── test_youtube.py # 单元测试
```
---
## 常见问题
### Q: 出现 "YOUTUBE_API_KEY not set" 错误
1. 检查 `claude_desktop_config.json` 中是否设置了 `env.YOUTUBE_API_KEY`
2. 确保 API Key 没有多余的空格或引号
3. 完全重启 Claude Desktop
### Q: 出现 "API quota exhausted" 错误
1. 等待配额重置 (太平洋时间午夜)
2. 在 Google Cloud Console 申请配额提升
3. 降低搜索频率或减少 `max_results`
### Q: Claude 找不到工具
1. 验证 `claude_desktop_config.json` 格式是否正确
2. 完全重启 Claude Desktop
3. 检查 Claude Desktop 日志中的错误信息
### Q: 没有搜索结果
1. 扩大时间范围 (如 12 小时 → 24 小时)
2. 使用更宽泛的关键词
3. 降低 `min_views` 阈值
---
## 技术栈
- **Python**: 3.11+
- **MCP**: FastMCP 2.13.1+
- **API**: google-api-python-client 2.187.0+
- **验证**: Pydantic 2.12.4+
---
## 许可证
MIT License - 详见 [LICENSE](LICENSE)
---
## 相关链接
- **GitHub**: [https://github.com/Xeron2000/viral-shorts](https://github.com/Xeron2000/viral-shorts)
- **MCP 文档**: [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)
- **FastMCP**: [https://github.com/jlowin/fastmcp](https://github.com/jlowin/fastmcp)
---
**用自然语言发现爆款视频吧！** 🚀
