TikTok GMV Max

io.github.Buer2333Published by GitHub account Buer2333v0.2.1Updated Nov 7, 2026

Read-only TikTok Business API: GMV Max campaigns and reports, ads, BC balances.

The publisher's own server: Tiktokporn

VerifiedSTDIODesktop onlyFinance Data & Analytics Business & Commerce

Server details

Identifier: io.github.Buer2333/tiktok-gmvmax-mcp
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Oct 19, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account Buer2333 for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.Buer2333%2Ftiktok-gmvmax-mcp.svg)](https://sourceweft.com/mcp/io.github.Buer2333%2Ftiktok-gmvmax-mcp?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Read-only TikTok Business API server for GMV Max campaigns, ads, reports and Business Center balances, with shop-timezone and USD-normalized reporting.

What you can do: List Business Centers, authorized ad accounts, identities and advertiser balances
Browse campaigns, ad groups, ads, video assets and GMV Max campaigns, stores and videos
Pull GMV Max and manual-bid reports, creative video insights, and shop-timezone-aligned or date-range aggregates
Review Business Center funds, per-account spend, transactions and budget change history
Look up trending TikTok hashtags by country over 7 or 30 days
When to use it: Useful when you run TikTok Shop or TikTok Ads accounts and want an assistant to answer questions about GMV Max performance, ad spend, ROI and Business Center budgets without opening Ads Manager. The timezone-aligned and USD-converted reports suit multi-shop reporting where ad-account days do not match shop days.
Requirements: Runs locally via uvx or pip with Python 3.10+. Needs a TikTok for Business developer app with read permissions and a long-lived access token, supplied through TIKTOK_APP_ID, TIKTOK_SECRET and TIKTOK_ACCESS_TOKEN; optional TIKTOK_ACCESS_TOKEN_2, TIKTOK_ADVERTISER_ID, TIKTOK_SANDBOX, TIKTOK_REQUEST_TIMEOUT, TIKTOK_ADS_PROXY. Network access to the TikTok Business API and an FX rate service.

Before you install

Requires an app secret and access tokens (TIKTOK_SECRET, TIKTOK_ACCESS_TOKEN, TIKTOK_ACCESS_TOKEN_2) that grant read access to ad accounts and Business Center finances; store them as secrets. Ad account data and currency amounts are sent to TikTok's API, and non-USD amounts are converted using an external FX rate service. The Python package name clashes with the tiktok-ads-mcp distribution, so do not install both in one environment.

Installation

In SourceWeft

Open TikTok GMV Max in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

Install

Requires Python 3.10+.

bash

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

uvx tiktok-gmvmax-mcp          # run without installing# orpip 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):

json

{  "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"      }    }  }}

{  "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

bash

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

git clone https://github.com/Buer2333/tiktok-gmvmax-mcp && cd tiktok-gmvmax-mcppython -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).

Source: README.md at commit 2f29d41

Tools

get_business_centers_tool

Get business centers accessible by the current access token

Parameterspagebc_idpage_size

get_identities_tool

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.

Parameterspagepage_sizeadvertiser_idrequiredidentity_typeidentity_authorized_bc_id

get_authorized_ad_accounts_tool

Get all authorized ad accounts accessible by the current access token

Parametersrandom_string

get_campaigns_tool

Get campaigns for a specific advertiser with optional filtering

Parametersfiltersadvertiser_idrequired

get_ad_groups_tool

Get ad groups for a specific advertiser with optional filtering

Parameterspagefilterspage_sizecampaign_idadvertiser_idrequired

get_ads_tool

Get ads for a specific advertiser with optional filtering

Parameterspagefilterspage_sizeadgroup_idadvertiser_idrequired

get_reports_tool

Get performance reports and analytics with comprehensive filtering and grouping options

Parameterspagebc_idfiltersmetricsend_datepage_sizedata_leveldimensionsorder_typestart_dateorder_fieldreport_type+6 more

get_gmvmax_campaigns_tool

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

Parameterspagefilteringpage_sizecampaign_idsadvertiser_idrequired

get_gmvmax_reports_tool

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": ["..."]}.

Parameterspagemetricsend_daterequiredfilteringpage_sizestore_idsrequireddimensionsstart_daterequiredadvertiser_idrequired

get_gmvmax_campaign_info_tool

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

Parameterscampaign_idrequiredadvertiser_idrequired

get_video_info_tool

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

Parametersvideo_idsrequiredadvertiser_idrequired

get_creative_report_tool

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

Parameterspageend_daterequiredfilteringpage_sizestart_daterequiredreport_typeadvertiser_idrequired

get_gmvmax_videos_tool

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

Parameterspagestore_idrequiredpage_sizeadvertiser_idrequiredidentity_listneed_auth_code_videostore_authorized_bc_id

get_bc_balance_tool

Get Business Center balance (available funds).

Parametersbc_idrequired

get_bc_account_cost_tool

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

Parameterspagebc_idrequiredend_daterequiredpage_sizestart_daterequired

get_bc_transactions_tool

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

Parameterspagebc_idrequiredend_timerequiredpage_sizestart_timerequiredtransaction_level

get_bc_budget_changelog_tool

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

Parameterspagebc_idrequiredend_daterequiredpage_sizestart_daterequiredadvertiser_idrequired

get_gmvmax_store_list_tool

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

Parametersadvertiser_idrequired

get_advertiser_balance_tool

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

Parametersadvertiser_idsrequired

get_gmvmax_report_aligned_tool

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.

Parametersdaterequiredmetricsshop_tzstore_idsrequiredadvertiser_idrequired

get_ads_report_aligned_tool

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.

Parametersdaterequiredmetricsshop_tzadvertiser_idrequired

get_gmvmax_range_report_tool

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

Parametersend_daterequiredstore_idsrequiredstart_daterequiredadvertiser_idrequired

get_ads_range_report_tool

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

Parametersend_daterequiredstart_daterequiredadvertiser_idrequired

Version history

v0.2.1LatestNov 5, 2026
v0.2.0Oct 19, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listedRequired15 pts
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts