mcp-cn-commerce

mcp-cn-commerce — 中国ECプラットフォーム向け MCP Server

🛒 AI エージェントが中国のECプラットフォームの店舗運営データを直接読み取れるようにします。 コンテンツ投稿は行わず、運営データ専用の MCP コネクターです。

中国のEC事業者の運営シーン向けに設計された、オープンソースの MCP Server スイートです。stdio MCP に対応したクライアントから接続できます。

検索キーワード：MCP Server、Model Context Protocol、EC MCP、AI エージェント、ECデータ、抖店 MCP、京東 MCP、巨量引擎 MCP、淘宝 MCP、拼多多 MCP、Python MCP、MCP 中国EC、店舗運営データ、EC運営分析、AI EC、Claude MCP

English | 簡体字中国語

Core 0.1.6 バージョンノート：実際に利用可能な成果物と対応するソースコードのコミットについては、v0.1.6 GitHub Release、PyPI 0.1.6 およびリリース準備記録の情報を参照してください。本バージョンでは各 SDK の live_verified はすべて false です。実店舗での受け入れ確認と管理画面との照合は完了していません。

プロジェクトと相談の進捗 · エンジニアリング／リリースの証拠 · 変更履歴

---

目次

• これは何ですか？
• このプロジェクトを選ぶ理由
• プラットフォーム対応状況
• クイックスタート
• ツールリファレンス
• アーキテクチャ
• セキュリティ
• 使用例 — 使用例とシナリオ
• よくある質問
• コントリビューション
• ロードマップ

---

これは何ですか？

AI エージェントが中国のECプラットフォームの店舗運営データに構造化された方法でアクセスできるようにする、MCP (Model Context Protocol) Server スイート（Monorepo）です。各プラットフォームは独立した MCP Server として、必要に応じてインストールして利用できます。

• 抖店、淘宝 — 注文およびアフターサービスの読み取り専用契約を確認済みです。実店舗のサンプル照合を優先しています。
• 京東 — 注文、店舗、アフターサービスに関する2つの専用照会を確認済みです。返品・返金の完全な収集にはまだ不足があります。
• 快手、小紅書、微信小店 — 注文／アフターサービスの一部読み取り操作を確認済みです。事業者の紐付け、収集範囲、実際の認可はそれぞれ個別に検証します。
• 巨量引擎 / 巨量千川 — 現在の SDK では広告主情報とアカウント残高を確認済みです。広告レポートと認可済みアカウントツリーは引き続き補完が必要です。
• 拼多多 — プラットフォームのエントリーポイントは残していますが、完全な公式業務スキーマを入手できていないため、運営 SDK による照会は無効化しています。その他の過去の MCP エントリーポイントは、確認済みの対応範囲には含まれません。

これは8つの MCP プラットフォームエントリーポイントと、登録済みツール155個を収録したカタログです。過去の互換用エントリーポイントと、明示的に非対応のエントリーポイントも含まれます。登録数は、確認済みの契約数や実店舗で利用可能な数を示すものではありません。現在の SDK の対応範囲は操作別の機能表を参照してください。有赞は SDK のみで接続できます。

すべてのツールはデフォルトで読み取り専用です。AI エージェントは運営データを分析できますが、内容を変更することはできません。

このプロジェクトを選ぶ理由

本プロジェクトは、事業者から認可を受けた運営データに焦点を当て、プラットフォームへの対応、読み取り専用の照会、決定的な日次レポートの集計を提供します。

• プラットフォームごとに独立した stdio サービスを提供し、店舗がすでに保有する認可情報を設定して利用します。
• 接続プール、レート制限、リトライ、メトリクス、機密情報のマスキングを共有します。
• 金額と時刻の処理を統一し、日次レポートではデータの欠落やページネーションの未完了を明示します。

プラットフォームの公開 API、プラットフォーム公式 MCP、本プロジェクトのサードパーティ MCP アダプターは、それぞれ異なるレイヤーです。詳細は公式アクセスの確認状況を参照してください。

現在、検証を手配できるシナリオ：

• アプリに必要な権限がある場合、確認済みの注文／アフターサービス API を読み取り、店舗の管理画面のサンプルと照合します。
• ページネーションと正規化が完了したレコードから、決定的な日次レポートを生成し、不明な金額とデータのカバー範囲の制限を明示します。
• まずシミュレーション用テンプレートで分析形式を確認し、その後、操作契約に基づいて実際の読み取り専用検証を手配します。広告 ROAS、在庫、レビューなどのテンプレートは、対応するデータソースが利用可能であることを証明するものではありません。

平台覆盖

平台	当前已核 SDK 范围	剩余边界（均未真店验收）	官方入口
巨量引擎 / 千川	广告主信息、账户余额	广告报表迁移与授权账户树；无现成 Pro 广告 provider 承诺	巨量开放平台
抖店	订单列表/详情、售后列表/详情	通用店铺信息不支持；支付优惠、实际退款和 90 天创建范围需后台核对	抖店开放平台
京东	订单列表/详情、店铺、售后列表/退款详情	售后专项不是全部退款；通用退款及退款 Source 未开放	京东零售开放平台
淘宝	订单列表/增量/详情、退款列表/详情	店铺信息仅 transport-only；应用字段权限与 payment 历史口径需核对	淘宝开放平台
拼多多	暂无可调用的经营 SDK 操作	官方完整业务 schema 待取得，经营 SDK 读操作明确不支持	拼多多开放平台
快手	订单/退款列表及详情、店铺	Pro 授权 open_id 与店铺主体绑定仍缺证据	快手电商开放平台
小红书	订单/售后列表及详情	Source 所需订单查询时间与退款完成时间单位未闭合	小红书开放平台
微信小店	订单/售后列表及详情、店铺	实际应用权限与游标终页需 live；Pro 同组件跨 tenant 委托另有缺口	微信开发文档

本表是 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.6
cd mcp-cn-commerce-0.1.6
python3.12 -m venv .venv
source .venv/bin/activate
python -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.git
cd mcp-cn-commerce
set -e
git rev-parse --verify 'refs/tags/v0.1.6^{commit}' >/dev/null
git checkout --detach v0.1.6
python3.12 -m venv .venv
source .venv/bin/activate
python -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 凭证即可体验。以下预览均使用模拟数据，不证明真实平台数据源已接通。示例数据遵循日报输入契约；原始平台返回需先完成分页、字段归一化和完整性声明。

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

📊 日报预览

┌────────┬──────────────┬──────────────┬────────┐
│ 指标   │ 今日         │ 昨日         │ 环比   │
├────────┼──────────────┼──────────────┼────────┤
│ 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	工具数	覆盖类别
oceanengine	23	广告、千川、星图、素材、人群、优化
doudian	25	订单、商品、售后、物流、评价、直播、流量、营销、资金、店铺
jd	20	订单、商品、售后、物流、评价、价格、库存、营销、店铺
taobao	18	订单、商品、售后、物流、评价、店铺、营销、类目
pinduoduo	18	订单、商品、售后、物流、评价、店铺、营销、多多客
kuaishou	17	订单、商品、售后、物流、评价、店铺、营销
xiaohongshu	18	订单、商品、售后、物流、评价、店铺、营销、库存、财务
weixin_store	16	订单、商品、售后、物流、店铺、营销、供货、类目
合计	155	平台工具 + 每个 server 5 个公共工具（运维、导出、日报）

每个 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 版
平台入口	8 个 MCP 平台、155 个注册工具；范围见能力表	复用 Core SDK；不等于开放全部历史 MCP 工具
Access Token 管理	通常由调用方管理；微信有显式本店 managed 模式	已实现相应 provider 的授权与刷新，按平台/应用模式确认；均待真实生命周期验收
OAuth 授权	调用方取得获准应用与店铺凭证	已登记且获平台允许的 loopback 可用 auth；HTTPS 回调需合作方 begin/complete 接入
店铺数量	MCP 一进程一套凭证；SDK 由宿主管理多个快照	私有配置与加密数据库管理应用、grant、店铺 ACL；同/跨平台聚合按采集能力确认
归一化与多店日报计算	已公开；可传入多店数据生成确定性日报、去重并标记未知金额/覆盖限制	复用公开计算能力，增加持久数据仓库和报告历史
持续采集与治理	宿主组织分页、授权生命周期、存储和访问控制	租户/店铺权限、持久分页证明、断点恢复、调度、审计；按已实现 Source 验证
数据流向	本地运行，向获准平台发起查询并向 MCP 客户端返回数据	由部署方管理；远程合作方 API、平台请求及显式配置通知按实际部署发生，license 离线校验
支持	GitHub Issues	内测场景反馈与交付方支持

🎯 正在招募首批种子用户：免费使用 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