What can you do with this server?

Read-only MCP server for the TikTok Business API that lets an assistant query GMV Max, regular ads, reporting, Business Center finances, and discovery data, with shop-timezone alignment and USD conversion where applicable. * List GMV Max campaigns, campaign details, linked stores, available videos, and performance reports (raw, shop-timezone aligned, and range aggregates). * Query authorized ad accounts, campaigns, ad groups, ads, TikTok identities, and video asset details. * Pull integrated reports with custom dimensions/metrics, manual-bid ads reports (aligned and range), and creative-level video insights. * Inspect Business Center balances, advertiser balances, account spend, transactions, and budget change history. * Fetch trending TikTok hashtags by country with optional daily history. * Supports paging/filtering and handles TikTok timeouts, rate limits, and non-USD conversion.

Which integrations are available for this server?

Provides tools to access TikTok advertising data, including campaigns, ad groups, ads, and performance reports via the TikTok Business API.

How do I use TikTok Ads MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TikTok Ads MCP Show me my active campaigns" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

TikTok Ads MCP

by Buer2333

Overview Schema Source Related Servers Discussions Admin

Python

Remote

TikTok GMV Max MCP

A read-only Model Context Protocol server for the TikTok Business (Marketing) API, with first-class GMV Max support. Ask your assistant how your GMV Max campaigns, regular ads, and Business Center budgets are doing, and get answers in your shop's timezone and in USD.

It runs daily in production behind a multi-shop TikTok Shop reporting stack, so most of the code beyond plain API wrappers handles things the raw API gets wrong. Report days are realigned from the ad account's timezone to the shop's. Non-USD accounts are converted at that day's rate. TikTok's transient 51010 timeouts are retried.

The Python import package tiktok_ads_mcp has the same name as the one in the tiktok-ads-mcp PyPI distribution, so don't install both into the same environment.

Tools (24, all read-only)

GMV Max

Tool	What it returns
`get_gmvmax_campaigns_tool`	GMV Max campaigns with status and ROI-protection info
`get_gmvmax_campaign_info_tool`	Budget, bid, products and schedule for one campaign
`get_gmvmax_reports_tool`	GMV Max performance reports (`/gmv_max/report/get/`)
`get_gmvmax_report_aligned_tool`	One shop-timezone day, rebuilt from hourly data: cost, gross revenue, orders, ROI
`get_gmvmax_range_report_tool`	Aggregate cost / GMV / orders / ROI for a date range
`get_gmvmax_videos_tool`	Videos available to GMV Max for a store
`get_gmvmax_store_list_tool`	Stores linked to a GMV Max advertiser

Accounts, campaigns and ads

Tool	What it returns
`get_business_centers_tool`	Business Centers visible to the token
`get_authorized_ad_accounts_tool`	All authorized advertiser accounts
`get_campaigns_tool` / `get_ad_groups_tool` / `get_ads_tool`	Campaign, ad group and ad lists with filtering
`get_identities_tool`	TikTok identities (creator accounts) authorized to an advertiser
`get_video_info_tool`	Video asset URL, poster and duration by video ID

Reporting

Tool	What it returns
`get_reports_tool`	Integrated reports with custom dimensions and metrics
`get_ads_report_aligned_tool`	Manual-bid ads, one shop-timezone day: cost, GMV, orders, ROAS
`get_ads_range_report_tool`	Manual-bid ads aggregate for a date range
`get_creative_report_tool`	Creative-level video insights (engagement, play metrics)

Business Center finance

Tool	What it returns
`get_advertiser_balance_tool`	Balance and basic info per advertiser (≤100 IDs per call)
`get_bc_balance_tool`	Business Center available funds
`get_bc_account_cost_tool`	Spend per ad account under a BC for a date range
`get_bc_transactions_tool`	Top-ups and deductions at BC or advertiser level
`get_bc_budget_changelog_tool`	Who changed an advertiser's budget, and when

Discovery

Tool	What it returns
`get_trending_list_tool`	Trending hashtags by country (7 or 30 days), optional daily history

Related MCP server: flin-google-ads-mcp

Install

Requires Python 3.10+.

uvx tiktok-gmvmax-mcp          # run without installing
# or
pip install tiktok-gmvmax-mcp  # provides the `tiktok-gmvmax-mcp` command

Configure

Create an app in the TikTok for Business developer portal, grant it read permissions for the endpoints you need (ad accounts, campaigns and ads, reporting, GMV Max, Business Center), and generate a long-lived access token.

Variable	Required	Meaning
`TIKTOK_APP_ID`	yes	App ID
`TIKTOK_SECRET`	yes	App secret
`TIKTOK_ACCESS_TOKEN`	yes	Access token
`TIKTOK_ACCESS_TOKEN_2`	no	Second token (e.g. another Business Center), tried on permission errors
`TIKTOK_ADVERTISER_ID`	no	Default advertiser
`TIKTOK_SANDBOX`	no	`true` to use the sandbox API
`TIKTOK_REQUEST_TIMEOUT`	no	Seconds, default 30
`TIKTOK_ADS_PROXY`	no	Proxy URL used only for Business API calls
`LARK_BOT_CACHE_DIR`	no	Where FX rates are cached (default `~/.cache/lark-bot`)

Versions before 0.2 read the token from TIKTOK_ACCESS_TOKEN_XINCHENG / TIKTOK_ACCESS_TOKEN_ZECHENG. Those names still work.

Claude Desktop / Claude Code (mcpServers):

{
  "mcpServers": {
    "tiktok-gmvmax": {
      "command": "uvx",
      "args": ["tiktok-gmvmax-mcp"],
      "env": {
        "TIKTOK_APP_ID": "your_app_id",
        "TIKTOK_SECRET": "your_secret",
        "TIKTOK_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Behavior worth knowing

Timezones. TikTok reports days in the ad account's timezone. The *_aligned_tools fetch hourly rows and re-aggregate them into a day in the shop's timezone, so ad spend lines up with shop orders.
Currency. Cost and revenue from non-USD accounts are converted to USD at that day's ECB midpoint rate (Frankfurter). If the rate API is down, a small built-in table of approximate rates is used for that call only and never cached; any other currency is then returned unconverted (rate 1.0) with a logged error.
Retries. Code 51010 (TikTok backend timeout) is retried with backoff at the client layer. Rate-limit and 5xx errors are retried too.
mcp 1.x and 2.x. Both work: the server imports MCPServer (2.x) and falls back to FastMCP (1.x).

Development

git clone https://github.com/Buer2333/tiktok-gmvmax-mcp && cd tiktok-gmvmax-mcp
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest tests -q

Issues and PRs are welcome. Please include a test with any behavior change.

Changelog

0.2.1

Repository renamed to tiktok-gmvmax-mcp; package links updated.

0.2.0

Published as tiktok-gmvmax-mcp.
Generic TIKTOK_ACCESS_TOKEN / TIKTOK_ACCESS_TOKEN_2. The legacy names still work.
CLI logs go to stderr, so stdout stays clean for the stdio protocol.
FX: a fallback rate used during an API outage is no longer cached permanently.
18 tools added since 0.1.x: GMV Max, aligned and range reports, creatives, Business Center finance, identities, trending. Also added: account discovery, 51010 retry, USD conversion, mcp 2.x compatibility.

0.1.x

Six core tools, async httpx client, FastMCP server.

License

MIT. See LICENSE.

Credits

The six core campaign/report tools are based on ysntony/tiktok-ads-mcp (MIT).

Available Tools

24 tools

get_ad_groups_toolC

Get ad groups for a specific advertiser with optional filtering

Inputs: advertiser_id (required), page, filters, page_size, +1 more. Returns: result

get_ads_range_report_toolB

Get Ads (manual bid) aggregate report for a date range (no timezone alignment). Returns cost, gmv, orders, roas.

Inputs: end_date (required), start_date (required), advertiser_id (required). Returns: result

get_ads_report_aligned_toolA

Get Ads (manual bid) report aligned to shop timezone. Fetches hourly data and re-aggregates to match a shop-tz day. Returns cost, gmv, orders, and roas.

Inputs: date (required), advertiser_id (required), metrics, shop_tz. Returns: result

get_ads_toolC

Get ads for a specific advertiser with optional filtering

Inputs: advertiser_id (required), page, filters, page_size, +1 more. Returns: result

get_advertiser_balance_toolB

Get balance and basic info for individual advertiser accounts. Max 100 IDs per request.

Inputs: advertiser_ids (required). Returns: result

get_authorized_ad_accounts_toolB

Get all authorized ad accounts accessible by the current access token

Inputs: random_string. Returns: result

get_bc_account_cost_toolB

Get cost summary for all ad accounts under a BC within a date range. Useful for weekly/monthly spend review.

Inputs: bc_id (required), end_date (required), start_date (required), page, +1 more. Returns: result

get_bc_balance_toolC

Get Business Center balance (available funds).

Inputs: bc_id (required). Returns: result

get_bc_budget_changelog_toolB

Get budget change history for a specific advertiser under BC. Track who changed budget and when.

Inputs: bc_id (required), end_date (required), start_date (required), advertiser_id (required), +2 more. Returns: result

get_bc_transactions_toolC

Get BC transaction records (top-ups, deductions). transaction_level: BC or ADVERTISER. Times format: YYYY-MM-DD HH:MM:SS.

Inputs: bc_id (required), end_time (required), start_time (required), page, +2 more. Returns: result

get_business_centers_toolC

Get business centers accessible by the current access token

Inputs: page, bc_id, page_size. Returns: result

get_campaigns_toolC

Get campaigns for a specific advertiser with optional filtering

Inputs: advertiser_id (required), filters. Returns: result

get_creative_report_toolC

Get creative-level performance report (video insights, engagement, play metrics). report_type: VIDEO_INSIGHT (default).

Inputs: end_date (required), start_date (required), advertiser_id (required), page, +3 more. Returns: result

get_gmvmax_campaign_info_toolA

Get detailed info for a specific GMV Max campaign via /campaign/gmv_max/info/. Returns budget, bid, product, and scheduling details.

Inputs: campaign_id (required), advertiser_id (required). Returns: result

get_gmvmax_campaigns_toolA

Get GMV Max campaigns via /gmv_max/campaign/get/. Returns campaign list with status and ROI protection info. Default filter: PRODUCT_GMV_MAX.

Inputs: advertiser_id (required), page, filtering, page_size, +1 more. Returns: result

get_gmvmax_range_report_toolA

Get GMVMAX aggregate report for a date range (no timezone alignment). Returns cost, gmv, orders, roi.

Inputs: end_date (required), store_ids (required), start_date (required), advertiser_id (required). Returns: result

get_gmvmax_report_aligned_toolA

Get GMVMAX report aligned to shop timezone. Fetches hourly data and re-aggregates to match a shop-tz day, regardless of the ad account's native timezone. Returns aggregated metrics (cost, gross_revenue, orders), ROI, and hours included.

Inputs: date (required), store_ids (required), advertiser_id (required), metrics, +1 more. Returns: result

get_gmvmax_reports_toolB

Get GMV Max performance reports via /gmv_max/report/get/. store_ids is REQUIRED (get from campaign info endpoint). Metrics: cost, orders, cost_per_order, gross_revenue, roi, net_cost, creative_delivery_status, product_impressions, product_clicks, product_click_rate, ad_click_rate, ad_conversion_rate, ad_video_view_rate_2s/6s/p25/p50/p75/p100. Dimensions: advertiser_id, stat_time_day, item_id (item_id requires filtering with campaign_ids AND item_group_ids). Filtering: {"campaign_ids": ["..."], "item_group_ids": ["..."]}.

Inputs: end_date (required), store_ids (required), start_date (required), advertiser_id (required), +5 more. Returns: result

get_gmvmax_store_list_toolA

Get stores linked to a GMVMAX advertiser account. Useful to verify store-advertiser bindings.

Inputs: advertiser_id (required). Returns: result

get_gmvmax_videos_toolC

Get videos available for GMVMAX campaigns for a given store. Returns video list with IDs for cross-referencing with creative reports.

Inputs: store_id (required), advertiser_id (required), page, page_size, +3 more. Returns: result

get_identities_toolA

Get TikTok identities (creator accounts) authorized to an advertiser. identity_type: CUSTOMIZED_USER, AUTH_CODE, TT_USER, BC_AUTH_TT. For BC_AUTH_TT, identity_authorized_bc_id is required.

Inputs: advertiser_id (required), page, page_size, identity_type, +1 more. Returns: result

get_reports_toolC

Get performance reports and analytics with comprehensive filtering and grouping options

Inputs: page, bc_id, filters, metrics, +14 more. Returns: result

get_trending_list_toolA

Get trending hashtags on TikTok via /discovery/trending_list/. discovery_type: HASHTAG. date_range: 7DAY | 30DAY. country_code: e.g. US. Set include_history=True to get per-day rank/views breakdown.

Inputs: advertiser_id (required), page_size, date_range, category_id, +3 more. Returns: result

get_video_info_toolA

Get video asset details (URL, thumbnail, duration) by video IDs. Use with get_ads_tool to map ad → video_id → video URL/poster.

Inputs: video_ids (required), advertiser_id (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored 2026-07-09 01:25 across 24 tools

Disambiguation4/5

Most tools have distinct purposes (ad management, reporting, BC operations, etc.), but there are multiple reporting tools (range, aligned, GMV Max variants) that could cause confusion if descriptions are not carefully read.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with a '_tool' suffix (e.g., get_ads_tool, get_bc_balance_tool), making them predictable and easy to navigate.

Tool Count4/5

24 tools is on the higher side but appropriate for covering TikTok Ads' extensive API (ad accounts, campaigns, ads, reports, BC, creative, trending). It's slightly above the ideal 3-15 but not excessive.

Completeness2/5

The server is heavily read-oriented, lacking create/update/delete operations for core entities like campaigns and ad groups. It also misses budget management and ad creation, leaving significant gaps for full lifecycle automation.

Maintenance

ActivityMaintained

ResponsivenessOutdated data

Resources

Related MCP Connectors

TikTok Ads MCP Server by AdKit
io.github.adkit
TikTok Ads MCP server: run TikTok campaigns, ad groups, ads and reports from AI.
Social Media Marketing
1
https://mcp.adkit.so/tiktok-ads
adwhiz
com.7275
Read-only MCP access to your DEXUN AdWhiz account: ad accounts, AI recommendations, savings.
Marketing AI & Machine Learning
1
https://www.7275.com/api/mcp
AdsAgent — TikTok Ads MCPB
md.adsagent
Hosted TikTok ads MCP with OAuth, bounded reads, and prepare/confirm writes.
Marketing Social Media
1
https://tiktok.adsagent.md/mcp
Lemonado
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3
https://mcp.lemonado.io/mcp

Related MCP Servers

tiktok-ads-mcp
Marketing Social Media
ysntony
A
license
B
quality
C
maintenance
Provides read-only access to TikTok advertising data, including campaigns, ad groups, ads, and performance reports through the TikTok Business API.
Updated 2 months ago (2026-09-17 08:03 UTC)
6
102 PyPI
46
MIT
flin-google-ads-mcp
Marketing Search
flin-agency
A
license
B
quality
B
maintenance
Read-only MCP server for Google Ads, enabling querying campaigns, ad groups, ads, insights, and keywords without create/update/delete operations.
Updated 7 days ago (2026-11-07 09:22 UTC)
9
MIT
flin-meta-ads-mcp
Marketing Social Media
flin-agency
A
license
B
quality
B
maintenance
Read-only MCP server for Meta Ads that lists and reads ad accounts, campaigns, ad sets, ads, ad images, creatives, and fetches insights at various levels.
Updated 7 days ago (2026-11-07 09:34 UTC)
18
MIT
unofficial-reddit-ads-mcp
Marketing Social Media Research & Data
goncaloaguer
A
license
Not graded
quality
C
maintenance
Read-only MCP server for the Reddit Ads API v3, enabling AI assistants to analyze ad performance, campaigns, reports, and targeting without modifying anything.
Updated 2 days ago (2026-11-12 16:24 UTC)
MIT