TonyWang-hub/mcp-cn-commerce

> 🛒 **让 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 范围 | 剩余边界（均未真店验收） | 官方入口 |
|---|---|---|---|
| 巨量引擎 / 千川 | 广告主信息、账户余额 | 广告报表迁移与授权账户树；无现成 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 为例，在项目虚拟环境安装：
从源码安装时，先确认仓库中存在 v0.1.6 tag（验证命令成功），再检出该 tag：
开发者可在同一项目虚拟环境中使用可编辑安装：
安装会写入项目的 .venv，不默认修改全局 Python。MCP 桌面客户端的 command 应填写该项目 .venv/bin/ 下命令的绝对路径；只在终端激活环境不保证桌面应用能找到它。其他操作系统使用对应的虚拟环境解释器/启动脚本路径。实际可安装制品和对应源码提交，以 v0.1.6 GitHub Release、PyPI 0.1.6 及发布准备记录为准。
配置凭证
接入 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）：
Claude Code（CLI）
Codex（CLI）
或写进 ~/.codex/config.toml：
OpenCode / MiMo Code（mcp 段）
这两者（MiMo Code 是 OpenCode 的 fork）用 mcp 配置格式：
> 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。按需添加，凭证见上方配置凭证。