# TikTok GMV Max

> TikTok GMV Max is an open-source MCP server for marketing and seo. Read-only TikTok Business API access for GMV Max campaigns, reports and balances. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI
- **Repository:** https://github.com/buer2333/tiktok-gmvmax-mcp
- **MCP Registry name:** io.github.Buer2333/tiktok-gmvmax-mcp
- **Categories:** [marketing and SEO](https://ai-powered.com/categories/marketing-and-seo), [e-commerce](https://ai-powered.com/categories/e-commerce)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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.

## 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.

## Alternatives

- [Google Ads + Meta Ads + SEO/GEO MCP](https://ai-powered.com/mcp/google-ads-meta-ads-seo-geo-mcp): Google Ads + Meta Ads + SEO/GEO MCP is a freemium MCP server for marketing and seo.
- [ChatGPT for Amazon](https://ai-powered.com/mcp/chatgpt_for_amazon): ChatGPT for Amazon is a freemium MCP server for marketing.
- [Calven](https://ai-powered.com/mcp/calven): Calven is an MCP server for marketing and seo.
- [O'So MCP Server for PrestaShop](https://ai-powered.com/mcp/o-so-mcp-server-for-prestashop): O'So MCP Server for PrestaShop is an open-source MCP server for e-commerce.
- [Ebid](https://ai-powered.com/mcp/ebid): Ebid is a freemium MCP server for e-commerce.
- [Customer Io](https://ai-powered.com/mcp/customer-io): Customer Io is a freemium MCP server for marketing and seo.
- [Zovo QR Code Maker](https://ai-powered.com/mcp/zovo-qr-code-maker): Zovo QR Code Maker is an MCP server for marketing and seo.
- [Google_search_console](https://ai-powered.com/mcp/google-search-console-8): Google_search_console is a freemium MCP server for web search and scraping.

---
Source: https://ai-powered.com/mcp/tiktok-gmv-max
