Skip to main content
Glama
README.md
# taobao-seller-mcp

淘宝 / 天猫卖家 MCP 服务器:生意参谋的经营概况、每日走势、今日实时、流量来源、商品排行、单品分析、引流搜索词、推广花费;生意参谋「市场」免费版(普惠版)的类目大盘、类目排行(交易 / 增速 / 流量 / 加购收藏 / 新品)、价格带和各价格带热销商品的件单价、属性分析、热搜 / 飙升词;竞店监控、竞店对比、竞品流失;以及千牛的订单和商品。

所有数据都从**本机紫鸟(Ziniao)店铺浏览器里已登录的页面**取:在生意参谋和千牛标签页里调后台自己的接口,不走淘宝开放平台,不需要 AppKey,也不需要额外授权。请求走那家店的紫鸟代理 IP。

- **只读**:不改价、不改商品、不发货、不联系买家。
- **天猫、淘宝都支持**(自动识别);**多店铺**:一个配置连多家店,工具里用 `shop` 选店。
- **不打扰干活**:紫鸟窗口最小化时照常工作——页面里用原生 fetch 发请求、mtop 签名在 Node 侧完成,不依赖会被 Chrome 限流的页面定时器;需要新开标签页时会自动再最小化回去,工作标签页开好后一直复用。工作标签页有自己的标记,**不会接管你自己打开的生意参谋 / 千牛页面**;被带到别的页面时会自己跳回去。
- **不输出买家信息**:订单接口本身隐藏买家昵称,结果里也不带收货信息;去掉了卖家 ID(含加密 ID)和链接跟踪参数。
- **遇到安全验证就停**:识别出淘宝安全验证(滑块 / 验证码 / RGV587)后不重试、不换接口再试,并且这家店 10 分钟内不再发请求(记在数据目录的 `cooldown.json`,用同一个数据目录的其他 MCP 进程也会停;删掉它可立即恢复);一次工具调用里的多个请求一个接一个发,前一个被拦就不发后面的;单次请求超时会取消浏览器里还没结束的请求。
- 零依赖,Node.js ≥ 22。

## 前提

1. 本机装了紫鸟客户端和 `ziniao-cli`(`ziniao-cli store list` 能列出店铺)。用客户端自带的 Node 启动 MCP 时(如 Accio),会自动去 nvm / Homebrew / npm 全局目录找 `ziniao-cli`,找不到可用 `ZINIAO_CLI` 指定。
2. 店铺浏览器里登录了这家店的千牛(myseller.taobao.com),生意参谋能正常打开。
3. 店铺浏览器没开时工具会通过 `ziniao-cli` 自动打开(会弹出一次窗口)。每家店会用两个标签页:生意参谋、千牛(订单接口只允许千牛页面跨域调用)。

## 配置

```json
{
  "mcpServers": {
    "taobao-seller": {
      "command": "npx",
      "args": ["-y", "taobao-seller-mcp@latest"],
      "env": {
        "TB_SHOPS": "[{\"name\":\"天猫店\",\"store_id\":\"12345678901234\",\"default\":true},{\"name\":\"淘宝店\",\"store_id\":\"23456789012345\"}]"
      }
    }
  }
}
```

| 环境变量 | 说明 |
|---|---|
| `TB_SHOPS` | 店铺数组(JSON)。`store_id` 是**紫鸟店铺 ID**(`ziniao-cli store list` 里的 storeId),`name` 随便起,`default: true` 标默认店(不标则第一家)。 |
| `TB_STORE_ID` | 只有一家店时可以只设紫鸟店铺 ID,代替 `TB_SHOPS`。 |
| `TB_DATA_DIR` | 数据目录(冷却记录),默认 `~/.taobao-seller-mcp`。多个程序用同一个紫鸟浏览器时共用这个目录,才能互相排队:排队用的是由这个目录算出来的本机端口(127.0.0.1 上 20000–29999 之间的一个),进程退出时自动释放。 |
| `ZINIAO_CLI` | `ziniao-cli` 的路径(自动查找失败时)。 |

配置写错时服务器照常启动,调用任何工具都会返回具体哪里错了。

## 工具

| 工具 | 内容 |
|---|---|
| `tb_shops` | 已配置的店铺 |
| `tb_store_overview` | 支付金额、支付买家数、支付转化率、客单价、访客数、浏览量、UV 价值、新老访客、跳失率、加购 / 收藏人数、新老支付买家;下单金额 / 买家 / 转化;推广总花费、点击、ROI。单日 / 近 7 天 / 近 30 天,带较上期变化。单日另给支付件数、净支付、退款(金额 / 退款率)、老客复购、咨询率、物流时效,以及同行同层平均 / 优秀 |
| `tb_store_trend` | 近 30 天每日:支付金额、买家、转化、客单价、访客、浏览、件数、加购、净支付、退款、老买家支付,附合计;可选同行平均 / 优秀线 |
| `tb_store_today` | 今天到目前为止的实时数据,带较昨天同时段变化 |
| `tb_traffic_sources` | 全店无线端各来源(推荐、手淘搜索、直通车 / 全站推广、站外…)的访客、加购、支付买家、转化;传 `product_id` 看单品来源树(含二级来源、支付金额) |
| `tb_product_rank` | 商品排行:按支付金额 / 访客 / 件数 / 转化率 / 加购 / 收藏排序;支付、访客、搜索引导访客和转化、加购、收藏、下单、退款、客单价、跳出率、停留时长、环比 |
| `tb_product_analysis` | 单品(商品 360):核心指标(含推广消耗、直接 ROI、询单 / 静默转化率)、每日走势、各 SKU 成交、流量来源树 |
| `tb_search_words` | 引流搜索词:买家搜哪些词进店,每个词的访客、加购、收藏、支付买家、金额、转化率 |
| `tb_market_categories` | 市场:这家店在「市场」里能看的类目(ID、路径、是否叶子) |
| `tb_market_overview` | 市场:类目大盘(支付买家数、支付金额占比、增幅、供需比)和价格段 |
| `tb_market_rank` | 市场:类目商品 / 店铺排行(排名变化、是否天猫、支付买家、访客、核心词、是否本店);榜单可选交易总量、交易增速、流量总量(多给搜索访客)、加购收藏(多给加购 / 收藏人数)、新品流量(店铺只有交易总量 / 增速);可按价格段筛选 |
| `tb_market_prices` | 市场:类目价格带(支付买家数和生意参谋的建议);指定价格带时给这个价格带里卖得最好的商品:支付单量、**件单价**(成交均价)、支付金额 |
| `tb_market_attributes` | 市场:类目属性分析——可分析的属性;1~2 个属性的取值(组合)的支付买家数、支付金额占比和增速、动销商品增速;某个取值下的热销商品和件单价 |
| `tb_market_search_words` | 市场:类目热搜词 / 飙升词(搜索词或核心词),搜索人气、点击率、支付转化率、飙升幅度,可按关键词筛选 |
| `tb_competitors` | 竞店监控:生意参谋里设置的竞店,支付买家、访客和变化、标签(交易大增 / 流量大增)、动态 |
| `tb_competitor_shop` | 竞店对比:本店 vs 1~2 家监控竞店的访客、支付买家、转化率、加购、收藏,某个指标的近 30 天每日走势,竞店热门商品和动态 |
| `tb_competitor_loss` | 竞品流失:本店哪些商品的买家流失到了竞品(流失金额、人数、流失率、收藏 / 加购后流失、流失去了多少竞品 / 竞店),以及最近一天访客流失最多的竞品和竞店 |
| `tb_orders` | 千牛「已卖出的宝贝」:按标签(近 3 个月、待付款、待发货、即将 / 已经超时、已发货、退款中、成功、关闭、3 个月前)筛选翻页;订单号、下单时间、状态、实付、商品(标题、SKU、商家编码、数量、金额、状态);附待发货 / 超时计数 |
| `tb_products` | 千牛「我的宝贝」:出售中 / 仓库中;标题、商家编码、价格、库存、近 30 天销量、类目、上架时间、基础质量分、流量标签 |

## 口径

- 生意参谋按**北京时间自然日**出数,最新通常到昨天;`date` 不填就用接口给的最新日期。金额人民币。
- 指标中文名取自生意参谋自己的指标字典,和后台一致。
- 流量来源是按来源去重的访客,同一访客可能来自多个来源,不要相加。
- 市场数据来自生意参谋「市场」**免费版(普惠版)**:只能看这家店经营的类目,指标是区间(如「7500 ~ 1万」),原样输出。
- **件单价** = 支付金额 ÷ 支付件数,是成交均价(含优惠、多个 SKU 平均),不是商品标价;价格带热销商品给的是数值,属性热销商品给的是档位(如「30+」)。
- `tb_market_prices` 的价格带来自「类目洞察 → 价格分析」,和 `tb_market_overview` 的价格段(用于 `tb_market_rank` 筛选)分法不同,不能混用。
- 竞店对比只能选生意参谋里已经设置监控的竞店,本店是精确值、竞店是区间。竞品流失里本店商品的流失数据是精确值,流失去向是流失指数(只比较相对大小)。
- 竞品对比(单个竞品商品)要先在生意参谋里关注竞品,暂未接入。

## 速度

生意参谋 / 千牛标签页首次打开各约 5–10 秒;之后每次查询 0.1–0.6 秒(订单约 0.3–1 秒)。同一个紫鸟浏览器同一时间只跑一个任务。

短时间内大量查询(比如一小时内上百次)会触发淘宝风控,生意参谋的市场接口会要求滑块验证。日常分析的量没问题,不要拿它做批量抓取。

## 说明

非官方工具:用的是生意参谋 / 千牛页面自己调用的内部接口,平台改版可能导致失效。请求和你在后台手动查看一样走店铺浏览器,但请控制调用频率,遇到安全验证时先在浏览器里手动处理,不要反复重试;使用时请遵守平台规则。

## 开发

```bash
npm test
```

测试不连浏览器。

## License

MIT