TikTok Ads: MCP tool reference
The Valkiria MCP server at https://valkiria.pro/mcp gives a connected assistant 26 tools for advertisers, campaigns, ad groups and ads in TikTok Ads. 14 of them only read. The assistant picks the tool itself; this page lists what exists, under the names it reports in its tool calls.
01
Tools that read (14)
These only return data. They are not counted against the monthly allowance.
- tiktok_list_advertisers: TikTok advertisers (ad accounts) connected to Valkiria by the caller, from the last sync: advertiser id, name, status, balance and currency. Use the advertiser id in the other tiktok_ tools. Stored data, not a live read. Read-only.
- tiktok_list_campaigns: Campaigns of one TikTok advertiser, live from TikTok: id, name, status (ENABLE / DISABLE and TikTok's secondary status), objective, budget and budget mode (daily, total or unlimited) in the advertiser currency. For metrics use tiktok_campaign_performance. Read-only.
- tiktok_campaign_performance: TikTok campaigns with their metrics for the period, from the same dated facts the Analytics screen shows: spend (advertiser currency), impressions, clicks, CTR, conversions and cost per conversion (providerCampaignId is the TikTok campaign id). recordedDays below requestedDays means some days are not synced yet. Provider facts carry no revenue: revenue and roas are null, not zero. Read-only.
- tiktok_list_ad_groups: Ad groups of one TikTok advertiser, optionally of one campaign, live: id, name, status, budget and budget mode, bid, optimization goal and the targeting Valkiria edits (locations, age groups, gender, languages). For the full targeting of one ad group use tiktok_ad_group_targeting. Read-only.
- tiktok_list_ads: Ads of one TikTok advertiser, optionally of one ad group or campaign, live: id, name, status, ad text, landing page, call to action and the video / image ids the ad uses. Read-only.
- tiktok_ad_performance: Per-ad performance from TikTok reporting for the period: spend, impressions, clicks, CTR, CPC, CPM, conversions, cost per conversion, reach and frequency, in the advertiser currency, sorted by spend. A null metric means TikTok did not report it, not zero. Provider facts carry no revenue: revenue and roas are null, not zero. Read-only.
- tiktok_geo_performance: Spend, impressions, clicks, CTR, conversions and cost per conversion by country (ISO code) for the period, from TikTok's audience report, in the advertiser currency. Use it before changing locations with tiktok_update_ad_group_targeting. A null metric means TikTok did not report it, not zero. Read-only.
- tiktok_audience_breakdown: Who the ads reached: spend, impressions, clicks, CTR, conversions and cost per conversion by age group, gender, device platform or language for the period, from TikTok's audience report, in the advertiser currency. A null metric means TikTok did not report it, not zero. Read-only.
- tiktok_creative_fatigue: Ads whose audience is tiring: across the last 2-4 full weeks, frequency rose by 15% or more to at least 2 while CTR fell by 15% or more, on at least 500 impressions per week. Each week is its own TikTok report, so reach and frequency are TikTok's figures for that week. Returns the weekly numbers behind each verdict; an empty list means no ad met the rule, not that every creative is fresh. Read-only.
- tiktok_wasted_spend: Where money went without a conversion in the period. level=ad (default): ads with spend and zero conversions from TikTok reporting, with each ad's share of spend. level=campaign: the same per campaign from the dated analytics facts. minSpend filters noise (advertiser currency, default 0). Zero only means TikTok attributed no conversion: check the pixel and events before pausing. A null metric means TikTok did not report it, not zero. Read-only.
- tiktok_ad_group_targeting: Full delivery settings of one TikTok ad group, live: targeting (location ids, age groups, gender, languages, interest category ids, included and excluded audience ids, operating systems), placements, schedule, budget and mode, bid and optimization goal. Use it as the base for tiktok_update_ad_group_targeting; resolve ids with tiktok_targeting_options. Read-only.
- tiktok_list_audiences: Custom and lookalike audiences of one TikTok advertiser, live, as TikTok lists them (id, name, type, size and validity where TikTok reports them). Use the ids as audience_ids / excluded_audience_ids in tiktok_update_ad_group_targeting. Read-only.
- tiktok_list_identities: Identities (the profile an ad is published as) of one TikTok advertiser, live: identity id, type and display name. A new ad needs one (tiktok_add_ad). Read-only.
- tiktok_targeting_options: TikTok's own targeting catalogue: locations (countries and provinces with their location ids), interest categories or languages, filtered by a name fragment. Returns the ids to use in tiktok_update_ad_group_targeting and tiktok_add_ad_group. Read-only.
02
Tools that change or generate (12)
A change requested through these tools follows the safety rules below: it is a proposal unless the write policy you set for the account allows it.
- tiktok_pause_campaign: Propose pausing a TikTok campaign. Pausing stops its spend and can be undone. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_resume_campaign: Propose resuming a paused TikTok campaign. Resuming starts spend again, so it always waits for the owner. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_pause_ad_group: Propose pausing a TikTok ad group. Pausing stops its spend and can be undone. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_resume_ad_group: Propose resuming a paused TikTok ad group. Resuming starts spend again, so it always waits for the owner. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_pause_ad: Propose pausing a TikTok ad. Pausing stops its spend and can be undone. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_resume_ad: Propose resuming a paused TikTok ad. Resuming starts spend again, so it always waits for the owner. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_update_campaign_budget: Propose a new budget for a TikTok campaign that holds a daily or total budget; it stays in the mode it has (a daily budget stays daily). The amount is in the advertiser currency in normal units and is sent to TikTok as it is, never in minor units; currencies without decimals (JPY, KRW, VND…) take whole amounts. Campaigns with an unlimited budget are budgeted on their ad groups. Undo restores the previous amount. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_update_ad_group_budget: Propose a new daily budget for a TikTok ad group. The amount is in the advertiser currency in normal units and is sent to TikTok as it is, never in minor units; currencies without decimals (JPY, KRW, VND…) take whole amounts. Ad groups with a total or unlimited budget cannot be changed here. Undo restores the previous amount. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_update_ad_group_schedule: Propose a new start and/or end time for a TikTok ad group. endTime=null removes the end date, so it runs until paused (not allowed with a total budget). TikTok refuses a new start time once an ad group has started; its answer is reported as is. Undo restores the previous schedule. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_update_ad_group_targeting: Propose a targeting change for a TikTok ad group as a patch: each key you pass replaces that key, null empties it (gender: no limit), every key you do not pass is kept. The patch is merged onto the targeting the ad group has at approval time, so nothing else is wiped, and the whole targeting is read back before the change is reported as applied. At least one location must remain. Read the current targeting with tiktok_ad_group_targeting; find ids with tiktok_targeting_options and tiktok_list_audiences. Undo restores the previous targeting. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_add_ad_group: Propose a new ad group in an existing TikTok campaign. It is always created disabled (operation_status DISABLE): a person enables it. locationIds is required. Without a budget the ad group is unlimited and the campaign budget applies; with one, the default mode is daily. The amount is in the advertiser currency in normal units and is sent to TikTok as it is, never in minor units; currencies without decimals (JPY, KRW, VND…) take whole amounts. Without optimizationGoal the goal is clicks; without bid TikTok bids automatically. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
- tiktok_add_ad: Propose a new ad in an existing TikTok ad group from media that is already in TikTok: videoId (optionally with one cover image id), imageIds for an image ad, or tiktokItemId for a Spark ad from an authorized post. It is always created disabled: a person enables it. identityId comes from tiktok_list_identities. The landing page must be https. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
03
How changes stay safe
- Two scopes, chosen by you at sign-in: read, and propose. With read alone the assistant cannot request any change.
- A change requested from an assistant is a proposal. It waits in Approvals in Valkiria until the account owner approves it, unless the write policy you set for that account allows that kind of change by itself.
- New campaigns are created paused. Starting new spend and deleting always wait for a person.
- The assistant can list what is waiting for approval and reject a proposal. It cannot approve one: approval stays with the owner in Valkiria.
- The change history shows who or what made each change and the value before and after, with Undo where the change can be reversed.
- You can disconnect an assistant at any time on the Connect AI page; a developer API key can be deleted the same way.
04
Limits
- The assistant sees only your own Valkiria workspace, and only the ad accounts connected there.
- Numbers are as fresh as the last sync or import; the assistant can tell you when that was.
- Money stays in each account's own currency. Different currencies are not converted or added up.
- Reading data is not counted against the monthly allowance; changes and AI generations are. Allowances per plan are on the pricing page.
05
FAQ
Connect an assistant and call the first tool
Create a free account, connect an ad account and add the connector. The first pass only reads.