io.github.TonyWang-hub/mcp-cn-commerce

Official

by TonyWang-hub · Python

Read-only merchant data from 8 Chinese e-commerce platforms: orders, products, after-sales, ads

Read-only merchant data from 8 Chinese e-commerce platforms including orders and analytics.

Topics

agent-toolai-agentai-toolsbusiness-datachina-ecommerceclaudedata-integrationdoudianecommercejdmcpmcp-servermodel-context-protocoloceanenginepinduoduopythontaobao

README.md19 KBView on GitHub

mcp-cn-commerce — 中国电商平台 MCP Server

🛒 让 AI Agent 直接读取中国电商平台的商家经营数据。 不做内容发布，只做经营数据的 MCP 连接器。

国内首个面向中国电商商家经营场景的开源 MCP Server 套件。支持 Claude、ChatGPT、Gemini 等 AI Agent 接入。

搜索关键词: MCP Server, Model Context Protocol, 电商 MCP, AI Agent, 电商数据, 抖店 MCP, 京东 MCP, 巨量引擎 MCP, 淘宝 MCP, 拼多多 MCP, Python MCP, MCP 中国电商, 商家经营数据, 电商经营分析, AI 电商, Claude MCP

English | 简体中文

这是什么？

一个 MCP (Model Context Protocol) Server 套件（Monorepo），让 AI Agent 能够结构化地访问中国电商平台的商家经营数据。每个平台是一个独立的 MCP Server，按需安装使用：

巨量引擎 / 巨量千川 — 广告投放数据（广告计划、报表、账户余额）
抖店 — TikTok 电商店铺经营数据（订单、商品、售后、退款）
京东 — 京东商家后台数据（订单、商品、店铺信息）
淘宝 / 拼多多 — 订单、商品、物流
快手 / 小红书 / 微信小店 — 订单、商品、库存

所有工具默认只读 — AI Agent 可以分析你的经营数据，但无法修改任何内容。

为什么选择这个项目？

国内已有的 MCP Server 全是内容发布（发视频、搜热搜），没有一个是商家经营（拉广告数据、看订单、管售后）。

	内容侧 MCP（HuiMei/Astron 等）	mcp-cn-commerce
做什么	发视频、搜热点	拉广告报表、查订单
目标用户	自媒体/创作者	电商老板/运营/数据分析师
数据类型	内容数据（播放量、点赞、热搜）	经营数据（收入、订单、退款、ROAS）
覆盖平台	内容平台	电商+广告平台
操作	发布/写入	只读分析 & 监控

这是国内首个面向电商商家经营场景的开源 MCP Server 套件。

典型使用场景：

AI Agent 每日自动拉取广告 ROAS 和消耗，生成投放优化建议
多平台订单数据汇总，用自然语言提问即可分析
库存预警：AI 监控商品库存，低库存自动提醒
售后分析：定期拉取退款数据，发现商品质量问题趋势

平台覆盖

平台	类型	Phase	状态	测试	开放平台
巨量引擎 (Ocean Engine)	广告投放	1	✅	24	open.oceanengine.com
巨量千川 (Qianchuan)	电商广告	1	✅	(同上)	qianchuan.jinritemai.com
抖店 (Douyin Shop)	电商店铺	1	✅	31	op.jinritemai.com
京东 (JD.com)	电商店铺	1	✅	19	jos.jd.com
淘宝 (Taobao)	电商店铺	2	✅	36	open.taobao.com
拼多多 (Pinduoduo)	电商店铺	2	✅	30	open.pinduoduo.com
快手 (Kuaishou)	电商店铺	3	✅	33	open.kuaixiaodian.com
小红书 (Xiaohongshu)	电商店铺	3	✅	33	open.xiaohongshu.com
微信小店 (WeChat Store)	电商店铺	3	✅	25	developers.weixin.qq.com

Phase 4: 闲鱼、美团、饿了么（API 受限，待政策明朗）

358 个测试，所有 8 个平台全部通过。CI 覆盖 Python 3.11/3.12/3.13。

快速开始

安装

从 PyPI 安装（推荐）

bash

# 一次安装，包含所有 8 个平台
pip install mcp-cn-commerce

所有平台 server 都在包内，通过 MCP 客户端配置选择使用哪些。

从 GitHub Releases 下载

bash

# 下载最新 Release 的 .whl 文件安装
# https://github.com/TonyWang-hub/mcp-cn-commerce/releases/latest

# 或直接安装：
pip install https://github.com/TonyWang-hub/mcp-cn-commerce/releases/latest/download/mcp_cn_commerce-0.1.0-py3-none-any.whl

从 Git 安装（始终最新）

bash

pip install git+https://github.com/TonyWang-hub/mcp-cn-commerce.git

开发模式

bash

git clone https://github.com/TonyWang-hub/mcp-cn-commerce.git
cd mcp-cn-commerce
pip install -e ".[dev]"

配置凭证

bash

# 巨量引擎 / 千川
export OCEANENGINE_APP_KEY="你的 App Key"
export OCEANENGINE_APP_SECRET="你的 App Secret"
export OCEANENGINE_ACCESS_TOKEN="你的 Access Token"

# 抖店
export DOUDIAN_APP_KEY="你的 App Key"
export DOUDIAN_APP_SECRET="你的 App Secret"
export DOUDIAN_SHOP_ID="你的店铺 ID"
export DOUDIAN_ACCESS_TOKEN="你的 Access Token"

# 京东
export JD_APP_KEY="你的 App Key"
export JD_APP_SECRET="你的 App Secret"
export JD_ACCESS_TOKEN="你的 Access Token"

接入 AI Agent

本项目是标准 stdio MCP server，所有支持 MCP 协议的客户端都能直接接入。下面给出主流客户端的配置方式（凭证可在 shell 里 export，也可写进客户端配置的 env 段，两种都行）。

Claude Desktop / Cherry Studio / Cline / Continue / Kimi Work（`mcpServers` JSON）

这类客户端用同一套 mcpServers 配置格式（Cline 写在 cline_mcp_settings.json，Claude Desktop 写在 claude_desktop_config.json）：

json

{
  "mcpServers": {
    "oceanengine": {
      "command": "mcp-cn-oceanengine",
      "env": {
        "OCEANENGINE_APP_KEY": "你的 App Key",
        "OCEANENGINE_APP_SECRET": "你的 App Secret",
        "OCEANENGINE_ACCESS_TOKEN": "你的 Access Token"
      }
    },
    "doudian": { "command": "mcp-cn-doudian" },
    "jd": { "command": "mcp-cn-jd" }
  }
}

Claude Code（CLI）

bash

claude mcp add oceanengine \
  --env OCEANENGINE_APP_KEY=你的Key \
  --env OCEANENGINE_APP_SECRET=你的Secret \
  --env OCEANENGINE_ACCESS_TOKEN=你的Token \
  -- mcp-cn-oceanengine

Codex（CLI）

bash

codex mcp add oceanengine -- mcp-cn-oceanengine

或写进 ~/.codex/config.toml：

toml

[mcp_servers.oceanengine]
command = "mcp-cn-oceanengine"
env = { OCEANENGINE_APP_KEY = "你的Key", OCEANENGINE_APP_SECRET = "你的Secret", OCEANENGINE_ACCESS_TOKEN = "你的Token" }

OpenCode / MiMo Code（`mcp` 段）

这两者（MiMo Code 是 OpenCode 的 fork）用 mcp 配置格式：

json

{
  "mcp": {
    "oceanengine": {
      "type": "local",
      "command": ["mcp-cn-oceanengine"],
      "enabled": true,
      "environment": {
        "OCEANENGINE_APP_KEY": "你的Key",
        "OCEANENGINE_APP_SECRET": "你的Secret",
        "OCEANENGINE_ACCESS_TOKEN": "你的Token"
      }
    }
  }
}

MiMo Code 还能直接从 Claude Code 自动导入已配置的 MCP server，无需重复配置。

其余平台 server 命令同理：mcp-cn-doudian、mcp-cn-jd、mcp-cn-taobao、mcp-cn-pinduoduo、mcp-cn-kuaishou、mcp-cn-xiaohongshu、mcp-cn-weixin-store。按需添加，凭证见上方配置凭证。

AI Agent 使用示例

配置完成后，你可以用自然语言问 AI Agent：

"帮我看看本周巨量引擎消耗最高的三个广告计划" "抖店哪些商品库存低于 10 件？" "京东待处理的退款单有哪些？" "对比巨量引擎上个月和这个月的 ROAS 趋势" "导出今天所有平台的订单汇总"

工作流模板 🆕

开箱即用的 AI 工作流模板，无需 API 凭证即可体验。模拟数据格式与真实 API 完全一致。

模板	用途	适用角色	Demo
电商日报	多平台 GMV/订单/退款汇总	运营/老板	查看 Demo
差评预警	差评监控 + 原因分析	客服/品控	查看 Demo
客服分类	退款原因分析 + 趋势	客服主管	查看 Demo
选品分析	品类热度 + 竞品价格	选品经理	示例数据
达人匹配	KOL 匹配 + ROI 预估	投放优化师	示例数据

📊 日报预览

code

┌────────┬──────────────┬──────────────┬────────┐
│ 指标   │ 今日         │ 昨日         │ 环比   │
├────────┼──────────────┼──────────────┼────────┤
│ GMV    │ ¥86,965.00   │ ¥88,900.00   │ -2.2%  │
│ 订单量 │ 312          │ 309          │ +1.0%  │
│ 客单价 │ ¥278.73      │ ¥287.70      │ -3.1%  │
│ 退款率 │ 5.1%         │ 4.6%         │ +0.5pp │
└────────┴──────────────┴──────────────┴────────┘

平台对比
┌──────────────────────┬──────────────┬──────┬────────┐
│ 平台                 │ GMV          │ 订单 │ 退款率 │
├──────────────────────┼──────────────┼──────┼────────┤
│ 抖店                 │ ¥28,950.00   │ 156  │ 5.1%   │
│ 京东                 │ ¥45,670.00   │ 89   │ 3.4%   │
│ 小红书               │ ¥12,345.00   │ 67   │ 7.5% ⚠️│
└──────────────────────┴──────────────┴──────┴────────┘

⚠️ 异常预警：
🔴 小红书退款率 7.5% — 超过 5% 阈值
🔴 库存预警：「夏季新款男士短袖T恤 白色 XL」仅剩 32 件

🚨 差评预警预览

code

原因分布
  质量问题     ████████████████████  40%
  色差         ██████████           20%
  尺码不合适   ██████████           20%
  做工粗糙     ██████████           20%

逐条分析：
1. 「洗了一次就掉色」— 抖店 ⭐
   → 建议：联系买家道歉 + 检查同批次库存

2. 「鞋码偏小，穿着挤脚」— 拼多多 ⭐⭐
   → 建议：尺码表加注「建议拍大一码」

3. 「颜色跟图片差太多」— 小红书 ⭐⭐
   → 建议：重新拍摄商品图

全部模板：templates/ | 接入文档：docs/template-guide.md

工具汇总

Server	工具数	覆盖类别
oceanengine	22	广告、千川、星图、素材、人群、优化
doudian	24	订单、商品、售后、物流、评价、直播、流量、营销、资金、店铺
jd	19	订单、商品、售后、物流、评价、价格、库存、营销、店铺
taobao	17	订单、商品、售后、物流、评价、店铺、营销、类目
pinduoduo	17	订单、商品、售后、物流、评价、店铺、营销、多多客
kuaishou	16	订单、商品、售后、物流、评价、店铺、营销
xiaohongshu	17	订单、商品、售后、物流、评价、店铺、营销、库存、财务
weixin_store	15	订单、商品、售后、物流、店铺、营销、供货、类目
合计	147	平台工具 + 每个 server 额外 4 个通用运维工具

每个 server 还额外暴露 4 个跨平台运维工具（已计入上表）：get_metrics（各接口延迟/成功/错误统计）、 get_traces（最近请求链路）、get_alerts（按实时指标评估告警规则）、export_data（导出记录为 CSV/JSON）。请求链路追踪与指标在每次调用时自动采集。

每个工具的具体用法见各 servers/<平台>/server.py 源码。

架构

code

mcp-cn-commerce/
├── .github/workflows/test.yml       # CI: push 自动跑 pytest
├── shared/                           # 共享基类：签名/请求/分页
│   └── cn_commerce_base.py           # 继承此基类即可新建平台
├── servers/                          # 所有平台 server（单一包，按需启动）
│   ├── oceanengine/server.py         ├── doudian/server.py
│   ├── jd/server.py                  ├── taobao/server.py
│   ├── pinduoduo/server.py           ├── kuaishou/server.py
│   ├── xiaohongshu/server.py         └── weixin_store/server.py
├── docs/platforms.md                 # 8 平台 API 对比 & 认证方式矩阵
├── README.md / README_en.md          # 简体中文 / English
└── LICENSE                           # MIT

单一包架构：pip install mcp-cn-commerce 一次安装，8 个平台 server 都在包内，通过 MCP 客户端配置选择使用哪些。

安全

本项目处理敏感的电商 API 凭证，安全保障：

🔒 本地运行 — API 密钥和凭证存在你的电脑上，不经过任何服务器
📖 代码开源 — 每一行代码都可审计
👁️ 默认只读 — 全部平台工具只读数据，零写入/修改/删除操作
📡 无数据收集 — 不收集、不追踪、不上传任何使用数据
🖥️ 直连平台 API — 代码直接调用平台 API，无中间服务器或代理
🔑 环境变量配置 — 凭证通过环境变量加载，绝不硬编码

常见问题

问：为什么不做内容发布（发视频/发笔记）？ 答：内容发布（抖音发视频、小红书发笔记）已经有 HuiMei/Astron 等优秀项目覆盖了，没必要重复。商家经营数据（广告报表、订单、售后）才是 MCP 生态的空白地带。

问：需要企业资质吗？ 答：部分平台需要：抖店需要企业/个体户资质，京东需要企业资质。拼多多个人可接入。详见 docs/platforms.md。

问：MCP 和 CLI 哪个更好？ 答：MCP 给 AI Agent 用（结构化 tool call，让 AI 自动分析），CLI 给人用（终端直接调，快速查数据）。Phase 2 会加 CLI 入口，共享同一套核心逻辑。

问：会支持闲鱼/美团/饿了么吗？ 答：在 Phase 4 计划中。这些平台的 API 在 2025 年大幅收紧（ISV 白名单制），等政策明朗后再接入。

问：和 MCP 官方 Python SDK 的关系？ 答：基于官方 MCP Python SDK 构建，遵循 MCP 协议标准。

问：支持哪些 AI Client？ 答：所有支持 MCP 协议的客户端：Claude Desktop、Cherry Studio、Kimi Work、Cline、Continue 等。

💼 Pro 版（内测招募中）

开源版永久免费、功能完整（单店铺 + 手动管理 token）。如果你是代运营公司 / 电商 SaaS / 多店铺商家，Pro 版解决两个开源版没有的问题：

能力	开源版	Pro 版
8 平台只读数据工具（147 个）	✅	✅
Access Token 管理	手动获取、过期手动换	自动刷新（过期前自动续约，巨量引擎 24h 过期不再是问题）
OAuth 授权	自己去开放平台抓 token	`auth` 向导：本地一条命令走完授权流程
店铺数量	单店铺（一进程一套凭证）	多店铺：`shops.yaml` 统一管理，按别名路由，跨店聚合
数据流向	全部本地	同样全部本地（无任何上报，license 离线校验）
支持	GitHub Issues	优先支持

🎯 正在招募首批种子用户：免费使用 Pro 内测版，换取你的真实场景反馈。特别欢迎管理多个店铺的代运营 TP / ISV。 👉 提交 Pro 咨询

Pro 版闭源、私有分发（GitHub Release + 专属 token 安装），首期覆盖巨量引擎 / 抖店 / 京东的 token 自动刷新，其余平台按用户反馈排期。

路线图

Phase 1 — 基础 ✅

巨量引擎: 广告报表/计划读取
巨量千川: 电商广告（共用巨量引擎认证）
抖店: 订单/商品/售后读取
京东: 订单/商品/店铺读取

Phase 2 — 主力扩展 ✅

淘宝: 完整 Top API — 订单/商品/物流
拼多多: 订单/商品/推广工具

Phase 3 — 长尾覆盖 ✅

快手: 订单/商品/物流
小红书: 订单/商品/库存
微信小店: 订单/商品/售后

Phase 4 — 探索 ⬜

闲鱼、美团、饿了么（等 API 政策）

引用

如果在研究或项目中使用 mcp-cn-commerce：

bibtex

@software{mcp-cn-commerce,
  title = {mcp-cn-commerce: MCP Servers for Chinese E-Commerce Platforms},
  year = {2026},
  url = {https://github.com/TonyWang-hub/mcp-cn-commerce}
}

许可证

MIT — 详见 LICENSE。

mcp-name: io.github.TonyWang-hub/mcp-cn-commerce

Install

Configuration

Environment variables

OCEANENGINE_APP_KEYsecret

Ocean Engine open platform App Key (only needed for the oceanengine server)

OCEANENGINE_APP_SECRETsecret

Ocean Engine open platform App Secret

OCEANENGINE_ACCESS_TOKENsecret

Ocean Engine OAuth access token

DOUDIAN_APP_KEYsecret

Douyin Shop App Key (only needed for the doudian server)

DOUDIAN_APP_SECRETsecret

Douyin Shop App Secret

DOUDIAN_SHOP_ID

Douyin Shop ID

DOUDIAN_ACCESS_TOKENsecret

Douyin Shop OAuth access token

JD_APP_KEYsecret

JD open platform App Key (only needed for the jd server)

JD_APP_SECRETsecret

JD open platform App Secret

JD_ACCESS_TOKENsecret

JD OAuth access token

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-cn-commerce": {
      "command": "uvx",
      "args": [
        "mcp-cn-commerce"
      ],
      "env": {
        "OCEANENGINE_APP_KEY": "<YOUR_OCEANENGINE_APP_KEY>",
        "OCEANENGINE_APP_SECRET": "<YOUR_OCEANENGINE_APP_SECRET>",
        "OCEANENGINE_ACCESS_TOKEN": "<YOUR_OCEANENGINE_ACCESS_TOKEN>",
        "DOUDIAN_APP_KEY": "<YOUR_DOUDIAN_APP_KEY>",
        "DOUDIAN_APP_SECRET": "<YOUR_DOUDIAN_APP_SECRET>",
        "DOUDIAN_SHOP_ID": "<YOUR_DOUDIAN_SHOP_ID>",
        "DOUDIAN_ACCESS_TOKEN": "<YOUR_DOUDIAN_ACCESS_TOKEN>",
        "JD_APP_KEY": "<YOUR_JD_APP_KEY>",
        "JD_APP_SECRET": "<YOUR_JD_APP_SECRET>",
        "JD_ACCESS_TOKEN": "<YOUR_JD_ACCESS_TOKEN>"
      }
    }
  }
}

io.github.TonyWang-hub/mcp-cn-commerce

Topics

mcp-cn-commerce — 中国电商平台 MCP Server

目录

这是什么？

为什么选择这个项目？

平台覆盖

快速开始

安装

从 PyPI 安装（推荐）

从 GitHub Releases 下载

从 Git 安装（始终最新）

开发模式

配置凭证

接入 AI Agent

Claude Desktop / Cherry Studio / Cline / Continue / Kimi Work（`mcpServers` JSON）

Claude Code（CLI）

Codex（CLI）

OpenCode / MiMo Code（`mcp` 段）

AI Agent 使用示例

工作流模板 🆕

📊 日报预览

🚨 差评预警预览

工具汇总

架构

安全

常见问题

💼 Pro 版（内测招募中）

路线图

Phase 1 — 基础 ✅

Phase 2 — 主力扩展 ✅

Phase 3 — 长尾覆盖 ✅

Phase 4 — 探索 ⬜

相关资源

引用

许可证

Install

Configuration

Topics

mcp-cn-commerce — 中国电商平台 MCP Server

目录

这是什么？

为什么选择这个项目？

平台覆盖

快速开始

安装

从 PyPI 安装（推荐）

从 GitHub Releases 下载

从 Git 安装（始终最新）

开发模式

配置凭证

接入 AI Agent

Claude Desktop / Cherry Studio / Cline / Continue / Kimi Work（mcpServers JSON）

Claude Code（CLI）

Codex（CLI）

OpenCode / MiMo Code（mcp 段）

AI Agent 使用示例

工作流模板 🆕

📊 日报预览

🚨 差评预警预览

工具汇总

架构

安全

常见问题

💼 Pro 版（内测招募中）

路线图

Phase 1 — 基础 ✅

Phase 2 — 主力扩展 ✅

Phase 3 — 长尾覆盖 ✅

Phase 4 — 探索 ⬜

相关资源

引用

许可证

Install

Configuration

Claude Desktop / Cherry Studio / Cline / Continue / Kimi Work（`mcpServers` JSON）

OpenCode / MiMo Code（`mcp` 段）