`meta_ads_search_ad_library`

Search Meta Ad Library

Description

Search the Meta Ad Library for ads from any advertiser. Returns public transparency data including ad creative text, snapshot URLs, delivery dates, and platforms. For political/issue ads, also returns spend ranges, impressions, and demographics. Does NOT require an ad account — searches globally. Rate limit: 200 calls/hour. Each result includes an ad_snapshot_url that links to the ad's visual preview on Facebook.

Read-onlyIdempotentOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "meta_ads_search_ad_library",
    "arguments": {
      "search_terms": "running shoes",
      "ad_reached_countries": [
        "US"
      ],
      "reason": "Competitive research on running shoe ads"
    }
  }
}

hopkin meta search-ad-library

Flag	Type	Required	Description
`--search-terms`	`string`	Optional	Keywords to search for in ad content. Spaces act as AND. Use the language the ad is written in.
`--search-type`	`string`	Optional	Search mode: KEYWORD_UNORDERED (default, any order) or KEYWORD_EXACT_PHRASE
`--search-page-ids`	`array`	Optional	Filter by up to 10 Facebook Page IDs. Use this for competitor/brand lookups.
`--ad-reached-countries`	`array`	Required	REQUIRED. ISO country codes (e.g. ["US", "GB"]) or ["ALL"]. Warning: ["ALL"] may return very large result sets — use with small limit values.
`--ad-type`	`string`	Optional	Filter by ad category. Default: ALL
`--ad-active-status`	`string`	Optional	Filter by delivery status. Default: ACTIVE
`--ad-delivery-date-min`	`string`	Optional	Minimum delivery date (YYYY-MM-DD)
`--ad-delivery-date-max`	`string`	Optional	Maximum delivery date (YYYY-MM-DD)
`--media-type`	`string`	Optional	Filter by media type
`--publisher-platforms`	`array`	Optional	Filter by platform(s)
`--languages`	`array`	Optional	Filter by language (ISO 639-1 codes)
`--limit`	`integer`	Optional	Results per page (default: 25, max: 50). Note: 200 calls/hour rate limit — use larger pages to conserve quota.
`--cursor`	`string`	Optional	Pagination cursor from previous response

{
  "mcpServers": {
    "meta-ads": {
      "url": "https://meta.mcp.hopkin.ai",
      "transport": "sse"
    }
  }
}

Parameters

Name	Type	Required	Description
`ad_reached_countries`	`array`	Required	REQUIRED. ISO country codes (e.g. ["US", "GB"]) or ["ALL"]. Warning: ["ALL"] may return very large result sets — use with small limit values.
`reason`	`string`	Required	Why this tool call is neededminLength: 1, maxLength: 500

Optional parameters (12)

Name	Type	Required	Description
`search_terms`	`string`	Optional	Keywords to search for in ad content. Spaces act as AND. Use the language the ad is written in.maxLength: 100
`search_type`	`string`	Optional	Search mode: KEYWORD_UNORDERED (default, any order) or KEYWORD_EXACT_PHRASE `KEYWORD_UNORDERED` `KEYWORD_EXACT_PHRASE`
`search_page_ids`	`array`	Optional	Filter by up to 10 Facebook Page IDs. Use this for competitor/brand lookups.
`ad_type`	`string`	Optional	Filter by ad category. Default: ALL `ALL` `EMPLOYMENT_ADS` `FINANCIAL_PRODUCTS_AND_SERVICES_ADS` `HOUSING_ADS` `POLITICAL_AND_ISSUE_ADS`
`ad_active_status`	`string`	Optional	Filter by delivery status. Default: ACTIVE `ACTIVE` `INACTIVE` `ALL`
`ad_delivery_date_min`	`string`	Optional	Minimum delivery date (YYYY-MM-DD)
`ad_delivery_date_max`	`string`	Optional	Maximum delivery date (YYYY-MM-DD)
`media_type`	`string`	Optional	Filter by media type `ALL` `IMAGE` `MEME` `VIDEO` `NONE`
`publisher_platforms`	`array`	Optional	Filter by platform(s)
`languages`	`array`	Optional	Filter by language (ISO 639-1 codes)
`limit`	`integer`	Optional	Results per page (default: 25, max: 50). Note: 200 calls/hour rate limit — use larger pages to conserve quota.min: 1, max: 50
`cursor`	`string`	Optional	Pagination cursor from previous responseminLength: 1

Examples

Search by keyword

{
  "search_terms": "running shoes",
  "ad_reached_countries": [
    "US"
  ],
  "reason": "Competitive research on running shoe ads"
}

hopkin meta search-ad-library --search-terms running shoes --ad-reached-countries US

Search by page ID

{
  "search_page_ids": [
    "123456789"
  ],
  "ad_reached_countries": [
    "US"
  ],
  "reason": "View competitor ads"
}

hopkin meta search-ad-library --search-page-ids 123456789 --ad-reached-countries US

Political ads

{
  "ad_type": "POLITICAL_AND_ISSUE_ADS",
  "ad_reached_countries": [
    "US"
  ],
  "search_terms": "climate",
  "reason": "Political ad transparency research"
}

hopkin meta search-ad-library --ad-type POLITICAL_AND_ISSUE_ADS --ad-reached-countries US --search-terms climate

Video ads on Instagram

{
  "search_terms": "fitness",
  "ad_reached_countries": [
    "US"
  ],
  "media_type": "VIDEO",
  "publisher_platforms": [
    "INSTAGRAM"
  ],
  "reason": "Creative research"
}

hopkin meta search-ad-library --search-terms fitness --ad-reached-countries US --media-type VIDEO --publisher-platforms INSTAGRAM