TikTok Shop

tiktok-shop-mcp

一个用于 TikTok Shop Partner API 的 模型上下文协议（MCP）服务，可通过 Claude 或任何其他 MCP 客户端查询多家店铺的订单、财务、商品、分析数据和联盟营销表现。

专为经营 TikTok Shop 的卖家和代理机构打造，帮助他们让 AI 助手直接通过官方 API 回答诸如 “美国店铺昨天卖了什么？”、“本周哪些 SKU 正在热销？” 或 “调取 6 月的结算单” 等问题，无需抓取浏览器数据。

功能

• 多店铺 — 在一个 JSON 文件中配置任意数量的店铺；每个工具都接受可选的 seller_name（部分匹配）来选择店铺
• 22 个工具，涵盖订单、财务、商品目录、店铺/视频/SKU 分析、联盟营销畅销商品以及退货/取消订单
• 人类可读的日期 — 传入 start_date=2026-07-01 和 IANA 时区即可，无需使用 Unix 时间戳；服务会处理转换
• 令牌生命周期管理 — 无需离开对话即可查看令牌过期时间并刷新访问令牌（单个店铺或所有店铺）
• 默认具备弹性 — 所有请求都通过 mcp-retry 发送（遇到 429/5xx/网络错误时采用指数退避并加入抖动）
• 对店铺只读 — 没有任何工具会编辑商品信息、创建商品或上传文件。服务唯一会写入的内容是刷新令牌时更新你自己的 shops.json，并设置仅所有者可访问（0600）的权限。为加强防护，请仅授予 Partner Center 应用只读范围

工具

分组	工具
店铺与身份验证	list_shops · refresh_token · refresh_all_tokens
订单	get_shop_orders · get_order_detail · search_returns · search_cancellations
财务	get_shop_statements · get_shop_transactions
商品	get_shop_products · get_product_detail
店铺分析	get_shop_performance · get_shop_performance_hourly · get_shop_products_performance · get_product_performance · get_shop_videos_performance · get_sku_performance · get_customer_service_performance
视频与联盟营销	get_account_video_gmv · get_videos_bestselling · get_creators_bestselling · get_products_bestselling

安装

pip install tiktok-shop-mcp

也可以从源码安装到虚拟环境中，并将直接依赖项固定为测试所用的版本：

git clone https://github.com/Buer2333/tiktok-shop-mcp.git
cd tiktok-shop-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install --no-deps -e .

requirements.txt 将直接运行时依赖项固定为精确版本，其中包括 mcp-retry，它会封装每次 API 调用，因此能够访问你的令牌。传递依赖项（pydantic、starlette 等）未固定；如需完全可复现的安装，请使用 pip-compile --generate-hashes 生成锁定文件。只有在了解某个版本的变更内容后，才更新固定版本。

兼容性

同时兼容 mcp 1.x 和 2.x。mcp 2.0 将 FastMCP 重命名为 MCPServer （mcp.server.mcpserver），并将 mcp.server.fastmcp 改为会抛出异常的存根；server.py 通过 try-v2-except-v1 垫片导入。测试已通过 1.28.1 和 2.1.1；requirements.txt 固定为 2.1.1。

配置

凭据保存在仓库之外的 JSON 文件中（默认路径为 ~/.config/tiktok-mcp/shops.json，可通过 TIKTOK_SHOP_CONFIG 环境变量覆盖）。服务不会读取项目文件夹中的 shops.json，因此放在项目文件夹中的副本不会被意外读取、同步或提交。请将文件权限设置为仅所有者可读写：

chmod 700 ~/.config/tiktok-mcp && chmod 600 ~/.config/tiktok-mcp/shops.json

设置脚本会在该文件旁留下令牌备份（shops.json.bak.* 和 recovery/ 文件夹）；商店正常工作后，请删除这些备份。旁边还会有一个小型 shops.json.lock 文件；服务、cron 刷新器和设置脚本会通过它避免同时写入文件，请勿删除。

[
  {
    "seller_name": "MY SHOP US",
    "seller_base_region": "US",
    "app_key": "...",
    "app_secret": "...",
    "access_token": "TTP_...",
    "refresh_token": "TTP_...",
    "shop_id": "...",
    "shop_cipher": "..."
  }
]

创建应用后，可从 TikTok Shop Partner Center 获取 app_key / app_secret，然后授权你的商店以获取令牌。shop_id / shop_cipher 由已授权商店端点返回；随附的 probe_authorized_shops.py 脚本可以帮你获取这些值。

三个 *_bestselling 工具需要使用已启用 Bestsellers 权限范围的应用所关联的商店。这些列表适用于整个平台，因此有一家这样的商店就足够了：将 TIKTOK_SHOP_BESTSELLERS_SHOP 设为该商店的 seller_name（支持部分匹配），如果省略 seller_name，工具就会使用它。若未设置该变量，工具会回退到 shops.json 中的第一家商店。

Claude Code

claude mcp add tiktok-shop -- tiktok-shop-mcp

Claude Desktop / 其他 MCP 客户端

{
  "mcpServers": {
    "tiktok-shop": {
      "command": "tiktok-shop-mcp",
      "env": { "TIKTOK_SHOP_CONFIG": "/path/to/shops.json" }
    }
  }
}

提示词示例

• “列出我的商店及其令牌过期时间”
• “查询 2026-07-18 Eastern time 的 MY SHOP US 订单”
• “过去 7 天里，哪些创作者为我们带来了最多 GMV？”
• “比较昨天和前一天的每小时 GMV 曲线”
• “刷新所有商店的令牌”

架构

tiktok_shop_mcp/
├── server.py     # FastMCP app — tool definitions, date handling, error envelope
├── client.py     # Signed HTTP client (HMAC-SHA256 request signing, via mcp-retry)
├── config.py     # Multi-shop credential loading & resolution
└── tools/        # One module per API domain (orders, finance, products, analytics…)

所有工具都会返回结构化 JSON。错误将以 {"error": true, "message": …, "suggestion": …} 的形式返回，以便模型自行纠正（例如，刷新已过期的令牌并重试）。

免责声明

这是一个独立的开源项目，与 TikTok 无关联，也未获得其认可。TikTok Shop API 的使用须遵守 TikTok 自身的条款。

许可证

MIT