TikTok GMV Max
Read-only TikTok Business API access for GMV Max campaigns, reports and balances
- Pricing
- Open source
- Platforms
- CLI
- Runs
- Locally
- Version
- 0.2.1
- Listing updated
- today
Similar MCP servers
About TikTok GMV Max
TikTok GMV Max is an open-source MCP server for marketing and seo. It runs locally on your machine and is started by your AI client.
This Python server wraps the TikTok Business Marketing API with extra care for TikTok Shop sellers who run GMV Max. Its 24 read-only tools return campaigns, budgets, bids, products and schedules, plus performance reports for GMV Max and regular manual-bid ads, creative-level video insights, Business Center balances, transactions, budget changelogs and trending hashtags.
Much of the code goes beyond plain wrappers. Report days are realigned from the ad account timezone to the shop's, non-USD amounts are converted at that day's rate, and TikTok's transient 51010 timeouts are retried with backoff. It runs daily in production behind a multi-shop reporting stack.
Setup needs a TikTok for Business developer app and a long-lived access token, supplied through environment variables. It is MIT licensed with PyPI distribution.
Install
Run in a terminal
claude mcp add tiktok-gmvmax-mcp --env TIKTOK_APP_ID='<TIKTOK_APP_ID>' --env TIKTOK_SECRET='<TIKTOK_SECRET>' --env TIKTOK_ACCESS_TOKEN='<TIKTOK_ACCESS_TOKEN>' --env TIKTOK_ACCESS_TOKEN_2='<TIKTOK_ACCESS_TOKEN_2>' -- uvx tiktok-gmvmax-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"tiktok-gmvmax-mcp": {
"command": "uvx",
"args": [
"tiktok-gmvmax-mcp"
],
"env": {
"TIKTOK_APP_ID": "<TIKTOK_APP_ID>",
"TIKTOK_SECRET": "<TIKTOK_SECRET>",
"TIKTOK_ACCESS_TOKEN": "<TIKTOK_ACCESS_TOKEN>",
"TIKTOK_ACCESS_TOKEN_2": "<TIKTOK_ACCESS_TOKEN_2>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"tiktok-gmvmax-mcp": {
"command": "uvx",
"args": [
"tiktok-gmvmax-mcp"
],
"env": {
"TIKTOK_APP_ID": "<TIKTOK_APP_ID>",
"TIKTOK_SECRET": "<TIKTOK_SECRET>",
"TIKTOK_ACCESS_TOKEN": "<TIKTOK_ACCESS_TOKEN>",
"TIKTOK_ACCESS_TOKEN_2": "<TIKTOK_ACCESS_TOKEN_2>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"tiktok-gmvmax-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"tiktok-gmvmax-mcp"
],
"env": {
"TIKTOK_APP_ID": "<TIKTOK_APP_ID>",
"TIKTOK_SECRET": "<TIKTOK_SECRET>",
"TIKTOK_ACCESS_TOKEN": "<TIKTOK_ACCESS_TOKEN>",
"TIKTOK_ACCESS_TOKEN_2": "<TIKTOK_ACCESS_TOKEN_2>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"tiktok-gmvmax-mcp": {
"command": "uvx",
"args": [
"tiktok-gmvmax-mcp"
],
"env": {
"TIKTOK_APP_ID": "<TIKTOK_APP_ID>",
"TIKTOK_SECRET": "<TIKTOK_SECRET>",
"TIKTOK_ACCESS_TOKEN": "<TIKTOK_ACCESS_TOKEN>",
"TIKTOK_ACCESS_TOKEN_2": "<TIKTOK_ACCESS_TOKEN_2>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"tiktok-gmvmax-mcp": {
"command": "uvx",
"args": [
"tiktok-gmvmax-mcp"
],
"env": {
"TIKTOK_APP_ID": "<TIKTOK_APP_ID>",
"TIKTOK_SECRET": "<TIKTOK_SECRET>",
"TIKTOK_ACCESS_TOKEN": "<TIKTOK_ACCESS_TOKEN>",
"TIKTOK_ACCESS_TOKEN_2": "<TIKTOK_ACCESS_TOKEN_2>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
TIKTOK_APP_IDTikTok Business API app IDRequiredTIKTOK_SECRETTikTok Business API app secretRequiredTIKTOK_ACCESS_TOKENLong-lived Business API access tokenRequiredTIKTOK_ACCESS_TOKEN_2Optional second token, tried on permission errors
Tools this server provides (8)
Taken from the project documentation; the running server may differ.
- get_gmvmax_campaigns_tool
- GMV Max campaigns with status and ROI-protection info.
- get_gmvmax_reports_tool
- GMV Max performance reports.
- get_gmvmax_report_aligned_tool
- One shop-timezone day from hourly data.
- get_gmvmax_range_report_tool
- Aggregate report for a date range.
- get_reports_tool
- Integrated reports with custom dimensions.
- get_bc_balance_tool
- Business Center available funds.
- get_bc_budget_changelog_tool
- Who changed a budget and when.
- get_trending_list_tool
- Trending hashtags by country.
What it does
- GMV Max reports
- Cost, revenue, orders and ROI for one day or a range.
- Timezone alignment
- Days realigned to the shop's timezone.
- USD conversion
- Non-USD accounts converted at that day's rate.
- Business Center finance
- Balances, spend, transactions and budget changes.
- Creative insights
- Video engagement and play metrics.
- Retry handling
- Retries transient TikTok timeouts.
Good for
- Check yesterday's GMV Max ROI by shop
- See who changed an advertiser's budget
- Compare manual-bid ads over a date range
- Find trending hashtags for a country
Pricing
Open source
MIT licensed; requires a TikTok Business API app.
TikTok GMV Max FAQ
Can it change campaigns?
No, all 24 tools are read-only.
What credentials are required?
App ID, secret and a long-lived access token.
Which Python?
3.10 or later.
Licence?
MIT.
Is TikTok GMV Max free?
Yes. TikTok GMV Max is open source, so you can use and self-host it for free.
How do I add TikTok GMV Max to Claude Code?
Run this command in your terminal: claude mcp add tiktok-gmvmax-mcp --env TIKTOK_APP_ID='<TIKTOK_APP_ID>' --env TIKTOK_SECRET='<TIKTOK_SECRET>' --env TIKTOK_ACCESS_TOKEN='<TIKTOK_ACCESS_TOKEN>' --env TIKTOK_ACCESS_TOKEN_2='<TIKTOK_ACCESS_TOKEN_2>' -- uvx tiktok-gmvmax-mcp
What are the best alternatives to TikTok GMV Max?
The closest alternatives to TikTok GMV Max are Google Ads + Meta Ads + SEO/GEO MCP, ChatGPT for Amazon, Calven, O'So MCP Server for PrestaShop and Ebid.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.