Meta Ads MCP: Ad Library tools, parameters and limits
How Proxy's Meta Ads MCP reads the Facebook and Instagram Ad Library: every parameter, accepted values, paging, cursors, credit cost and failure modes.
There are two kinds of Meta Ads MCP. One manages your own ad account. Proxy is the other kind: it reads the public Meta Ad Library, so an assistant can pull any brand’s Facebook and Instagram ads. It is read-only and never connects to an ad account.
This page documents exactly how the three Meta tools behave. For the short parameter tables, see the Meta tool reference.
Connect
One endpoint serves every client and every platform:
https://mcp.useproxy.dev/mcp?ref=docs
Sign-in is OAuth, with no API keys. Steps per client are in Connect your client, with deeper notes for Claude, ChatGPT and Claude Code.
Which tool fires when
| You ask for | Tool chain |
|---|---|
| A brand’s current ads | get_meta_ads with the brand name |
| A brand with an ambiguous name | get_meta_platform_id, then get_meta_ads with the chosen page_id |
| Ads about a topic, no brand known | search_meta_ads_by_keyword |
| Creator or partnership ads for a brand | search_meta_ads_by_keyword with the brand handle, domain or hashtag |
| A transcript or visual breakdown | analyze_ad_video or analyze_ad_image with the ad_id |
get_meta_ads accepts brand names directly. A name that is not all digits is resolved to its top-ranked page, so the lookup step is only needed when you want to choose between pages.
get_meta_platform_id
Finds the Meta pages that match a brand.
| Parameter | Type | Behaviour |
|---|---|---|
brand_names |
string or list | One name, or a list looked up in parallel |
- Returns up to three candidates per brand:
page_id,name,verification,ig_followers,image_uri. - Candidates are ranked by how closely the page name matches the query, then by Instagram followers, with verification as the tiebreak. Deleted pages are dropped.
- In a list call, a brand whose lookup failed is reported as failed, not as “no such brand”.
- Zero matches returns a hint to retry with the bare brand name, without a country, city or legal suffix.
get_meta_ads
Pulls a page’s ads.
| Parameter | Default | Accepted values and behaviour |
|---|---|---|
platform_ids |
required | Page ID, brand name, or a list of either |
limit |
30 | Per page ID. Values under 25 are raised to 25; the maximum is 1000 |
country |
all | Two-letter code such as US. Anything else is rejected |
status |
active |
active, inactive or all. Becomes all when a date is set |
active_only |
false | Only ads still running |
media_type |
all |
all, image or video. image includes carousels |
sort_by |
longest-running first | longest_running, newest, total_impressions, relevancy_monthly_grouped |
min_duration_days |
none | Only ads that have run at least this long |
language |
none | Two-letter code such as EN |
start_date, end_date |
none | YYYY-MM-DD, filters by impression dates |
include_reach |
false | Adds per-ad EU and UK reach where Meta discloses it |
trim |
true | false adds funding entity, disclaimer, languages and positions |
cursor |
none | Continuation token from the previous response |
Notes on the values:
sort_byaliases.impressionsis read astotal_impressions,longestandoldestaslongest_running,recentandlatestasnewest. Any other value returns an error that lists the four valid ones.longest_runningandnewestrank only the ads fetched. They are applied after the fetch, not by Meta. Raiselimitor setmin_duration_daysfor a wider net.media_typealiases.static,photo,meme,carousel,dcoanddpaare read asimage. Unknown values return an error instead of silently returning everything.- Dates imply history. With
start_dateorend_dateand no explicitstatus, the search covers all statuses.
What each ad contains
Every row carries ad_id, page_id, page_name, advertiser_name, advertiser_handle, media_type, headline, body, cta_text, link_url, placements, start_date, end_date, is_active and ad_snapshot_url.
media_typeisIMAGE,VIDEO,DCO(any carousel or dynamic creative) orTEXT.headlinecan be empty on video ads. Usebodyandmedia_type.is_activeis derived fromend_date, the last day the ad was shown.- Ads that share one creative are collapsed into one row.
ads_in_creativesays how many ads run that creative. reach,reach_by_age_gender,impressionsandspendappear only when Meta’s transparency data discloses them for that ad. A missing field means not disclosed, not zero.
The response also carries has_active_ads, count, estimated_total_count, a one-line profile of the fetched set (format mix, placements, longest-running ad, launches in the last 30 days) and, in list calls, a per-brand outcome.
What it never contains
- Spend, clicks, CPC or results for ordinary commercial ads. Meta does not publish them.
- Ads a brand paid a creator to run from the creator’s own page. Those sit under the creator’s page.
- Old commercial ads. Meta keeps them for about a year after they stop; political and issue ads are kept for seven years.
search_meta_ads_by_keyword
Searches every advertiser by topic.
| Parameter | Default | Accepted values and behaviour |
|---|---|---|
query |
required | Keyword, phrase, handle, domain or hashtag |
limit |
30 | One upstream page. Maximum 1000, capped at 10 pages |
sort_by |
relevancy_monthly_grouped |
Same four values as get_meta_ads |
search_type |
keyword_unordered |
Or keyword_exact_phrase for multi-word product names |
ad_type |
all |
Or political_and_issue_ads |
min_duration_days |
none | Scans up to 5 pages for ads that have run this long |
country, media_type, start_date, end_date, trim, cursor |
Same as get_meta_ads |
|
status |
ACTIVE |
ACTIVE, INACTIVE or ALL. Becomes ALL when a date is set |
- The default sort only returns recent ads.
relevancy_monthly_groupedstays on topic but covers roughly the last month. Combining it withmin_duration_daysreturns an error, because nothing would match. - With
min_duration_daysand nosort_by, the sort switches tototal_impressions, which covers ads of any age but matches more loosely. - Relevance is reported. The response includes
query_hit_count, the number of returned ads whose own copy mentions a query word. When five or more ads come back and under 30% mention it, the result is flaggedoff_topicand the assistant is told to say so. - Without
country, results span all countries.
Paging and cursors
- Upstream page size. The first page of a brand’s ads holds 30 ads; every later page holds 10.
- Windows. A large result is returned in windows of about 40,000 characters. The rest is stored for 24 hours and read with a cursor of the form
rs:<id>:<offset>. Reading it costs no credits. - Upstream cursors. Any other cursor value continues the scan at Meta. It works with a single page ID only and costs credits, so the assistant is told to ask before continuing.
- Expired cursor. After 24 hours an
rs:cursor returns an error asking to re-run the call without a cursor.
Credit cost
| Call | Credits |
|---|---|
get_meta_platform_id |
1 per brand |
get_meta_ads, default limit 30 |
1 per page ID, plus 1 per brand name that had to be resolved |
get_meta_ads, larger limit |
1 for the first 30 ads, then 1 per 10 more. limit 150 is 13 |
get_meta_ads with media_type image |
Up to 5, because image mode scans five unfiltered pages |
get_meta_ads with min_duration_days or active_only |
Up to 5, so sparse matches are not reported as zero |
get_meta_ads with a list |
Per brand, capped at 10 pages each |
search_meta_ads_by_keyword |
1 per page: 1 by default, up to 5 with min_duration_days |
Reading an rs: cursor |
0 |
analyze_ad_image, analyze_ad_video |
1 per ad |
Free is 20 credits a day with no card, Pro is $50 a month for 100 a day, and Max is $100 a month for 250 a day. There is no overage billing. See Credits and plans.
Failure modes
| Situation | What the tool returns |
|---|---|
| Page runs ads, but none match the filters | Zero ads with has_active_ads true and a note to loosen the filters |
| Page has no ads | Zero ads with may_be_inactive true and a note to try another candidate page |
| Empty date window | A note that the library may no longer hold that period |
| One brand in a list fails | That brand is marked “fetch failed, not confirmed inactive”; the others still return |
| Meta fails mid-scan | The ads fetched so far, plus a cursor to resume |
| Credits run out mid-scan | The ads fetched so far; unfetched brands are marked as not fetched |
| Several parallel single-brand calls | An error asking for one call with a list of IDs |
| Rate limit, timeout or outage | A short retry hint. Raw upstream errors are never passed through |
Mistyped ad_id in an analysis call |
“Meta’s Ad Library has no ad with ID …” |
Worked prompts
What Meta ads is [brand] running right now? Show the 30 longest-running.
get_meta_ads with the brand name. 2 credits: one to resolve the name, one page of ads.
[brand] is ambiguous. List the candidate Meta pages and pull ads from the one whose site is [domain].
get_meta_platform_id, then get_meta_ads with that page_id. 2 credits.
Compare the video ads of [brand A], [brand B] and [brand C] in the US.
One get_meta_ads call with a list of three names, media_type video, country US. 6 credits.
Search Meta for "collagen gummies" ads that have run at least 90 days and list the hooks that repeat.
search_meta_ads_by_keyword with min_duration_days 90. Sort switches to total_impressions. Up to 5 credits.
Transcribe [brand]'s longest-running video ad and break down the first three seconds.
get_meta_ads, then analyze_ad_video with that ad’s ad_id as ad_archive_id. 3 credits.