# Ad Library MCP

Self-hosted MCP server for searching competitor ads and content across Meta Ad Library, Google Ads Transparency Center, Instagram, TikTok, and YouTube. All data sources are public — no ad account credentials required.

You bring your own [ScrapeCreators API key](https://scrapecreators.com) and deploy to your own [Fly.io](https://fly.io) account.

## Prerequisites

1. **ScrapeCreators API key** — sign up at [scrapecreators.com](https://scrapecreators.com)
2. **Fly.io account** — sign up at [fly.io](https://fly.io) (free tier works)
3. **Fly CLI** — install with `brew install flyctl` or see [fly.io/docs/flyctl/install](https://fly.io/docs/flyctl/install/)
4. **Claude Code** — [claude.ai/code](https://claude.ai/code)

Optional: **Gemini API key** for the `analyze-creatives` tool (AI-powered image/video analysis). Get one free at [aistudio.google.com/apikey](https://aistudio.google.com/apikey).

## Deploy (5 minutes)

```bash
# 1. Clone and install
git clone https://github.com/superpower-growth/ad-library-mcp.git
cd ad-library-mcp
npm install

# 2. Deploy to Fly.io
fly auth login
fly launch          # Creates your app — say yes to defaults

# 3. Set your API keys as secrets
fly secrets set SCRAPECREATORS_API_KEY=your-scrapecreators-key
fly secrets set GEMINI_API_KEY=your-gemini-key   # optional

# 4. Deploy
fly deploy

# 5. Verify it's running
curl https://YOUR-APP-NAME.fly.dev/health
```

`fly launch` will assign your app a unique name (e.g. `my-ad-library-mcp`). Use that name in the URL below.

## Connect to Claude Code

Once deployed, add it to Claude Code with your app's URL:

```bash
claude mcp add ad-library --transport http https://YOUR-APP-NAME.fly.dev/mcp
```

Or add to `.mcp.json`:

```json
{
  "ad-library": {
    "type": "http",
    "url": "https://YOUR-APP-NAME.fly.dev/mcp"
  }
}
```

Replace `YOUR-APP-NAME` with the name from `fly launch`.

## Local Development

```bash
cp .env.example .env
# Edit .env — add your ScrapeCreators API key (required)

npm run dev          # Starts on http://localhost:3002
```

Test locally with Claude Code:

```bash
claude mcp add ad-library-local --transport http http://localhost:3002/mcp
```

## Tools

| Tool | Platform | What it does |
|------|----------|-------------|
| `resolve-company` | Cross-platform | Find a company using 5 parallel strategies: name search, domain lookup, keyword search, website scrape, and active ad count verification. Returns confidence-ranked matches. |
| `meta-search-ads` | Meta | Search ads by keyword or company page ID. Configurable limit (1-1000). |
| `meta-get-ad` | Meta | Full ad details: copy, carousel cards (per-card content), caption, video URLs, targeting, transcript, Ad Library link. |
| `google-search-ads` | Google | List ads by domain or advertiser ID. Optional full details (headlines, descriptions, impressions, regions). |
| `google-get-ad` | Google | Full ad details: creative variations, OCR text, impression ranges, regional breakdown, Transparency Center link. |
| `analyze-creatives` | Cross-platform | Batch Gemini AI analysis of images and videos: visual descriptions, text overlay extraction, full verbatim transcripts, messaging themes, hooks. Requires Gemini API key. |
| `ig-search-reels` | Instagram | Search Reels by keyword, ranked by viral ratio (views / followers). BREAKOUT/STRONG/GOOD labels. |
| `ig-get-profile` | Instagram | Creator profile with top Reels sorted by views and viral ratio. |
| `ig-get-transcript` | Instagram | Transcribe a Reel via ScrapeCreators (Gemini AI fallback). |
| `tiktok-search-videos` | TikTok | Search videos by keyword or #hashtag, ranked by viral ratio. Auto-detects hashtags. |
| `tiktok-get-profile` | TikTok | Creator profile with top videos ranked by views and viral ratio. |
| `tiktok-get-comments` | TikTok | Video comments sorted by likes. Optional keyword filter for finding audience pain points. |
| `youtube-search-creators` | YouTube | Search creators in a niche, ranked by median views/subscribers across surfaced videos. Returns subs, top videos, and view/like/comment engagement as % of subscribers. |
| `youtube-get-profile` | YouTube | Channel profile + top videos with views/likes/comments expressed as % of subscribers. Useful for benchmarking against audience size. |

## How resolve-company Works

The most important tool — finds the right brand across platforms using a 2-phase approach that minimizes API credits.

**Phase 1 (always runs, ~3 credits):**

| Strategy | What it does | Cost |
|----------|-------------|------|
| 1. Name search | Searches Meta companies + Google advertisers by brand name | 2 credits |
| 2. Domain lookup | Infers domain from name, searches Google by domain | 1 credit |
| 4. Website scrape | Fetches homepage, parses for Facebook page link | Free |

**Phase 2 (only if Phase 1 result is ambiguous, +1-4 credits):**

| Strategy | What it does | Cost |
|----------|-------------|------|
| 3. Keyword search | Searches Meta ads for the domain in ad content — finds partner/influencer pages | 1 credit |
| 5. Ad count verify | Checks active ad count on top Meta pages — strongest signal | 1 credit each (up to 3) |

**Caching:** Results cached for 10 minutes. Second lookup for the same brand is instant (0 credits).

## Usage Flow

```
1. resolve-company query="<brand name>"
   -> Confidence-ranked matches with Page IDs, Advertiser IDs, active ad counts

2. meta-search-ads page_id="<page_id>" limit=10
   -> Newest ads with copy, format, CTA, carousel card count, and Ad Library links

3. meta-get-ad id="<ad_id>" get_transcript=true
   -> Full ad detail: carousel cards with per-card content, caption, video transcript, targeting

4. google-search-ads domain="<domain>" get_ad_details=true
   -> Headlines, descriptions, impressions, regions, landing pages, Transparency Center links

5. analyze-creatives creatives=[{url: "<image_or_video_url>", type: "video"}]
   -> Batch AI analysis: visual descriptions, full verbatim transcript, messaging themes, hooks

6. ig-search-reels query="<keyword>"
   -> Reels ranked by viral ratio (views / followers)

7. tiktok-search-videos query="<keyword>"
   -> Videos ranked by viral ratio (views / followers)

8. youtube-search-creators query="<niche>"
   -> Creators ranked by median views/subscribers
```

## Environment Variables

Set as Fly.io secrets (`fly secrets set KEY=value`) or in `.env` for local dev.

| Variable | Required | Description |
|----------|----------|-------------|
| `SCRAPECREATORS_API_KEY` | Yes | API key from [scrapecreators.com](https://scrapecreators.com) |
| `GEMINI_API_KEY` | No | Google AI key for `analyze-creatives` tool. Get at [aistudio.google.com](https://aistudio.google.com/apikey) |
| `GEMINI_MODEL` | No | Gemini model (default: `gemini-2.5-flash`) |
| `PORT` | No | Server port (default: 3002) |

## CI/CD (Optional)

The repo includes a GitHub Actions workflow (`.github/workflows/fly-deploy.yml`) that auto-deploys on push to `main`. To use it:

1. Fork the repo
2. Add your Fly.io API token as a GitHub secret named `FLY_API_TOKEN`
   - Generate one with `fly tokens create deploy -x 999999h`
3. Push to `main` — it deploys automatically

## Data Sources

- **Meta Ad Library** — via [ScrapeCreators API](https://scrapecreators.com). Ad copy, images, video URLs, CTA, impressions, spend, targeting, carousel cards, transcripts.
- **Google Ads Transparency Center** — via ScrapeCreators API. Headlines, descriptions, impressions, regions, creative variations, OCR text.
- **Instagram** — via ScrapeCreators API. Reels search, profile data, user reels with play counts, built-in transcription. Viral ratio ranking (views / followers) for identifying breakout content.
- **TikTok** — via ScrapeCreators API. Keyword and hashtag video search, creator profiles, video comments with keyword filtering. Viral ratio ranking for identifying breakout content.
- **YouTube** — via ScrapeCreators API. Niche search across videos and shorts, channel details with subscriber counts, top videos with views/likes/comments, all engagement signals expressed as % of subscribers.
- **Gemini AI** — optional. Batch image/video analysis with visual descriptions, full verbatim transcripts, and messaging theme classification.