Facebook Ads Library MCP by RamsesAguirre777

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

crawl4ai (AsyncWebCrawler) opens the Ad Library URL in headless Chromium, waits for the React app to hydrate, runs a scroll loop to trigger lazy-loaded cards, serialises the DOM to markdown, and a regex parser (_parse_ad_library_markdown) splits it on Library ID: boundaries and pulls the fields above.

Facebook answers the headless browser with HTTP 403 but still serves the rendered cards, so the tools judge success by whether cards parsed, not by status code.

Limitations

• It parses the public SPA markup, so a Facebook layout change can break field extraction. raw_markdown is always returned as a fallback.
• platforms often comes back empty — the FB/IG/Messenger markers render as icons, not text, so they only survive when the page includes their labels.
• No caching or rate-limit handling. If you hammer it you'll get empty results for a while; back off and raise wait_seconds.
• Spend and impression numbers are not available — Meta only publishes those for political ads, and only through the API. This tool gives you creative, cadence and landing-page intelligence, not budget figures.

Tests

python -m pytest tests/ -q

Offline — they exercise the markdown parser against a fixture.

License

MIT — see LICENSE.

Acknowledgments

• FastMCP
• crawl4ai
• Facebook Ad Library