Ad Library

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 and deploy to your own Fly.io account.

Prerequisites

1. ScrapeCreators API key — sign up at scrapecreators.com
2. Fly.io account — sign up at fly.io (free tier works)
3. Fly CLI — install with brew install flyctl or see fly.io/docs/flyctl/install
4. Claude Code — 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.

Deploy (5 minutes)

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

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

Or add to .mcp.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

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:

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
GEMINI_API_KEY	No	Google AI key for analyze-creatives tool. Get at aistudio.google.com
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. 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.