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

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

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

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.

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.