Meta Ad Library Spend MCP by AdSpendSpy

Search AdSpendSpy's Meta Ad Library database for an advertiser or brand by name. Returns up to five matching brands with category, logo, number of active ads where known, and the page_id. No sign-in needed.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100,
      "description": "Brand or advertiser name, e.g. \"Gymshark\"."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

Show one brand's active Meta ads (Facebook and Instagram). For brands AdSpendSpy tracks: active ad count, an estimated 30-day spend range split into EU/UK and US where available, and up to six top ads with image or video, headline, text, days running, platforms and landing domain. A brand name is matched exactly; if only similar names exist, it returns them as candidates and no ads. With live_lookup true, an untracked brand is looked up live in the Meta Ad Library (up to ten newest ads, no spend). No sign-in needed. Pass page_id when known, otherwise brand.

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 25,
      "pattern": "^[0-9]+$",
      "description": "Numeric Meta page ID of the advertiser, as returned in earlier results. Preferred when known."
    },
    "brand": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100,
      "description": "Exact brand or advertiser name as the user wrote it, e.g. \"Gymshark\". Used only when no page_id is given; never matched to a differently named brand."
    },
    "country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 3,
      "default": "ALL",
      "description": "Two-letter ISO country code such as \"DE\", \"US\" or \"GB\" when the user names a country; \"ALL\" for worldwide."
    },
    "live_lookup": {
      "type": "boolean",
      "default": false,
      "description": "True only after a previous call returned candidates and none is the brand the user means. Live lookups are limited per conversation and per day."
    }
  },
  "required": [],
  "additionalProperties": false
}

List up to six tracked advertisers similar to a brand (same Facebook page category or niche), each with category, active ads where known, estimated 30-day spend range and one top ad. No sign-in needed. Pass page_id when known, otherwise the exact brand name.

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 25,
      "pattern": "^[0-9]+$",
      "description": "Numeric Meta page ID of the advertiser, as returned in earlier results. Preferred when known."
    },
    "brand": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100,
      "description": "Exact brand or advertiser name as the user wrote it, e.g. \"Gymshark\". Used only when no page_id is given; never matched to a differently named brand."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 6,
      "default": 6
    }
  },
  "required": [],
  "additionalProperties": false
}

Compare 2 to 6 tracked advertisers side by side: category, active ads where known, estimated 30-day spend range and one top ad each. A name AdSpendSpy does not track is listed as not tracked and never replaced by a similar brand. No sign-in needed.

{
  "type": "object",
  "properties": {
    "page_ids": {
      "type": "array",
      "minItems": 1,
      "maxItems": 6,
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 25,
        "pattern": "^[0-9]+$"
      }
    },
    "brands": {
      "type": "array",
      "minItems": 1,
      "maxItems": 6,
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 100
      }
    }
  },
  "required": [],
  "additionalProperties": false
}

List your actively tracked advertisers and their string page_id values.

{
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "all, my_brands, unassigned, or an owned project public_id. Every choice stays within your tracked brands."
    }
  },
  "required": [],
  "additionalProperties": false
}

Search your tracked advertisers by name, Meta page ID, or stored Facebook URL. Searches existing local data only; does not resolve vanity URLs through paid providers.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1
    }
  },
  "required": [
    "q"
  ],
  "additionalProperties": false
}

Check whether each string Meta page ID is actively tracked by your account.

{
  "type": "object",
  "properties": {
    "page_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9]{5,25}$",
        "description": "Meta advertiser page ID, kept as a string."
      },
      "minItems": 1,
      "maxItems": 100
    }
  },
  "required": [
    "page_ids"
  ],
  "additionalProperties": false
}

Add a known advertiser to your tracked brands before reading its ads. Changes your AdSpendSpy account: the advertiser joins your tracked brands and AdSpendSpy starts importing its ads. Requires a Meta page_id and brand_name and consumes one of your existing account tracking slots, not an extra subscription. Repeating an active tracking is idempotent, even at the limit. New imports run in the background, so ads may not be ready yet. Returns tracked_count, tracked_limit, remaining_slots and ingestion_state. There is no MCP removal tool: remove brands on the AdSpendSpy website. Does not search Meta or resolve advertiser names or URLs.

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "string",
      "pattern": "^[0-9]{5,25}$",
      "description": "Meta advertiser page ID, kept as a string."
    },
    "brand_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Advertiser display name, not a URL or an instruction."
    }
  },
  "required": [
    "page_id",
    "brand_name"
  ],
  "additionalProperties": false
}

List creative summaries for one tracked advertiser, newest internal ID first, or with sort spend highest latest cumulative estimated spend first (use it for an advertiser's top ads). pagination.next_cursor returns the next page. Each ad carries internal_ad_id (AdSpendSpy ID) and meta_ad_id (the ad on Meta).

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "string",
      "pattern": "^[0-9]{5,25}$",
      "description": "Meta advertiser page ID, kept as a string."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "Opaque pagination.next_cursor returned by the previous page with the same filters."
    },
    "media_type": {
      "type": "string",
      "enum": [
        "all",
        "image",
        "video"
      ],
      "default": "all"
    },
    "active_only": {
      "type": "boolean",
      "default": false
    },
    "sort": {
      "type": "string",
      "enum": [
        "newest",
        "spend"
      ],
      "default": "newest",
      "description": "newest = newest internal ID first; spend = highest estimated spend first."
    }
  },
  "required": [
    "page_id"
  ],
  "additionalProperties": false
}

Retrieve one ad of an advertiser you actively track by its internal AdSpendSpy ad ID (internal_ad_id), not its Meta ad ID. Saved lists and favorites do not retain MCP ad access after you remove a tracked brand on the website.

{
  "type": "object",
  "properties": {
    "ad_id": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991,
      "description": "Internal AdSpendSpy ad ID (internal_ad_id in ad listings); never a Meta ad ID."
    }
  },
  "required": [
    "ad_id"
  ],
  "additionalProperties": false
}

Analyze latest cumulative estimated spend in EUR for your tracked advertisers. page_id is an exact advertiser filter. timeframe filters when ads were last seen, NOT spend accrued during that period. Creative breakdowns sample the top 1,000 ads; response metadata states matched and sampled counts and full-match aggregate spend. Zero can mean unavailable estimates.

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "string",
      "pattern": "^[0-9]{5,25}$",
      "description": "Meta advertiser page ID, kept as a string."
    },
    "q": {
      "type": "string",
      "maxLength": 500
    },
    "media_type": {
      "type": "string",
      "enum": [
        "all",
        "image",
        "video"
      ],
      "default": "all"
    },
    "category": {
      "type": "string",
      "maxLength": 100
    },
    "project": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "all, my_brands, unassigned, or an owned project public_id. Every choice stays within your tracked brands."
    },
    "timeframe": {
      "type": "string",
      "enum": [
        "all",
        "7d",
        "30d",
        "90d"
      ],
      "default": "30d",
      "description": "Last-seen window; never a period-spend calculation."
    },
    "active_only": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "0",
            "1",
            "true",
            "false"
          ]
        }
      ],
      "default": false
    }
  },
  "required": [],
  "additionalProperties": false
}

Rank the landing pages of your tracked advertisers by latest cumulative estimated spend in EUR. Ads are grouped by landing URL with ad, advertiser and active-ad counts, the top-spending advertiser and, when one is stored, a screenshot as screenshot_url (site path) and screenshot_full_url (absolute URL). page_id is an exact advertiser filter; q matches part of the landing URL. timeframe filters when ads were last seen, NOT spend accrued during that period. Zero can mean unavailable estimates.

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "string",
      "pattern": "^[0-9]{5,25}$",
      "description": "Meta advertiser page ID, kept as a string."
    },
    "q": {
      "type": "string",
      "maxLength": 500,
      "description": "Substring of the landing URL."
    },
    "project": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "all, my_brands, unassigned, or an owned project public_id. Every choice stays within your tracked brands."
    },
    "timeframe": {
      "type": "string",
      "enum": [
        "all",
        "7d",
        "30d",
        "90d"
      ],
      "default": "30d",
      "description": "Last-seen window; never a period-spend calculation."
    },
    "active_only": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "0",
            "1",
            "true",
            "false"
          ]
        }
      ],
      "default": false
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 60
    }
  },
  "required": [],
  "additionalProperties": false
}

Read your saved lists, with ad creatives limited to advertisers you actively track. list_id selects one owned list; ad_id reports which of your lists contain that internal ad ID and takes precedence when both are supplied. Saving an ad does not bypass tracking limits.

{
  "type": "object",
  "properties": {
    "list_id": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "ad_id": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [],
  "additionalProperties": false
}

Read your projects. public_id selects one owned project; brand_id selects memberships for an actively tracked internal brand record and takes precedence when both are supplied.

{
  "type": "object",
  "properties": {
    "brand_id": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "public_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    }
  },
  "required": [],
  "additionalProperties": false
}

Read the number of pending alerts for your account.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

List ads that newly appeared for advertisers you actively track, newest first (event ad.new). An ad counts as new when it started at most 7 days before it was first seen, so the back catalog of a freshly tracked advertiser is excluded. Without since_id or cursor the last 30 days are returned. since_id returns only items with a higher internal_ad_id. Spend is a latest cumulative estimate in EUR; null means unknown. Use page_id or project, not both.

{
  "type": "object",
  "properties": {
    "since_id": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991,
      "description": "Return only items with a higher id (internal_ad_id for new ads, alert_id for alerts)."
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "Opaque pagination.next_cursor returned by the previous page with the same filters."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "page_id": {
      "type": "string",
      "pattern": "^[0-9]{5,25}$",
      "description": "Meta advertiser page ID, kept as a string."
    },
    "project": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Public_id of one of your projects. Cannot be combined with page_id."
    }
  },
  "required": [],
  "additionalProperties": false
}

List spend alerts for ads of advertisers you actively track, newest first (event ad.spend_alert). Each item carries the alert threshold and the estimated spend when the alert was created. Without since_id or cursor the last 30 days are returned. since_id returns only items with a higher alert_id. Spend is a latest cumulative estimate in EUR; null means unknown. Reading alerts does not mark them as sent. Use page_id or project, not both.

{
  "type": "object",
  "properties": {
    "since_id": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991,
      "description": "Return only items with a higher id (internal_ad_id for new ads, alert_id for alerts)."
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "Opaque pagination.next_cursor returned by the previous page with the same filters."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "page_id": {
      "type": "string",
      "pattern": "^[0-9]{5,25}$",
      "description": "Meta advertiser page ID, kept as a string."
    },
    "project": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Public_id of one of your projects. Cannot be combined with page_id."
    }
  },
  "required": [],
  "additionalProperties": false
}