For AI agents: the full docs index is at /docs/llms.txt. Append .md to any docs URL for Markdown.
Skip to content
Proxy Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

TikTok Ads MCP: EU ad library tools and limits

How Proxy's TikTok Ads MCP reads TikTok's EU ad library: exact advertiser-name matching, name variants, paging, expiring media URLs and credit cost.

Proxy connects an assistant to TikTok’s public ad repository for the EU. It can pull a brand’s TikTok ads with creative, landing page and country targeting. It is read-only and never connects to TikTok Ads Manager.

This page documents exactly how the two TikTok tools behave. For the short parameter tables, see the TikTok 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 TikTok ads search_tiktok_ads with a list of name variants
Landing page and countries for an ad get_tiktok_ad_details with the ad id
A transcript analyze_ad_video with the ad id as tiktok_id
Ads about a topic Not supported on TikTok. Find advertisers with search_meta_ads_by_keyword or search_competitors, then search each name

search_tiktok_ads

Parameter Type Behaviour
advertiser_name string or list Registered advertiser name, or up to 4 variants. query and brand_name are accepted as aliases
cursor string Token from the previous response. Works with one name only

How name matching works

  • The registered name is often the legal or parent company, not the consumer brand.
  • Matching is exact and case-sensitive, so the tool takes a list of variants: legal name, consumer brand, alternate capitalisation.
  • Variants are tried in order. The search stops at the first one that returns ads, and the response names it in advertiser_name.
  • Only the first 4 variants are used. Duplicates are dropped.
  • There is no country filter at search level. Country targeting is in the ad details.

How much it fetches

For the matching name, one call fetches up to 5 pages of about 12 ads each. It stops earlier when:

  • TikTok reports no more results, or
  • every ad on a page was last shown more than 30 days ago. Pages are ordered by recency, so the rest is the inactive tail.

If more remain, the response carries has_more and a cursor. Pass that cursor back with the matched name to continue.

What each ad contains

Every row carries id, body, brand_name, first_shown_date, last_shown_date, estimated_audience and ad_url.

  • body is cut to the first 120 characters in search results.
  • brand_name and estimated_audience can be missing.
  • An ad last shown in the past few days is likely still running.
  • There is no reliable total count. Trust has_more.

get_tiktok_ad_details

Parameter Type Behaviour
ad_id string or list Ad ID from search, a list of IDs, or a library.tiktok.com ad URL

A single ID returns id, body, brand_name, video_url, cover, landing_page, country_code, first_shown_date, last_shown_date and duration. Where TikTok provides them, it also returns ctr, like and objective.

  • landing_page is the most reliable sign of who the brand is. brand_name is often missing.
  • A list returns an object keyed by ID. An ID that failed carries its own error; the others still return.
  • Duplicate IDs in a list are fetched once.

What it never contains

  • Ads that only ran outside the EU. A US-only advertiser returns nothing.
  • Spend or impressions. The EU library does not carry them at search level.
  • Topic, keyword, category or format search.
  • A guaranteed brand name on each ad.

Credit cost

Call Credits
search_tiktok_ads, matching name 1 per page fetched, up to 5
search_tiktok_ads, each variant that returned nothing 1
search_tiktok_ads with a cursor 1 per page fetched, up to 5
get_tiktok_ad_details 1 per ad ID
analyze_ad_video with tiktok_id 2: 1 for the fresh video fetch, 1 for the analysis

Put your best guess first in the list. A wrong first guess costs a credit before the right name is tried.

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
No name matched Zero ads, a reminder of the two limits, and a prompt to try the legal or parent name once more
Still nothing after that The assistant is told to stop retrying and continue with Meta and Google
Cursor sent with several names An error asking for only the matched name with the cursor
TikTok source is down “TikTok ads source is temporarily unavailable” with a retry hint
One ID in a list fails That ID carries an error; the rest return
Ad has no video analyze_ad_video reports that the ad has no video URL
Credits run out mid-list The first IDs are fetched; the rest are marked as not fetched

If a brand you know advertises returns nothing, open library.tiktok.com, find one of its ads and copy the advertiser name exactly as shown.

Worked prompts

Find [brand]'s TikTok ads. Try [legal name], [parent company] and [brand], with exact capitalisation.

search_tiktok_ads with three variants. 1 credit per miss, then up to 5 for the match.

Where do [advertiser]'s five newest TikTok ads send people, and which countries do they target?

get_tiktok_ad_details with a list of five IDs. 5 credits.

Transcribe [advertiser]'s newest TikTok ad and break down the first three seconds.

search_tiktok_ads, then analyze_ad_video with tiktok_id. 2 credits after the search.

Show me more of [advertiser]'s TikTok ads.

search_tiktok_ads with the matched name and the cursor. Up to 5 credits.

Which protein snack brands run TikTok ads in the EU?

search_meta_ads_by_keyword to collect advertiser names, then search_tiktok_ads per name. TikTok itself has no topic search.

Guides

Was this page helpful?