Back to search
facebook-ads-library-mcp
MCP serverGitHub
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
Markdown
[](/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)
- # Facebook Ad Library MCP
- [](https://www.python.org/downloads/)
- [](https://github.com/jlowin/fastmcp)
- [](https://opensource.org/licenses/MIT)
- 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
- ```bash
- 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:
- ```bash
- claude mcp add facebook-ads -- /abs/path/venv/bin/python /abs/path/facebook_ads_mcp_complete.py
- ```
- Claude Desktop (`claude_desktop_config.json`):
- ```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](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
- ```bash
- python -m pytest tests/ -q
- ```
- Offline — they exercise the markdown parser against a fixture.
- ## License
- MIT — see [LICENSE](LICENSE).
- ## Acknowledgments
- - [FastMCP](https://github.com/jlowin/fastmcp)
- - [crawl4ai](https://github.com/unclecode/crawl4ai)
- - [Facebook Ad Library](https://www.facebook.com/ads/library/)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.