Mcp Cn Commerce

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

[Test] [Python] [License] [MCP] [PyPI version] [Code style: black]

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

面向中国电商商家经营场景的开源 MCP Server 套件。通过支持 stdio MCP 的客户端接入。

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

English | 简体中文

Core 0.1.6 版本说明：实际可用制品与对应源码提交，以 v0.1.6 GitHub Release、PyPI 0.1.6 和发布准备记录中的信息为准。本版本各 SDK 的 live_verified 均为 false；真实商家验收和后台对账未完成。

项目与咨询进展 · 工程/发布证据 · 更新记录

目录

• 这是什么？
• 为什么选择这个项目？
• 平台覆盖
• 快速开始
• 工具参考
• 架构
• 安全
• 使用示例 — 使用示例和场景
• 常见问题
• 参与贡献
• 路线图

这是什么？

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

• 抖店、淘宝 — 已核订单与售后只读合同，优先进行真店样本核对。
• 京东 — 已核订单、店铺和两项售后专项查询；完整退款采集仍有缺口。
• 快手、小红书、微信小店 — 已核部分订单/售后读操作；主体绑定、采集范围及真实授权分别验收。
• 巨量引擎 / 巨量千川 — 当前 SDK 已核广告主信息和账户余额；广告报表及授权账户树仍待补齐。
• 拼多多 — 已保留平台入口，经营 SDK 查询因完整官方业务 schema 未取得而关闭；其他历史 MCP 入口不属已核支持。

这是 8 个 MCP 平台入口、155 个已注册工具的目录，包含历史兼容及明确不支持的入口。注册数量不代表已核合同或真店可用数量；当前 SDK 范围见逐操作能力表，有赞另提供 SDK-only 接入。

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

为什么选择这个项目？

本项目聚焦商家已授权的经营数据，提供平台适配、只读查询和确定性日报汇总。

• 各平台独立 stdio 服务，按店铺已有授权配置。
• 共享连接池、限流、重试、指标与脱敏。
• 统一金额与时间处理；日报明确标记缺失数据和不完整分页。

平台开放 API、平台官方 MCP 与本项目的第三方 MCP 适配器是不同层次；详见官方接入核查。

当前可安排验证的场景：

• 在应用确有权限时读取已核订单/售后接口，并与店铺后台样本核对。
• 对已完成分页和归一化的记录生成确定性日报，明确金额未知与覆盖限制。
• 先用模拟模板确认分析形式，再按操作合同安排真实只读验收。广告 ROAS、库存和评价等模板不证明对应数据源已经可用。

平台覆盖

本表是 SDK 摘要，不将历史 MCP 商品、库存、物流等入口全部标为当前已核合同。工具注册、合同已读、SDK 可调用、真实店铺通过分别记录；所有 SDK live_verified 仍为 false。当前证据见平台说明、官方接入核查与候选验收状态。CI 配置覆盖 Python 3.11/3.12/3.13，实际结果绑定具体提交。

Core 为各平台业务工具的 MCP tools/list 描述提供 contract_status、supported 和 live_verified。supported=false 的操作在发送平台请求前拒绝；历史兼容工具保留调用入口，明确标为 unverified。supported=true 只表示保留了调用映射，实际权限、合同范围和真店验收仍需分别确认。五项共享工具保持原有用途和描述，155 个注册工具的名称及输入输出结构不变。

快速开始

安装

安装 Core 0.1.6

使用 Python 3.11+；以下以 Python 3.12 为例，在项目虚拟环境安装：

mkdir -p mcp-cn-commerce-0.1.6cd mcp-cn-commerce-0.1.6python3.12 -m venv .venvsource .venv/bin/activatepython -m pip install "mcp-cn-commerce==0.1.6"mcp-cn-commerce --version

从源码安装时，先确认仓库中存在 v0.1.6 tag（验证命令成功），再检出该 tag：

git clone https://github.com/TonyWang-hub/mcp-cn-commerce.gitcd mcp-cn-commerceset -egit rev-parse --verify 'refs/tags/v0.1.6^{commit}' >/dev/nullgit checkout --detach v0.1.6python3.12 -m venv .venvsource .venv/bin/activatepython -m pip install -c requirements-lock.txt .

开发者可在同一项目虚拟环境中使用可编辑安装：

python -m pip install -c requirements-lock.txt -e ".[dev]"

安装会写入项目的 .venv，不默认修改全局 Python。MCP 桌面客户端的 command 应填写该项目 .venv/bin/ 下命令的绝对路径；只在终端激活环境不保证桌面应用能找到它。其他操作系统使用对应的虚拟环境解释器/启动脚本路径。实际可安装制品和对应源码提交，以 v0.1.6 GitHub Release、PyPI 0.1.6 及发布准备记录为准。

配置凭证

# 巨量引擎 / 千川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 段，两种都行）。

将下方 /absolute/path/to/mcp-cn-commerce 替换为所选安装目录的绝对路径；安装稳定版时使用该版本目录。桌面客户端还需在自己的 env 配置中设置凭证；终端中的 export 仅对继承该环境的进程生效。

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

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

{  "mcpServers": {    "oceanengine": {      "command": "/absolute/path/to/mcp-cn-commerce/.venv/bin/mcp-cn-oceanengine",      "env": {        "OCEANENGINE_APP_KEY": "你的 App Key",        "OCEANENGINE_APP_SECRET": "你的 App Secret",        "OCEANENGINE_ACCESS_TOKEN": "你的 Access Token"      }    },    "doudian": { "command": "/absolute/path/to/mcp-cn-commerce/.venv/bin/mcp-cn-doudian" },    "jd": { "command": "/absolute/path/to/mcp-cn-commerce/.venv/bin/mcp-cn-jd" }  }}

Claude Code（CLI）

claude mcp add oceanengine \  --env OCEANENGINE_APP_KEY=你的Key \  --env OCEANENGINE_APP_SECRET=你的Secret \  --env OCEANENGINE_ACCESS_TOKEN=你的Token \  -- /absolute/path/to/mcp-cn-commerce/.venv/bin/mcp-cn-oceanengine

Codex（CLI）

codex mcp add oceanengine -- /absolute/path/to/mcp-cn-commerce/.venv/bin/mcp-cn-oceanengine

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

[mcp_servers.oceanengine]command = "/absolute/path/to/mcp-cn-commerce/.venv/bin/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 配置格式：

{  "mcp": {    "oceanengine": {      "type": "local",      "command": ["/absolute/path/to/mcp-cn-commerce/.venv/bin/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 工作流模板，无需 API 凭证即可体验。以下预览均使用模拟数据，不证明真实平台数据源已接通。示例数据遵循日报输入契约；原始平台返回需先完成分页、字段归一化和完整性声明。

📊 日报预览

┌────────┬──────────────┬──────────────┬────────┐│ 指标   │ 今日         │ 昨日         │ 环比   │├────────┼──────────────┼──────────────┼────────┤│ 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 件

🚨 差评预警预览

原因分布  质量问题     ████████████████████  40%  色差         ██████████           20%  尺码不合适   ██████████           20%  做工粗糙     ██████████           20%
逐条分析：1. 「洗了一次就掉色」— 抖店 ⭐   → 建议：联系买家道歉 + 检查同批次库存
2. 「鞋码偏小，穿着挤脚」— 拼多多 ⭐⭐   → 建议：尺码表加注「建议拍大一码」
3. 「颜色跟图片差太多」— 小红书 ⭐⭐   → 建议：重新拍摄商品图

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

工具汇总

此表统计注册入口及其目录类别，包含兼容和未核合同；可调用 SDK 范围另见能力表。

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

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

架构

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

单一包架构：Core 包含 8 个平台 server。按上方版本安装说明和逐操作能力表配置 MCP 客户端。

安全

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

• 🔒 本地运行 — 凭证由本地读取，必要的认证信息发送给对应平台 API
• 📖 代码开源 — 每一行代码都可审计
• 👁️ 默认只读 — 全部平台工具只读数据，零写入/修改/删除操作
• 📡 无数据收集 — 本项目不向自建服务上报使用数据；业务查询结果会返回你配置的 MCP/AI 客户端
• 🖥️ 直连平台 API — 代码直接调用平台 API，无中间服务器或代理
• 🔑 环境变量配置 — 凭证通过环境变量加载，绝不硬编码

常见问题

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

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

问：MCP 和 CLI 哪个更好？ 答：MCP 给 AI Agent 用（结构化 tool call，让 AI 自动分析），CLI 给人用（终端直接调，快速查数据）。CLI 提供启动和健康诊断；每个 stdio 连接启动一个平台，经营查询通过 MCP 工具完成。

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

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

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

💼 Pro 版（内测招募中）

开源版永久免费，MIT 许可和已经公开的能力保持不变：平台适配、显式凭证 SDK、金额/时间归一化，以及 build_daily_report 的多店确定性日报计算都属于 Core。多店算法无需 Pro；宿主需提供已采集记录和准确的完整性声明。代运营公司 / 电商 SaaS / 多店铺商家可参加 Pro 内测，验证授权治理和持续运行能力；平台范围按当前合同逐操作确认。

Pro 与 Core 分开维护、验证和发布，属于独立私有交付；Pro 的版本、能力和验收状态不由 Core 的版本或 CI 代表。Core 0.1.6 不包含 Pro 私有源码或制品。真实商家 live_verified 仍为 false，业务验收与后台对账尚未完成。

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

Pro 版闭源、私有交付。具体 provider、授权模式和采集范围以配套 Pro 文档与 capabilities 为准；当前不承诺巨量/千川自动续期或广告报表。旧 shops.yaml 不会自动导入当前配置。免费内测的许可安排由交付方确认，本地试用计时不替代上述免费内测承诺。

Core 安装不需要 Pro 或独立商业 Client。CI 在依赖安装前检查源码，在制品安装/公开上传前检查 wheel 和 sdist，防止意外混入私有代码或依赖。详见 Core / Pro 边界与检查。Pro 的源码改作、OEM/再分发、正式交付范围和支持安排另行书面确认，不因安装包存在自动授予。

路线图

已完成的工程阶段

• 8 个平台 MCP 入口、共享工具和显式凭证 SDK；工具目录包含历史兼容项。
• 抖店、TOP、京东、快手、小红书、微信等已核读合同迁移；具体操作见当前能力表。
• 按准确提交完成工程回归、安装和真实 MCP 传输检查，见验收状态。

当前稳定与验收

• 优先抖店/TOP 1–2 平台获准店铺的只读样本、分页、金额日期及授权生命周期核对。
• 补 PDD 业务 schema、XHS Source 时间合同、JD 两类退款资金覆盖，以及 Pro 已知主体/委托缺口。
• 商品、库存、物流、评价、营销、广告和账单等广泛数据域按合同逐项推进，不以历史 Phase 完成标记承诺全部当前可用。

Phase 4 — 探索 ⬜

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

相关资源

• Model Context Protocol (MCP) 官方文档
• MCP Python SDK
• Claude Desktop — MCP 支持
• Cherry Studio — 多模型 MCP 客户端
• 平台 API 对比文档

引用

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

@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