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.
bodyis cut to the first 120 characters in search results.brand_nameandestimated_audiencecan 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_pageis the most reliable sign of who the brand is.brand_nameis 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.