内容
# TikTok 店铺 MCP 服务器
一个 [模型上下文协议](https://modelcontextprotocol.io) (MCP) 服务器，用于 **TikTok 店铺合作伙伴 API** — 查询订单、财务、产品、分析数据和多个店铺的联盟表现，来自 Claude 或其他 MCP 客户端。
为经营 TikTok 店铺的卖家和机构而建，他们希望他们的 AI 助手能够回答诸如 *"美国店铺昨天卖了什么?"*、 *"本周哪些 SKU 很流行?"* 或 *"提取六月份的结算声明"* 等问题 — 直接针对官方 API，无需浏览器抓取。
## 功能特点
- **多店铺支持** — 在一个 JSON 文件中配置任意数量的店铺；每个工具都可选 `seller_name`（部分匹配）来选择店铺
- **25 种工具**，涵盖订单、财务、产品目录、店铺/视频/SKU 分析、联盟最佳卖家、退货/取消和产品编辑
- **人性化日期** — 传递 `start_date=2026-07-01` + IANA 时区，而不是 Unix 时间戳；服务器处理转换
- **令牌生命周期** — 检查过期和刷新访问令牌（单个店铺或所有店铺）而无需离开对话
- **默认弹性** — 所有请求都通过 [`mcp-retry`](https://github.com/Buer2333/mcp-retry)（指数退避 + 429/5xx/网络错误时的抖动）
- **只读为主，可选写入** — 唯一变异工具是显式的（`edit_product`、`clone_product`、`upload_image`）；其他均为只读
## 工具列表
| 分组 | 工具 |
|---|---|
| 店铺与认证 | `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` · `edit_product` · `clone_product` · `upload_image` |
| 店铺分析 | `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` |
## 安装
```bash
pip install tiktok-shop-mcp
```
或从源码安装：
```bash
git clone https://github.com/Buer2333/tiktok-shop-mcp.git
cd tiktok-shop-mcp
pip install -e .
```
## 配置
凭证存储在仓库外部的 JSON 文件中（默认为 `~/.config/tiktok-mcp/shops.json`，可通过环境变量 `TIKTOK_SHOP_CONFIG` 重写）：
```json
[
{
"seller_name": "我的美国店铺",
"seller_base_region": "美国",
"app_key": "...",
"app_secret": "...",
"access_token": "TTP_...",
"refresh_token": "TTP_...",
"shop_id": "...",
"shop_cipher": "..."
}
]
```
通过在 [TikTok 店铺合作伙伴中心](https://partner.tiktokshop.com) 创建应用获取 `app_key` / `app_secret`，然后授权您的店铺以获取令牌。`shop_id` / `shop_cipher` 由授权店铺端点返回；捆绑的 `probe_authorized_shops.py` 脚本可以为您获取它们。
### Claude 代码
```bash
claude mcp add tiktok-shop -- tiktok-shop-mcp
```
### Claude 桌面版 / 其他 MCP 客户端
```json
{
"mcpServers": {
"tiktok-shop": {
"command": "tiktok-shop-mcp",
"env": { "TIKTOK_SHOP_CONFIG": "/path/to/shops.json" }
}
}
}
```
## 示例提示
- *"列出我的店铺及其令牌过期时间"*
- *"2026 年 7 月 18 日美国店铺的订单，东岸时间"*
- *"过去 7 天内哪些创作者为我们带来了最多的 GMV？"*
- *"比较昨天的每小时 GMV 曲线与前一天的曲线"*
- *"刷新所有店铺的令牌"*
## 架构
```
tiktok_shop_mcp/
├── server.py # FastMCP 应用 — 工具定义、日期处理、错误信封
├── client.py # 签名 HTTP 客户端（HMAC-SHA256 请求签名，通过 mcp-retry）
├── config.py # 多店铺凭证加载与解析
└── tools/ # 每个 API 领域一个模块（订单、财务、产品、分析……）
```
所有工具返回结构化 JSON。错误以 `{"error": true, "message": …, "suggestion": …}` 形式返回，以便模型可以自我纠正（例如，刷新过期令牌并重试）。
## 免责声明
这是一个独立的开源项目，与 TikTok 无关或未得到 TikTok 认可。使用 TikTok 店铺 API 须遵守 TikTok 自己的条款。
## 许可证
[MIT](LICENSE)
