内容
# 广告库 MCP
自托管的MCP服务器，用于搜索竞争对手的广告和内容，涵盖 Meta 广告库、谷歌广告透明度中心、Instagram、TikTok 和 YouTube。所有数据源均为公开 - 无需广告账户凭证。
您需要提供自己的 [ScrapeCreators API 密钥](https://scrapecreators.com) 并部署到您自己的 [Fly.io](https://fly.io) 账户。
## 前置条件
1. **ScrapeCreators API 密钥** - 在 [scrapecreators.com](https://scrapecreators.com) 注册
2. **Fly.io 账户** - 在 [fly.io](https://fly.io) 注册（免费层级可用）
3. **Fly CLI** - 使用 `brew install flyctl` 安装或查看 [fly.io/docs/flyctl/install](https://fly.io/docs/flyctl/install/)
4. **Claude 代码** - [claude.ai/code](https://claude.ai/code)
可选：`analyze-creatives` 工具的 **Gemini API 密钥**（AI 驱动的图像/视频分析）。在 [aistudio.google.com/apikey](https://aistudio.google.com/apikey) 免费获取。
## 部署（5分钟）
```bash
# 1. 克隆并安装
git clone https://github.com/superpower-growth/ad-library-mcp.git
cd ad-library-mcp
npm install
# 2. 部署到 Fly.io
fly auth login
fly launch # 创建您的应用 - 默认设置确认 yes
# 3. 将 API 密钥设置为机密
fly secrets set SCRAPECREATORS_API_KEY=您的-scrapecreators-密钥
fly secrets set GEMINI_API_KEY=您的-gemini-密钥 # 可选
# 4. 部署
fly deploy
# 5. 验证它是否运行
curl https://您的应用名称.fly.dev/health
```
`fly launch` 将为您的应用分配一个唯一名称（例如 `my-ad-library-mcp`）。在下面的 URL 中使用该名称。
## 连接到 Claude 代码
部署后，使用您的应用 URL 将其添加到 Claude 代码：
```bash
claude mcp add ad-library --transport http https://您的应用名称.fly.dev/mcp
```
或添加到 `.mcp.json`：
```json
{
"ad-library": {
"type": "http",
"url": "https://您的应用名称.fly.dev/mcp"
}
}
```
将 `您的应用名称` 替换为 `fly launch` 中的名称。
## 本地开发
```bash
cp .env.example .env
# 编辑 .env - 添加您的 ScrapeCreators API 密钥（必需）
npm run dev # 在 http://localhost:3002 启动
```
使用 Claude 代码在本地测试：
```bash
claude mcp add ad-library-local --transport http http://localhost:3002/mcp
```
## 工具
| 工具 | 平台 | 功能 |
|------|----------|-------------|
| `resolve-company` | 跨平台 | 使用 5 种并行策略查找公司：名称搜索、域名查找、关键词搜索、网站爬取和活跃广告数量验证。返回置信度排名的匹配结果。 |
| `meta-search-ads` | Meta | 按关键词或公司页面 ID 搜索广告。可配置限制（1-1000）。 |
| `meta-get-ad` | Meta | 广告详细信息：复制、轮播卡（每张卡的内容）、标题、视频 URL、定位、转录、广告库链接。 |
| `google-search-ads` | Google | 按域名或广告商 ID 列出广告。可选完整详细信息（标题、描述、印象、地区）。 |
| `google-get-ad` | Google | 广告详细信息：创意变体、OCR 文本、印象范围、地区分解、透明度中心链接。 |
| `analyze-creatives` | 跨平台 | 批量 Gemini AI 分析图像和视频：视觉描述、文本叠加提取、完整逐字转录、消息主题、钩子。需要 Gemini API 密钥。 |
| `ig-search-reels` | Instagram | 按关键词搜索 Reels，按病毒比率（观看次数/关注者）排名。BREAKOUT/STRONG/GOOD 标签。 |
| `ig-get-profile` | Instagram | 创作者资料，顶部 Reels 按观看次数和病毒比率排序。 |
| `ig-get-transcript` | Instagram | 通过 ScrapeCreators（Gemini AI 备用）转录 Reels。 |
| `tiktok-search-videos` | TikTok | 按关键词或 #hashtag 搜索视频，按病毒比率排名。自动检测哈希标签。 |
| `tiktok-get-profile` | TikTok | 创作者资料，顶部视频按观看次数和病毒比率排名。 |
| `tiktok-get-comments` | TikTok | 视频评论按点赞数排序。可选关键词过滤器，用于查找受众痛点。 |
| `youtube-search-creators` | YouTube | 在特定领域搜索创作者，按中位观看次数/订阅者排名。返回订阅者、顶部视频和观看/点赞/评论参与度占订阅者的百分比。 |
| `youtube-get-profile` | YouTube | 频道资料 + 顶部视频，观看次数/点赞/评论表示为订阅者的百分比。对于根据受众规模进行基准测试很有用。 |
## resolve-company 工作原理
最重要的工具 - 使用两阶段方法在平台间查找正确的品牌，尽量减少 API 积分。
**第一阶段（始终运行，约 3 积分）：**
| 策略 | 功能 | 成本 |
|----------|-------------|------|
| 1. 名称搜索 | 在 Meta 公司和 Google 广告商中按品牌名称搜索 | 2 积分 |
| 2. 域名查找 | 从名称推断域名，在 Google 中按域名搜索 | 1 积分 |
| 4. 网站爬取 | 获取首页，解析 Facebook 页面链接 | 免费 |
**第二阶段（仅当第一阶段结果不明确时，+1-4 积分）：**
| 策略 | 功能 | 成本 |
|----------|-------------|------|
| 3. 关键词搜索 | 在 Meta 广告中搜索域名的广告内容 - 查找合作伙伴/影响者页面 | 1 积分 |
| 5. 广告数量验证 | 检查顶部 Meta 页面的活跃广告数量 - 最强的信号 | 每个最多 3 个积分 |
**缓存：** 结果缓存 10 分钟。第二次查找同一品牌即时（0 积分）。
## 使用流程
```
1. resolve-company query="<品牌名称>"
-> 置信度排名的匹配结果，包含页面 ID、广告商 ID 和活跃广告数量
2. meta-search-ads page_id="<页面 ID>" limit=10
-> 最新广告，包含复制、格式、CTA、轮播卡数量和广告库链接
3. meta-get-ad id="<广告 ID>" get_transcript=true
-> 广告详细信息：轮播卡和每张卡的内容、标题、视频转录、定位
4. google-search-ads domain="<域名>" get_ad_details=true
-> 标题、描述、印象、地区、着陆页和透明度中心链接
5. analyze-creatives creatives=[{url: "<图像或视频 URL>", type: "video"}]
-> 批量 AI 分析：视觉描述、完整逐字转录、消息主题、钩子
6. ig-search-reels query="<关键词>"
-> Reels 按病毒比率（观看次数/关注者）排名
7. tiktok-search-videos query="<关键词>"
-> 视频按病毒比率（观看次数/关注者）排名
8. youtube-search-creators query="<领域>"
-> 创作者按中位观看次数/订阅者排名
```
## 环境变量
在 Fly.io 机密（`fly secrets set KEY=value`）或本地开发的 `.env` 中设置。
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `SCRAPECREATORS_API_KEY` | 是 | 来自 [scrapecreators.com](https://scrapecreators.com) 的 API 密钥 |
| `GEMINI_API_KEY` | 否 | 用于 `analyze-creatives` 工具的 Google AI 密钥。在 [aistudio.google.com](https://aistudio.google.com/apikey) 获取 |
| `GEMINI_MODEL` | 否 | Gemini 模型（默认：`gemini-2.5-flash`） |
| `PORT` | 否 | 服务器端口（默认：3002） |
## CI/CD（可选）
存储库中包含一个 GitHub Actions 工作流（`.github/workflows/fly-deploy.yml`），在推送到 `main` 时自动部署。要使用它：
1. 分叉存储库
2. 将 Fly.io API 令牌添加为 GitHub 机密，命名为 `FLY_API_TOKEN`
- 使用 `fly tokens create deploy -x 999999h` 生成
3. 推送到 `main` - 自动部署
## 数据源
- **Meta 广告库** - 通过 [ScrapeCreators API](https://scrapecreators.com)。广告复制、图像、视频 URL、CTA、印象、花费、定位、轮播卡、转录。
- **谷歌广告透明度中心** - 通过 ScrapeCreators API。标题、描述、印象、地区、创意变体、OCR 文本。
- **Instagram** - 通过 ScrapeCreators API。Reels 搜索、资料数据、用户 Reels 带有播放次数、内置转录。病毒比率排名（观看次数/关注者）用于识别爆款内容。
- **TikTok** - 通过 ScrapeCreators API。关键词和哈希标签视频搜索、创作者资料、视频评论带有关键词过滤。病毒比率排名用于识别爆款内容。
- **YouTube** - 通过 ScrapeCreators API。跨视频和短视频的领域搜索、频道详细信息带有订阅者数量、顶部视频带有观看次数/点赞/评论，所有参与度信号表示为订阅者的百分比。
- **Gemini AI** - 可选。批量图像/视频分析带有视觉描述、完整逐字转录和消息主题分类。
