`meta_ads_track_competitor`

Track Competitor

Description

Register a Meta advertiser for daily ad-library tracking. Provide exactly one identifier: page_id (numeric Facebook Page ID — most precise; works even for a page never scraped), page_url (a facebook.com page URL; numeric IDs resolve directly, a vanity handle is matched by page handle or read as a name), or name (the advertiser's name as it appears on its Facebook page, e.g. "Jones Road Beauty"). Call this directly with the name — do not search the ad library first: a name or handle not yet in the corpus is looked up live in Meta's Ad Library (a keyword search, about 20–60 s) and tracked in this same call if exactly one advertiser has that exact name. Several matches return a candidate list (name, platform_advertiser_id — the page ID — and ad count) and track NOTHING — retry with page_id set to a candidate's platform_advertiser_id; no exact match returns an error (nothing tracked) asking for the page ID — that is not proof the advertiser has no ads, since the keyword search can miss one. A new track starts a full background scrape (full_scrape: "started"); the response reports seeded (ads landed by the lookup), full_scrape and any warning. The daily sweep keeps the advertiser's ads current for meta_ads_list_competitor_ads. Requires no Meta connection.

IdempotentOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "meta_ads_track_competitor",
    "arguments": {
      "page_id": "15087023444",
      "reason": "Start daily tracking of a key competitor"
    }
  }
}

hopkin meta track-competitor

Flag	Type	Required	Description
`--page-id`	`string`	Optional	Numeric Facebook Page ID of the advertiser (most precise identifier). A non-numeric value is treated as a handle/name search, like name.
`--page-url`	`string`	Optional	Facebook Page URL, e.g. https://www.facebook.com/nike, https://www.facebook.com/profile.php?id=15087023444, or an Ad Library URL with view_all_page_id. Numeric IDs resolve exactly; a vanity handle is matched by page handle, or looked up live as a name when no scraped advertiser has it.
`--name`	`string`	Optional	Advertiser name as it appears on its Facebook page, e.g. "Nike". Searched among scraped advertisers, then looked up live in the Ad Library when none matches exactly. Exactly one exact match is tracked; multiple matches return candidates and track nothing.

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

Parameters

Name	Type	Required	Description
`reason`	`string`	Required	Why this tool call is neededminLength: 1, maxLength: 500

Optional parameters (3)

Name	Type	Required	Description
`page_id`	`string`	Optional	Numeric Facebook Page ID of the advertiser (most precise identifier). A non-numeric value is treated as a handle/name search, like name.minLength: 1
`page_url`	`string`	Optional	Facebook Page URL, e.g. https://www.facebook.com/nike, https://www.facebook.com/profile.php?id=15087023444, or an Ad Library URL with view_all_page_id. Numeric IDs resolve exactly; a vanity handle is matched by page handle, or looked up live as a name when no scraped advertiser has it.
`name`	`string`	Optional	Advertiser name as it appears on its Facebook page, e.g. "Nike". Searched among scraped advertisers, then looked up live in the Ad Library when none matches exactly. Exactly one exact match is tracked; multiple matches return candidates and track nothing.minLength: 1

Examples

Track by page ID

{
  "page_id": "15087023444",
  "reason": "Start daily tracking of a key competitor"
}

hopkin meta track-competitor --page-id 15087023444

Track by page URL

{
  "page_url": "https://www.facebook.com/nike",
  "reason": "Track a competitor from their Facebook page link"
}

hopkin meta track-competitor --page-url https://www.facebook.com/nike

Track by name

{
  "name": "Nike",
  "reason": "Track a competitor known only by name"
}

hopkin meta track-competitor --name Nike