TikTok GMV Max

TikTok GMV Max MCP

一个只读的 Model Context Protocol 服务，用于 TikTok Business（Marketing）API，并提供一流的 GMV Max 支持。询问助手你的 GMV Max 广告系列、常规广告和 Business Center 预算的表现，即可获得按你店铺时区和美元显示的答案。

它每天在生产环境中运行，支撑多店铺 TikTok Shop 报告系统，因此除了基础 API 封装之外，大部分代码都用于处理原始 API 的问题。报告日期会从广告账户时区调整为店铺时区。非美元账户会按当日汇率换算。TikTok 的临时 51010 超时会重试。

最初是 ysntony/tiktok-ads-mcp（MIT）的分支，涵盖六种核心广告系列和报告工具。本项目新增了 GMV Max、时区对齐和日期范围报告、创意素材、Business Center 财务信息及热门标签，并以独立的 tiktok-gmvmax-mcp 发布。Python 导入包仍为 tiktok_ads_mcp，因此不要在同一环境中安装这两个发行包。

工具（24 个，均为只读）

GMV Max

工具	返回内容
get_gmvmax_campaigns_tool	GMV Max 广告系列及其状态和 ROI 保护信息
get_gmvmax_campaign_info_tool	单个广告系列的预算、出价、商品和排期
get_gmvmax_reports_tool	GMV Max 效果报告（/gmv_max/report/get/）
get_gmvmax_report_aligned_tool	按店铺时区计算的单日数据，由小时数据重建：花费、总收入、订单、ROI
get_gmvmax_range_report_tool	日期范围内的花费 / GMV / 订单 / ROI 汇总
get_gmvmax_videos_tool	店铺可用于 GMV Max 的视频
get_gmvmax_store_list_tool	与 GMV Max 广告主关联的店铺

账户、广告系列和广告

工具	返回内容
get_business_centers_tool	令牌可访问的 Business Center
get_authorized_ad_accounts_tool	所有已授权的广告主账户
get_campaigns_tool / get_ad_groups_tool / get_ads_tool	可筛选的广告系列、广告组和广告列表
get_identities_tool	获授权为广告主使用的 TikTok 身份（创作者账户）
get_video_info_tool	根据视频 ID 获取视频素材 URL、封面图和时长

报告

工具	返回内容
get_reports_tool	支持自定义维度和指标的综合报告
get_ads_report_aligned_tool	手动出价广告的按店铺时区计算的单日数据：花费、GMV、订单、ROAS
get_ads_range_report_tool	手动出价广告在日期范围内的汇总
get_creative_report_tool	创意素材级视频洞察（互动、播放指标）

Business Center 财务信息

工具	返回内容
get_advertiser_balance_tool	每个广告主的余额和基本信息（每次调用 ≤100 个 ID）
get_bc_balance_tool	Business Center 可用资金
get_bc_account_cost_tool	日期范围内 BC 下各广告账户的花费
get_bc_transactions_tool	BC 或广告主层级的充值和扣款
get_bc_budget_changelog_tool	谁在何时更改了广告主的预算

发现

工具	返回内容
get_trending_list_tool	按国家/地区划分的热门标签（7 或 30 天），可选每日历史记录

安装

需要 Python 3.10+。

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

配置

在 TikTok for Business 开发者门户中创建应用，为所需的端点（广告账户、广告系列和广告、报告、GMV Max、Business Center）授予读取权限，并生成长期有效的访问令牌。

变量	必填	含义
TIKTOK_APP_ID	是	应用 ID
TIKTOK_SECRET	是	应用密钥
TIKTOK_ACCESS_TOKEN	是	访问令牌
TIKTOK_ACCESS_TOKEN_2	否	第二个令牌（例如，另一个 Business Center 的令牌），遇到权限错误时尝试使用
TIKTOK_ADVERTISER_ID	否	默认广告主
TIKTOK_SANDBOX	否	设为 true 以使用沙盒 API
TIKTOK_REQUEST_TIMEOUT	否	秒数，默认为 30
TIKTOK_ADS_PROXY	否	仅用于 Business API 调用的代理 URL
LARK_BOT_CACHE_DIR	否	FX 汇率的缓存位置（默认为 ~/.cache/lark-bot）

0.2 之前的版本从 TIKTOK_ACCESS_TOKEN_XINCHENG / TIKTOK_ACCESS_TOKEN_ZECHENG 读取令牌。这些名称仍然可用。

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

值得了解的行为

• 时区。 TikTok 按广告账户的时区报告每天的数据。*_aligned_tool 会获取每小时的数据行，并按店铺时区重新汇总为每日数据，以便广告支出与店铺订单对应。
• 货币。 非 USD 账户的成本和收入会按当天的欧洲央行中间汇率（Frankfurter）换算为 USD。如果汇率 API 不可用，本次调用会使用内置的小型近似汇率表，且不会缓存；其他货币则会以未换算的形式返回（汇率为 1.0），并记录错误日志。
• 重试。 代码 51010（TikTok 后端超时）会在客户端层进行退避重试。限流错误和 5xx 错误也会重试。
• mcp 1.x 和 2.x。 两者均可使用：服务会导入 MCPServer（2.x），并在无法导入时回退到 FastMCP（1.x）。

开发

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

欢迎提交问题和 PR。任何行为变更都请附上测试。

更新日志

0.2.0

• 以 tiktok-gmvmax-mcp 发布（PyPI 名称 tiktok-ads-mcp 属于上游项目）。
• 通用的 TIKTOK_ACCESS_TOKEN / TIKTOK_ACCESS_TOKEN_2。旧名称仍然可用。
• CLI 日志输出到 stderr，使 stdout 保持干净，以供 stdio 协议使用。
• FX：API 中断期间使用的备用汇率不再被永久缓存。
• 自分叉以来新增 18 个工具：GMV Max、对齐报告和范围报告、创意素材、Business Center 财务、身份信息、趋势内容。此外还新增：账户发现、51010 重试、USD 换算、mcp 2.x 兼容性。

0.1.x（上游）

• 六个核心工具、异步 httpx 客户端、FastMCP 服务。请参阅 ysntony/tiktok-ads-mcp。

许可证

MIT。请参阅 LICENSE。