Skip to content
MCP server

TikTok GMV Max

Read-only TikTok Business API access for GMV Max campaigns, reports and balances

Runs locallyStatus and history
Install
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-mcp

Add 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 IDRequired
  • TIKTOK_SECRETTikTok Business API app secretRequired
  • TIKTOK_ACCESS_TOKENLong-lived Business API access tokenRequired
  • TIKTOK_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.

How AIPoweredBot checks servers