Skip to main content
Glama
aliexpress-seller-mcp

aliexpress-seller-mcp

by mrsxs
README.md
# aliexpress-seller-mcp

速卖通卖家 MCP 服务器:店铺经营数据(生意参谋)、订单、商品、类目大盘与热搜词,以及按收货国家图搜的竞品比价和价格监控。

所有数据都从**本机紫鸟(Ziniao)店铺浏览器里已登录的页面**取:卖家数据在卖家后台标签页里调后台自己的接口,比价在买家前台标签页里图搜。
不走速卖通开放平台,不需要 AppKey,也不需要额外授权。

- **只读**:不改价、不改商品、不发货。唯一的写操作是本机的竞品监控数据。
- **普通店、半托管、全托管都支持**(自动识别店铺模式;全托管店没有买家订单接口)。
- **多店铺**:一个配置连多家店,工具里用 `shop` 选店。
- **不打扰干活**:紫鸟窗口最小化时照常工作。请求签名在 Node 侧完成,不依赖页面定时器(Chrome 会限流后台页面的定时器);需要新开标签页时会自动再最小化回去,工作标签页开好后一直复用。工作标签页有自己的标记,**不会接管你自己打开的速卖通页面**;被带到别的页面时会自己跳回去。
- **遇到安全验证就停**:识别出速卖通安全验证(滑块 / 验证码 / RGV587)后不重试、不换接口再试;图搜在某个国家遇到验证就整体停下(不再搜后面的国家,并还原收货地 cookie)。这家店 10 分钟内不再发请求(记在数据目录的 `cooldown.json`,用同一个数据目录的其他 MCP 进程也会停;删掉它可立即恢复)。一次工具调用里的多个请求一个接一个发,前一个被拦就不发后面的;单次请求超时会取消浏览器里还没结束的请求。
- **不输出买家信息**:订单不输出买家名;订单「服务」列只输出已知的状态短语;接口错误信息会去掉链接和像 ID 的长串。
- 零依赖,Node.js ≥ 22。

## 前提

1. 本机装了紫鸟客户端和 [`ziniao-cli`](https://www.ziniao.com/),并且能在命令行里用(`ziniao-cli store list` 能列出店铺)。
2. 店铺浏览器里登录了速卖通卖家后台(csp.aliexpress.com)。比价用同一个店铺浏览器的买家前台,不需要另外登录。
3. 店铺浏览器没开时工具会通过 `ziniao-cli` 自动打开(会弹出一次窗口)。

## 配置

```json
{
  "mcpServers": {
    "aliexpress-seller": {
      "command": "npx",
      "args": ["-y", "aliexpress-seller-mcp@latest"],
      "env": {
        "AE_SHOPS": "[{\"name\":\"主店\",\"store_id\":\"12345678901234\",\"default\":true},{\"name\":\"全托管店\",\"store_id\":\"23456789012345\"}]"
      }
    }
  }
}
```

| 环境变量 | 说明 |
|---|---|
| `AE_SHOPS` | 店铺数组(JSON)。`store_id` 是**紫鸟店铺 ID**(`ziniao-cli store list` 里的 storeId),`name` 随便起,`default: true` 标默认店(不标则第一家)。 |
| `AE_STORE_ID` | 只有一家店时可以只设紫鸟店铺 ID,代替 `AE_SHOPS`。 |
| `AE_DATA_DIR` | 竞品监控数据和冷却记录目录,默认 `~/.aliexpress-seller-mcp`。和其他用同一个紫鸟浏览器的程序共用这个目录,才能互相排队:排队用的是由这个目录算出来的本机端口(127.0.0.1 上的一个端口,进程退出时自动释放);同一个监控同一时间也只跑一轮。 |
| `ZINIAO_CLI` | `ziniao-cli` 的路径(不在 PATH 里时)。 |

配置写错时服务器照常启动,调用任何工具都会返回具体哪里错了(不会只显示 “exited with code 1”)。

## 工具

### 店铺经营(生意参谋)

| 工具 | 内容 |
|---|---|
| `ae_shops` | 已配置的店铺 |
| `ae_store_overview` | 支付金额、支付买家数、支付转化率、客单价、支付订单数、支付件数、访客数、浏览量、跳失率、新访客数;单日 / 近 7 天 / 近 30 天,带较上一周期变化,单日另有周同比 |
| `ae_store_trend` | 近 30 天每日的上述交易和流量指标,附合计;可选同行优秀 / 同行平均线 |
| `ae_store_today` | 今天(美国太平洋时间)到目前为止的实时数据 |
| `ae_traffic_sources` | 流量来源(搜索、导购频道、推荐、会场、基础工具、站外…)的访客数、占比、下单转化率,分 APP / 非 APP;可看全店或单个商品 |
| `ae_product_rank` | 商品排行:按支付金额 / 访客 / 收藏 / 加购排序,每个商品的支付、访客、搜索曝光、转化、加购、收藏、退款、停留时长和环比 |
| `ae_product_analysis` | 单品深入分析:买家搜索词(曝光、访客、支付,带英文翻译)、分国家表现、流量来源 |

### 订单与商品

| 工具 | 内容 |
|---|---|
| `ae_orders` | 订单列表:按状态 / 订单类型筛选、翻页、按订单号查;订单金额、国家、标签、商品明细;附订单看板计数(今日新订单、待发货、纠纷中…)。买家名不输出。全托管店没有订单。 |
| `ae_products` | 商品列表:正在销售 / 已下架 / 草稿 / 审核中 / 审核不通过,半托管各标签页;价格、库存、近 30 天销量 / 访客 / 曝光 / 支付 / 转化、参加的活动,可选 SKU 明细。全托管店给供货价(CNY)和备货模式。 |

### 市场(整个类目,非本店)

| 工具 | 内容 |
|---|---|
| `ae_categories` | 按中文名查类目 ID,或列子类目 |
| `ae_market_overview` | 类目大盘:访客指数、搜索指数、交易指数、客单价、供需指数、加购 / 收藏人数;子类目构成、国家构成 |
| `ae_search_words` | 类目热搜词:搜索次数 / 人数及变化、点击率、转化率、支付订单数、供需比、主要搜索国家、是否品牌词 |

### 竞品比价(买家前台图搜)

| 工具 | 内容 |
|---|---|
| `ae_search` | 用商品图按收货国家图搜,返回每国同款的价格分布和靠前商品(标价、展示价、去掉新人补贴的参考价、活动、销量) |
| `ae_watch_create` / `ae_watch_run` | 建竞品监控、立即跑一轮(适合交给定时任务按间隔调用),自动比出改价和活动变化 |
| `ae_watches` / `ae_latest` / `ae_history` / `ae_events` | 查监控列表、最新一期价格、某个竞品的价格走势、改价和活动事件 |

## 口径

- 生意参谋按**美国太平洋时间**出数,最新通常到昨天;`date` 不填就用接口给的最新日期。
- 金额 USD;支付金额含平台代收税费(支付金额 − 税费 = 订单金额)。全托管商品列表里的价格是供货价(CNY)。
- 流量来源只能分 APP / 非 APP 两端查;同一访客可能来自多个渠道,各渠道相加大于总访客。
- 市场数据是指数化的类目数据,不是本店数据。
- 订单列表最多翻到 5000 条(后台限制)。

## 速度

卖家后台标签页首次打开约 10 秒,之后每次查询 0.3–1 秒(订单翻页 / 筛选约 1–2 秒);图搜每个国家约 1–2 秒。同一个紫鸟浏览器同一时间只跑一个任务,多个进程通过 `AE_DATA_DIR` 算出来的本机锁端口排队。

## 开发

```bash
npm test
```

测试不连浏览器;`test/fixtures` 是去掉了账号信息的速卖通搜索页样本。

## License

MIT