Skip to main content
Glama
konstantin-tradient

Meta Ad Library MCP

by konstantin-tradient
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Meta Ad Library MCP

An MCP server that searches the Meta (Facebook) Ad Library by keyword and returns each ad's advertiser, full ad copy, and EU reach (per‑country / age / gender breakdown) — the data the official Ad Library API does not expose for commercial ads.

It works by driving the public Ad Library like a real user (Playwright + your real Chrome) and reading the page's own data — no API key, no login required.

search_ads("dental implants", country="DE", limit=50, fetch_reach=True)
  → 50 advertisers + ad copy + EU reach, ranked

Requirements

  • A residential internet connection. Meta rd_challenge‑403s datacenter IPs (AWS/GCP/VPS) within seconds. On a normal home/office machine it just works; on a server you must set RESIDENTIAL_PROXY_URL (see Hosting).

  • Python 3.10+

  • Google Chrome installed (the server launches your real Chrome for a clean fingerprint). No Chrome? Set META_ADS_CHANNEL="" to use Playwright's bundled Chromium.

Related MCP server: AdWhispr MCP Server

Install (uv — recommended)

git clone https://github.com/konstantin-tradient/meta-ad-library-mcp.git
cd meta-ad-library-mcp
uv sync                          # creates an isolated venv from pyproject.toml
uv run playwright install chromium

Quick local check (no MCP client needed):

uv run python smoke.py "dental implants" DE     # live: search + reach
uv run --extra dev pytest -q                    # offline parser test
py -m pip install -r requirements.txt && py -m playwright install chromium   # Windows
python3 -m pip install -r requirements.txt && python3 -m playwright install chromium

Then run/register with py -m meta_ads_mcp.server + --env PYTHONPATH=<dir>.

No-clone install (uvx)

To use it on a machine without cloning, uvx fetches + builds straight from GitHub. Install Chromium once, then register the connector:

# one-time: download the browser into the shared cache
uvx --from playwright playwright install chromium

# Claude Code — pin a tag so deps don't drift
claude mcp add meta-ads --scope user -- \
  uvx --from git+https://github.com/konstantin-tradient/meta-ad-library-mcp.git@v0.1.0 meta-ads-mcp

(Claude Desktop: "command": "/full/path/to/uvx", "args": ["--from", "git+https://github.com/konstantin-tradient/meta-ad-library-mcp.git@v0.1.0", "meta-ads-mcp"].)

Use this for machines that only run the tool. To develop it, clone + uv run below (so your local edits apply and uv.lock pins deps). If you hit a "browser not found" error, re-run playwright install chromium.

Connect it to Claude (from a clone)

The MCP command is just uv run --directory <clone> meta-ads-mcp — uv auto-syncs the venv, so there's nothing to install globally.

Claude Code (CLI)

# --scope user = available in every project. Use the clone's ABSOLUTE path.
claude mcp add meta-ads --scope user -- uv run --directory /abs/path/to/meta-ad-library-mcp meta-ads-mcp

Restart Claude Code, then ask: "search the Meta Ad Library for dental implants in Germany."

Claude Desktop (Mac/Windows app)

Edit claude_desktop_config.json (Windows: %APPDATA%\Claude\, macOS: ~/Library/Application Support/Claude/) and add under mcpServers (use the **full path to uv** — which uv / where uv):

"meta-ads": {
  "command": "/full/path/to/uv",
  "args": ["run", "--directory", "/abs/path/to/meta-ad-library-mcp", "meta-ads-mcp"]
}

Fully quit and reopen Claude Desktop (tray → Quit). The tools appear in the chat.

claude.ai (web) can't run a local server — it only connects to remote MCP servers (public HTTPS URL + auth). See Hosting.

Tools

Tool

Returns

search_ads(keyword, country="ALL", limit=20, fetch_reach=False, min_reach=0, stop_after_below=5)

{count, ads:[{library_id, page_name, status, body_text, cta, link_url, start_date, end_date, versions, eu_total_reach?, uk_total_reach?, reach_breakdown?}], reach_meta?}

get_ad_details(keyword, library_id, country="ALL")

{library_id, eu_total_reach, uk_total_reach, gender_audience, age_audience, location_audience, reach_breakdown:[{country, age_gender:[{age_range, male, female, unknown}]}]}

session_status()

{ready, egress_ip, proxy, last_challenge}

  • Use an EU country code (DE, FR, NL…) to surface ads that carry EU‑reach data. Ads not delivered in the EU have eu_total_reach = null (Meta's design).

  • fetch_reach=True clicks every result in one warm session (~3–4s/ad) — great for ≤50; otherwise list fast and pull reach per‑ad with get_ad_details.

Top-ads-by-reach (min_reach)

Meta exposes no reach or impressions in the list and offers no reach sort — the only number is eu_total_reach, behind a click per ad. But Meta orders the list by impressions (descending), which is ~monotonic with reach. So:

search_ads("biosila.bg", country="BG", limit=300, fetch_reach=True, min_reach=1000)
  → only ads with EU reach ≥ 1000, sorted reach-desc

It walks Meta's order, clicking for reach, and stops after stop_after_below consecutive ads fall below min_reach (the rest, lower in the order, are assumed below too) — so you get the top‑by‑reach set after ~40 clicks instead of 800+. reach_meta reports {checked, stopped_early}. Raise stop_after_below for multi‑advertiser keywords where impressions‑order is noisier vs. reach.

How it works

  • rd_challenge is a soft gate — the first request 403s but sets a clearance cookie; the server warms the session (homepage → library landing) and retries, which clears it. (This is what made headless work without a paid API.)

  • List = the page's own GraphQL, not DOM scraping. search_ads reads the SSR'd first page (embedded JSON) + AdLibrarySearchPaginationQuery captured on scroll, so advertiser + ad copy are reliable for every ad (incl. image/video), and it paginates to 50+.

  • Reach comes from AdLibraryV3AdDetailsQuery, which only fires when you click an ad's "See ad details" on the search page — so reach is gathered by clicking, either in batch (fetch_reach=True) or per‑ad (get_ad_details).

Environment variables

Var

Default

Purpose

RESIDENTIAL_PROXY_URL

–

http://user:pass@host:port — route Meta traffic through a residential proxy (required on datacenter hosts)

META_ADS_CHANNEL

chrome

Browser channel; set "" to use Playwright's bundled Chromium

META_ADS_HEADFUL

–

1 to show the browser window (default headless)

META_ADS_PROFILE

~/.meta-ads-profile

Persistent browser profile dir (keeps the warm session)

Hosting / remote (claude.ai)

Runs locally on a residential IP for free — ideal for interactive use. To reach it from claude.ai (web) or run it 24/7 on a server, you need:

  1. HTTP transport — switch mcp.run() to streamable-http in server.py.

  2. A public HTTPS endpoint with auth (claude.ai connectors expect OAuth).

  3. Residential egress — set RESIDENTIAL_PROXY_URL; there is no free way around the datacenter‑IP rd_challenge.

Legal

This automates access to a public transparency tool for competitive research. It nonetheless falls under Meta's automated‑access terms — use a disposable/burner account if you host it, pace conservatively, and don't hammer. Provided as‑is.

Available Tools

3 tools
get_ad_detailsA

Fetch one ad's EU/UK reach + per-country/age/gender breakdown.

Args: keyword: the same keyword you searched (reach only loads from the keyword-search page, so we re-find the ad there). library_id: the ad's Library ID (from search_ads). country: ISO-2 country code, or "ALL". Returns: {library_id, eu_total_reach, uk_total_reach, gender_audience, age_audience, location_audience, reach_breakdown:[{country, age_gender:[...]}]}. Note: ads not delivered in the EU have eu_total_reach=null (Meta's design).

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordYes
library_idYes
countryNoALL

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the keyword is used to re-find the ad, the country default is 'ALL', and includes a critical behavioral trait: 'ads not delivered in the EU have eu_total_reach=null (Meta's design)'. This goes beyond basic purpose to inform the agent of important edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with 'Args' and 'Returns' sections, and a note. Every sentence adds value: purpose, parameter descriptions, return structure, and a crucial behavioral note. No redundant or vague statements.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, no output schema, and moderate complexity, the description covers all necessary aspects: what the tool does, how to use parameters, the return value structure, and an important null case. It is fully self-contained for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no descriptions in input schema), so the description must explain each parameter. It does so effectively: keyword is the search keyword used earlier, library_id is from search_ads, and country is ISO-2 or 'ALL'. This adds valuable context beyond the schema's type and title.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Fetch one ad's EU/UK reach + per-country/age/gender breakdown', specifying the verb 'fetch', the resource 'ad', and the detailed data returned. It distinguishes from sibling tools 'search_ads' (which searches for ads) and 'session_status' (which checks session) by focusing on fetching details for a single ad.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit prerequisites: keyword must be the same as used in search, and library_id must come from search_ads. It also explains the purpose of each argument and the default for country. While it does not explicitly state when not to use, it implies usage after search_ads, which is sufficient given distinct sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_adsA

Search the Meta Ad Library by keyword — returns the advertiser + description for each ad (supports loading 50+). Fast by default.

Args: keyword: free-text query (e.g. "dental implants"). country: ISO-2 country code (e.g. "DE", "AE"); use an EU country to find ads with EU-reach data. "ALL" = no country filter. limit: max ads to return (paginates by scrolling; 50 is fine). fetch_reach: if True, also clicks each result in one warm session to add eu_total_reach + breakdown (slower: ~3-4s/ad; use for ≤50). Returns: {keyword, country, count, ads:[{library_id, page_name, status, body_text, cta, link_url, start_date, end_date, versions, eu_total_reach?, uk_total_reach?, reach_breakdown?}]}. Ads not delivered in the EU have eu_total_reach=null (Meta's design). For a single ad's reach later, use get_ad_details(keyword, library_id, country).

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordYes
countryNoALL
limitNo
fetch_reachNo

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behaviors: returns specific fields, supports loading 50+, paginates by scrolling, fetch_reach makes additional requests (slower), eu_total_reach null for non-EU ads (Meta's design). No annotations provided, but description fully covers safety and performance traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and capacity. Parameter details follow in structured list. Slightly verbose but each sentence provides value. Could tighten the return format description, but overall well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and 0% schema coverage, the description thoroughly covers all needed context: parameter semantics, return structure, behavioral notes (paginate, slow fetch_reach), and even references sibling tool. Edge cases (null reach) are explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has no parameter descriptions (0% coverage). Description fully compensates with detailed explanations for all 4 parameters: keyword, country (with ISO-2 and 'ALL'), limit (pagination), fetch_reach (slower, use for ≤50). Also clarifies return format and edge cases.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'search' + resource 'Meta Ad Library' with keyword. Mentions returns advertiser + description and capacity (50+). Distinguishes from sibling get_ad_details by scope (multiple vs single ad).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly explains when to use (search by keyword) and when not to (use get_ad_details for a single ad's reach). Provides parameter usage details: keyword free-text, country ISO-2 with 'ALL' no filter, EU for reach, limit with pagination, fetch_reach slower for ≤50.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_statusA

Health check: is the browser ready, what egress IP, any recent challenge?

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It discloses the tool is a health check but does not mention whether it's read-only, if it has side effects, or any rate limits. Behavior is minimally described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the purpose. Every word serves a function with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the key aspects of the health check but does not detail the response format or data types. Given no output schema, slightly more detail would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters, the schema coverage is trivially 100%. The description adds no parameter info, but none is needed. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it's a health check for browser readiness, egress IP, and recent challenges. This distinguishes it from sibling tools get_ad_details and search_ads which are ad-specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives or any prerequisites. The description only states what it does, not when it should be invoked.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
Disambiguation5/5

Each tool has a clear, distinct purpose: search_ads for searching ads, get_ad_details for fetching detailed reach data on a specific ad, and session_status for health check. No overlap or confusion.

Naming Consistency4/5

Tool names mostly follow verb_noun pattern (get_ad_details, search_ads), but session_status deviates slightly (noun_noun). Overall consistent and readable.

Tool Count3/5

With only 3 tools, the server feels under-scoped for a full-fledged ad library. While each tool is useful, additional tools like listing recent ads or managing collections would improve coverage.

Completeness2/5

Obvious gaps exist: no tool to retrieve ad creative (images, videos) or to list ads by advertiser. The surface focuses on search and reach data but misses core ad details.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/konstantin-tradient/meta-ad-library-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server