Skip to content
Back to search

facebook-ads-library-mcp

Free, self-hosted MCP server that scrapes the public Facebook Ad Library (no API token) for competitive ad research — advertiser, copy, landing pages, CTAs, any country.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ramsesaguirre777--facebook-ads-library-mcp/badge.svg)](/listings/ramsesaguirre777--facebook-ads-library-mcp)

HTML

<a href="/listings/ramsesaguirre777--facebook-ads-library-mcp"><img src="/api/listings/ramsesaguirre777--facebook-ads-library-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 138 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Facebook Ad Library MCP
  2. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  3. [![FastMCP](https://img.shields.io/badge/FastMCP-3.x-green.svg)](https://github.com/jlowin/fastmcp)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5. A small MCP server that scrapes the **public Facebook Ad Library** for competitive ad
  6. research — from your MCP client, with no Facebook account and no API token.
  7. It exists because the paid Ad Library scrapers (Apify actors, ScrapeCreators, and friends)
  8. charge for something that is publicly visible in a browser. This just drives a headless
  9. browser instead.
  10. ## Why not the official API?
  11. Meta's `ads_archive` API only returns **political & issue ads** worldwide (and all ad
  12. types only for the EU/UK). For an ordinary commercial advertiser in most of the world it
  13. returns nothing useful — no ads, no spend, no impressions. So this server doesn't use it
  14. at all. It renders the same Ad Library web page you'd open yourself and parses the cards.
  15. ## What you get
  16. Two tools:
  17. - **`search_ad_library(query, country="MX", ...)`** — keyword search.
  18. - **`scrape_ad_library_url(url, ...)`** — scrape any Ad Library URL you already have.
  19. Both return structured records per ad:
  20. | field | meaning |
  21. |---|---|
  22. | `advertiser`, `advertiser_handle` | Page name and its `facebook.com/<handle>` |
  23. | `started_running` | first-seen date |
  24. | `ads_using_creative` | how many creatives share this copy — a rough scale signal |
  25. | `landing_url`, `landing_domain` | destination, unwrapped from the `l.facebook.com` redirect |
  26. | `cta` | the button label (`Learn more`, `Sign up`, `Send message`, …) |
  27. | `link_text` | the headline strip under the creative |
  28. | `body` | full ad copy |
  29. | `creative_image` | thumbnail URL |
  30. | `ad_details_url` | deep link to that ad's detail view |
  31. Plus an `advertisers` histogram and the `raw_markdown` of the page so the model can pull
  32. anything the parser missed.
  33. ## Install
  34. ```bash
  35. git clone https://github.com/RamsesAguirre777/facebook-ads-library-mcp.git
  36. cd facebook-ads-library-mcp
  37. python -m venv venv && source venv/bin/activate
  38. pip install -r requirements.txt
  39. python -m playwright install chromium # crawl4ai needs a browser
  40. ```
  41. ### Register with your MCP client
  42. Claude Code:
  43. ```bash
  44. claude mcp add facebook-ads -- /abs/path/venv/bin/python /abs/path/facebook_ads_mcp_complete.py
  45. ```
  46. Claude Desktop (`claude_desktop_config.json`):
  47. ```json
  48. {
  49. "mcpServers": {
  50. "facebook-ads": {
  51. "command": "/abs/path/venv/bin/python",
  52. "args": ["/abs/path/facebook_ads_mcp_complete.py"]
  53. }
  54. }
  55. }
  56. ```
  57. Restart the client.
  58. ## Usage
  59. ```
  60. "Search the Mexico Ad Library for 'automatización con inteligencia artificial',
  61. group by advertiser, and list the landing domains."
  62. "Scrape https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=MX&q=nike&search_type=keyword_unordered
  63. with scroll_rounds=15 and summarise the creative angles."
  64. ```
  65. Full discovery → website-teardown workflow: **[docs/examples.md](docs/examples.md)**.
  66. ### Parameters worth knowing
  67. - **`scroll_rounds`** (default 8) — the Ad Library is infinite-scroll; the first paint is
  68. only ~20–26 cards. Each round is a scroll-to-bottom + 2.5s wait. `0` = first render only
  69. (fast); `15+` for a deep historical sweep. It trades time for completeness.
  70. - **`wait_seconds`** (default 8) — SPA hydration wait before scraping. Raise it if results
  71. come back empty.
  72. - **`country`** — ISO code the ads were delivered in (`MX`, `US`, `ES`, …).
  73. - **`advertiser_page_id`** — target one Page's "all ads" view. This view is heavier
  74. client-rendered and doesn't always hydrate headless; a keyword search of the advertiser
  75. name is more reliable.
  76. ## How it works
  77. `crawl4ai` (`AsyncWebCrawler`) opens the Ad Library URL in headless Chromium, waits for
  78. the React app to hydrate, runs a scroll loop to trigger lazy-loaded cards, serialises the
  79. DOM to markdown, and a regex parser (`_parse_ad_library_markdown`) splits it on
  80. `Library ID:` boundaries and pulls the fields above.
  81. Facebook answers the headless browser with **HTTP 403** but still serves the rendered
  82. cards, so the tools judge success by whether cards parsed, not by status code.
  83. ## Limitations
  84. - It parses the public SPA markup, so a Facebook layout change can break field
  85. extraction. `raw_markdown` is always returned as a fallback.
  86. - `platforms` often comes back empty — the FB/IG/Messenger markers render as icons, not
  87. text, so they only survive when the page includes their labels.
  88. - No caching or rate-limit handling. If you hammer it you'll get empty results for a
  89. while; back off and raise `wait_seconds`.
  90. - Spend and impression numbers are **not available** — Meta only publishes those for
  91. political ads, and only through the API. This tool gives you creative, cadence and
  92. landing-page intelligence, not budget figures.
  93. ## Tests
  94. ```bash
  95. python -m pytest tests/ -q
  96. ```
  97. Offline — they exercise the markdown parser against a fixture.
  98. ## License
  99. MIT — see [LICENSE](LICENSE).
  100. ## Acknowledgments
  101. - [FastMCP](https://github.com/jlowin/fastmcp)
  102. - [crawl4ai](https://github.com/unclecode/crawl4ai)
  103. - [Facebook Ad Library](https://www.facebook.com/ads/library/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.