Facebook Ad Library MCP

A small MCP server that scrapes the public Facebook Ad Library for competitive ad research — from your MCP client, with no Facebook account and no API token.

It exists because the paid Ad Library scrapers (Apify actors, ScrapeCreators, and friends) charge for something that is publicly visible in a browser. This just drives a headless browser instead.

Why not the official API?

Meta's ads_archive API only returns political & issue ads worldwide (and all ad types only for the EU/UK). For an ordinary commercial advertiser in most of the world it returns nothing useful — no ads, no spend, no impressions. So this server doesn't use it at all. It renders the same Ad Library web page you'd open yourself and parses the cards.

What you get

Two tools:

• search_ad_library(query, country="MX", ...) — keyword search.
• scrape_ad_library_url(url, ...) — scrape any Ad Library URL you already have.

Both return structured records per ad:

field	meaning
advertiser, advertiser_handle	Page name and its facebook.com/<handle>
started_running	first-seen date
ads_using_creative	how many creatives share this copy — a rough scale signal
landing_url, landing_domain	destination, unwrapped from the l.facebook.com redirect
cta	the button label (Learn more, Sign up, Send message, …)
link_text	the headline strip under the creative
body	full ad copy
creative_image	thumbnail URL
ad_details_url	deep link to that ad's detail view

Plus an advertisers histogram and the raw_markdown of the page so the model can pull anything the parser missed.

Install

git clone https://github.com/RamsesAguirre777/facebook-ads-library-mcp.git
cd facebook-ads-library-mcp
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python -m playwright install chromium   # crawl4ai needs a browser

Register with your MCP client

Claude Code:

claude mcp add facebook-ads -- /abs/path/venv/bin/python /abs/path/facebook_ads_mcp_complete.py

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "facebook-ads": {
      "command": "/abs/path/venv/bin/python",
      "args": ["/abs/path/facebook_ads_mcp_complete.py"]
    }
  }
}

Restart the client.

Usage

"Search the Mexico Ad Library for 'automatización con inteligencia artificial',
 group by advertiser, and list the landing domains."

"Scrape https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=MX&q=nike&search_type=keyword_unordered
 with scroll_rounds=15 and summarise the creative angles."

Full discovery → website-teardown workflow: docs/examples.md.

Parameters worth knowing

• scroll_rounds (default 8) — the Ad Library is infinite-scroll; the first paint is only ~20–26 cards. Each round is a scroll-to-bottom + 2.5s wait. 0 = first render only (fast); 15+ for a deep historical sweep. It trades time for completeness.
• wait_seconds (default 8) — SPA hydration wait before scraping. Raise it if results come back empty.
• country — ISO code the ads were delivered in (MX, US, ES, …).
• advertiser_page_id — target one Page's "all ads" view. This view is heavier client-rendered and doesn't always hydrate headless; a keyword search of the advertiser name is more reliable.

How it works