{
  "markdown": "# mcp-cn-commerce — 中国电商平台 MCP Server\n\n[![Test](https://github.com/TonyWang-hub/mcp-cn-commerce/actions/workflows/test.yml/badge.svg)](https://github.com/TonyWang-hub/mcp-cn-commerce/actions/workflows/test.yml)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![MCP](https://img.shields.io/badge/Model_Context_Protocol-MCP-blueviolet)](https://modelcontextprotocol.io/)\n[![PyPI version](https://img.shields.io/pypi/v/mcp-cn-commerce)](https://pypi.org/project/mcp-cn-commerce/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n> 🛒 **让 AI Agent 直接读取中国电商平台的商家经营数据。** 不做内容发布，只做**经营数据**的 MCP 连接器。\n>\n> 国内首个面向中国电商商家经营场景的开源 MCP Server 套件。支持 Claude、ChatGPT、Gemini 等 AI Agent 接入。\n>\n> **搜索关键词**: MCP Server, Model Context Protocol, 电商 MCP, AI Agent, 电商数据, 抖店 MCP, 京东 MCP, 巨量引擎 MCP, 淘宝 MCP, 拼多多 MCP, Python MCP, MCP 中国电商, 商家经营数据, 电商经营分析, AI 电商, Claude MCP\n\n[English](README_en.md) | **简体中文**\n\n---\n\n## 目录\n\n- [这是什么？](#这是什么)\n- [为什么选择这个项目？](#为什么选择这个项目)\n- [平台覆盖](#平台覆盖)\n- [快速开始](#快速开始)\n- [工具参考](#每个-server-的工具)\n- [架构](#架构)\n- [安全](#安全)\n- [使用示例](docs/examples.md) — 使用示例和场景\n- [常见问题](#常见问题)\n- [参与贡献](CONTRIBUTING.md)\n- [路线图](#路线图)\n\n---\n\n## 这是什么？\n\n一个 **MCP (Model Context Protocol) Server 套件**（Monorepo），让 AI Agent 能够结构化地访问中国电商平台的商家经营数据。每个平台是一个独立的 MCP Server，按需安装使用：\n\n- **巨量引擎 / 巨量千川** — 广告投放数据（广告计划、报表、账户余额）\n- **抖店** — TikTok 电商店铺经营数据（订单、商品、售后、退款）\n- **京东** — 京东商家后台数据（订单、商品、店铺信息）\n- **淘宝 / 拼多多** — 订单、商品、物流\n- **快手 / 小红书 / 微信小店** — 订单、商品、库存\n\n所有工具**默认只读** — AI Agent 可以分析你的经营数据，但无法修改任何内容。\n\n## 为什么选择这个项目？\n\n国内已有的 MCP Server 全是**内容发布**（发视频、搜热搜），没有一个是**商家经营**（拉广告数据、看订单、管售后）。\n\n| | 内容侧 MCP（HuiMei/Astron 等） | mcp-cn-commerce |\n|---|---|---|\n| **做什么** | 发视频、搜热点 | 拉广告报表、查订单 |\n| **目标用户** | 自媒体/创作者 | **电商老板/运营/数据分析师** |\n| **数据类型** | 内容数据（播放量、点赞、热搜） | **经营数据**（收入、订单、退款、ROAS） |\n| **覆盖平台** | 内容平台 | 电商+广告平台 |\n| **操作** | 发布/写入 | 只读分析 & 监控 |\n\n**这是国内首个面向电商商家经营场景的开源 MCP Server 套件。**\n\n**典型使用场景**：\n- AI Agent 每日自动拉取广告 ROAS 和消耗，生成投放优化建议\n- 多平台订单数据汇总，用自然语言提问即可分析\n- 库存预警：AI 监控商品库存，低库存自动提醒\n- 售后分析：定期拉取退款数据，发现商品质量问题趋势\n\n## 平台覆盖\n\n| 平台 | 类型 | Phase | 状态 | 测试 | 开放平台 |\n|---|---|---|---|---|---|\n| 巨量引擎 (Ocean Engine) | 广告投放 | 1 | ✅ | 24 | [open.oceanengine.com](https://open.oceanengine.com) |\n| 巨量千川 (Qianchuan) | 电商广告 | 1 | ✅ | (同上) | [qianchuan.jinritemai.com](https://qianchuan.jinritemai.com) |\n| 抖店 (Douyin Shop) | 电商店铺 | 1 | ✅ | 31 | [op.jinritemai.com](https://op.jinritemai.com) |\n| 京东 (JD.com) | 电商店铺 | 1 | ✅ | 19 | [jos.jd.com](https://jos.jd.com) |\n| 淘宝 (Taobao) | 电商店铺 | 2 | ✅ | 36 | [open.taobao.com](https://open.taobao.com) |\n| 拼多多 (Pinduoduo) | 电商店铺 | 2 | ✅ | 30 | [open.pinduoduo.com](https://open.pinduoduo.com) |\n| 快手 (Kuaishou) | 电商店铺 | 3 | ✅ | 33 | [open.kuaixiaodian.com](https://open.kuaixiaodian.com) |\n| 小红书 (Xiaohongshu) | 电商店铺 | 3 | ✅ | 33 | [open.xiaohongshu.com](https://open.xiaohongshu.com) |\n| 微信小店 (WeChat Store) | 电商店铺 | 3 | ✅ | 25 | [developers.weixin.qq.com](https://developers.weixin.qq.com) |\n\n> Phase 4: 闲鱼、美团、饿了么（API 受限，待政策明朗）\n>\n> **358 个测试**，所有 8 个平台全部通过。CI 覆盖 Python 3.11/3.12/3.13。\n\n## 快速开始\n\n### 安装\n\n#### 从 PyPI 安装（推荐）\n\n```bash\n# 一次安装，包含所有 8 个平台\npip install mcp-cn-commerce\n```\n\n所有平台 server 都在包内，通过 MCP 客户端配置选择使用哪些。\n\n#### 从 GitHub Releases 下载\n\n```bash\n# 下载最新 Release 的 .whl 文件安装\n# https://github.com/TonyWang-hub/mcp-cn-commerce/releases/latest\n\n# 或直接安装：\npip install https://github.com/TonyWang-hub/mcp-cn-commerce/releases/latest/download/mcp_cn_commerce-0.1.0-py3-none-any.whl\n```\n\n#### 从 Git 安装（始终最新）\n\n```bash\npip install git+https://github.com/TonyWang-hub/mcp-cn-commerce.git\n```\n\n#### 开发模式\n\n```bash\ngit clone https://github.com/TonyWang-hub/mcp-cn-commerce.git\ncd mcp-cn-commerce\npip install -e \".[dev]\"\n```\n\n### 配置凭证\n\n```bash\n# 巨量引擎 / 千川\nexport OCEANENGINE_APP_KEY=\"你的 App Key\"\nexport OCEANENGINE_APP_SECRET=\"你的 App Secret\"\nexport OCEANENGINE_ACCESS_TOKEN=\"你的 Access Token\"\n\n# 抖店\nexport DOUDIAN_APP_KEY=\"你的 App Key\"\nexport DOUDIAN_APP_SECRET=\"你的 App Secret\"\nexport DOUDIAN_SHOP_ID=\"你的店铺 ID\"\nexport DOUDIAN_ACCESS_TOKEN=\"你的 Access Token\"\n\n# 京东\nexport JD_APP_KEY=\"你的 App Key\"\nexport JD_APP_SECRET=\"你的 App Secret\"\nexport JD_ACCESS_TOKEN=\"你的 Access Token\"\n```\n\n### 接入 AI Agent\n\n本项目是标准 stdio MCP server，所有支持 MCP 协议的客户端都能直接接入。下面给出主流客户端的配置方式（凭证可在 shell 里 `export`，也可写进客户端配置的 `env` 段，两种都行）。\n\n#### Claude Desktop / Cherry Studio / Cline / Continue / Kimi Work（`mcpServers` JSON）\n\n这类客户端用同一套 `mcpServers` 配置格式（Cline 写在 `cline_mcp_settings.json`，Claude Desktop 写在 `claude_desktop_config.json`）：\n\n```json\n{\n  \"mcpServers\": {\n    \"oceanengine\": {\n      \"command\": \"mcp-cn-oceanengine\",\n      \"env\": {\n        \"OCEANENGINE_APP_KEY\": \"你的 App Key\",\n        \"OCEANENGINE_APP_SECRET\": \"你的 App Secret\",\n        \"OCEANENGINE_ACCESS_TOKEN\": \"你的 Access Token\"\n      }\n    },\n    \"doudian\": { \"command\": \"mcp-cn-doudian\" },\n    \"jd\": { \"command\": \"mcp-cn-jd\" }\n  }\n}\n```\n\n#### Claude Code（CLI）\n\n```bash\nclaude mcp add oceanengine \\\n  --env OCEANENGINE_APP_KEY=你的Key \\\n  --env OCEANENGINE_APP_SECRET=你的Secret \\\n  --env OCEANENGINE_ACCESS_TOKEN=你的Token \\\n  -- mcp-cn-oceanengine\n```\n\n#### Codex（CLI）\n\n```bash\ncodex mcp add oceanengine -- mcp-cn-oceanengine\n```\n\n或写进 `~/.codex/config.toml`：\n\n```toml\n[mcp_servers.oceanengine]\ncommand = \"mcp-cn-oceanengine\"\nenv = { OCEANENGINE_APP_KEY = \"你的Key\", OCEANENGINE_APP_SECRET = \"你的Secret\", OCEANENGINE_ACCESS_TOKEN = \"你的Token\" }\n```\n\n#### OpenCode / MiMo Code（`mcp` 段）\n\n这两者（MiMo Code 是 OpenCode 的 fork）用 `mcp` 配置格式：\n\n```json\n{\n  \"mcp\": {\n    \"oceanengine\": {\n      \"type\": \"local\",\n      \"command\": [\"mcp-cn-oceanengine\"],\n      \"enabled\": true,\n      \"environment\": {\n        \"OCEANENGINE_APP_KEY\": \"你的Key\",\n        \"OCEANENGINE_APP_SECRET\": \"你的Secret\",\n        \"OCEANENGINE_ACCESS_TOKEN\": \"你的Token\"\n      }\n    }\n  }\n}\n```\n\n> MiMo Code 还能直接从 Claude Code 自动导入已配置的 MCP server，无需重复配置。\n\n> 其余平台 server 命令同理：`mcp-cn-doudian`、`mcp-cn-jd`、`mcp-cn-taobao`、`mcp-cn-pinduoduo`、`mcp-cn-kuaishou`、`mcp-cn-xiaohongshu`、`mcp-cn-weixin-store`。按需添加，凭证见上方[配置凭证](#配置凭证)。\n\n### AI Agent 使用示例\n\n配置完成后，你可以用自然语言问 AI Agent：\n\n> \"帮我看看本周巨量引擎消耗最高的三个广告计划\"\n> \"抖店哪些商品库存低于 10 件？\"\n> \"京东待处理的退款单有哪些？\"\n> \"对比巨量引擎上个月和这个月的 ROAS 趋势\"\n> \"导出今天所有平台的订单汇总\"\n\n## 工作流模板 🆕\n\n开箱即用的 AI 工作流模板，**无需 API 凭证即可体验**。模拟数据格式与真实 API 完全一致。\n\n| 模板 | 用途 | 适用角色 | Demo |\n|------|------|----------|------|\n| [电商日报](templates/daily-report/) | 多平台 GMV/订单/退款汇总 | 运营/老板 | [查看 Demo](templates/daily-report/demo-output.md) |\n| [差评预警](templates/bad-review-alert/) | 差评监控 + 原因分析 | 客服/品控 | [查看 Demo](templates/bad-review-alert/demo-output.md) |\n| [客服分类](templates/cs-classify/) | 退款原因分析 + 趋势 | 客服主管 | [查看 Demo](templates/cs-classify/demo-output.md) |\n| [选品分析](templates/product-select/) | 品类热度 + 竞品价格 | 选品经理 | [示例数据](templates/product-select/example-data.json) |\n| [达人匹配](templates/kol-match/) | KOL 匹配 + ROI 预估 | 投放优化师 | [示例数据](templates/kol-match/example-data.json) |\n\n### 📊 日报预览\n\n```\n┌────────┬──────────────┬──────────────┬────────┐\n│ 指标   │ 今日         │ 昨日         │ 环比   │\n├────────┼──────────────┼──────────────┼────────┤\n│ GMV    │ ¥86,965.00   │ ¥88,900.00   │ -2.2%  │\n│ 订单量 │ 312          │ 309          │ +1.0%  │\n│ 客单价 │ ¥278.73      │ ¥287.70      │ -3.1%  │\n│ 退款率 │ 5.1%         │ 4.6%         │ +0.5pp │\n└────────┴──────────────┴──────────────┴────────┘\n\n平台对比\n┌──────────────────────┬──────────────┬──────┬────────┐\n│ 平台                 │ GMV          │ 订单 │ 退款率 │\n├──────────────────────┼──────────────┼──────┼────────┤\n│ 抖店                 │ ¥28,950.00   │ 156  │ 5.1%   │\n│ 京东                 │ ¥45,670.00   │ 89   │ 3.4%   │\n│ 小红书               │ ¥12,345.00   │ 67   │ 7.5% ⚠️│\n└──────────────────────┴──────────────┴──────┴────────┘\n\n⚠️ 异常预警：\n🔴 小红书退款率 7.5% — 超过 5% 阈值\n🔴 库存预警：「夏季新款男士短袖T恤 白色 XL」仅剩 32 件\n```\n\n### 🚨 差评预警预览\n\n```\n原因分布\n  质量问题     ████████████████████  40%\n  色差         ██████████           20%\n  尺码不合适   ██████████           20%\n  做工粗糙     ██████████           20%\n\n逐条分析：\n1. 「洗了一次就掉色」— 抖店 ⭐\n   → 建议：联系买家道歉 + 检查同批次库存\n\n2. 「鞋码偏小，穿着挤脚」— 拼多多 ⭐⭐\n   → 建议：尺码表加注「建议拍大一码」\n\n3. 「颜色跟图片差太多」— 小红书 ⭐⭐\n   → 建议：重新拍摄商品图\n```\n\n全部模板：[`templates/`](templates/) | 接入文档：[`docs/template-guide.md`](docs/template-guide.md)\n\n## 工具汇总\n\n| Server | 工具数 | 覆盖类别 |\n|---|---|---|\n| oceanengine | 22 | 广告、千川、星图、素材、人群、优化 |\n| doudian | 24 | 订单、商品、售后、物流、评价、直播、流量、营销、资金、店铺 |\n| jd | 19 | 订单、商品、售后、物流、评价、价格、库存、营销、店铺 |\n| taobao | 17 | 订单、商品、售后、物流、评价、店铺、营销、类目 |\n| pinduoduo | 17 | 订单、商品、售后、物流、评价、店铺、营销、多多客 |\n| kuaishou | 16 | 订单、商品、售后、物流、评价、店铺、营销 |\n| xiaohongshu | 17 | 订单、商品、售后、物流、评价、店铺、营销、库存、财务 |\n| weixin_store | 15 | 订单、商品、售后、物流、店铺、营销、供货、类目 |\n| **合计** | **147** | 平台工具 + 每个 server 额外 4 个通用运维工具 |\n\n每个 server 还额外暴露 **4 个跨平台运维工具**（已计入上表）：`get_metrics`（各接口延迟/成功/错误统计）、\n`get_traces`（最近请求链路）、`get_alerts`（按实时指标评估告警规则）、`export_data`（导出记录为 CSV/JSON）。\n请求链路追踪与指标在每次调用时自动采集。\n\n每个工具的具体用法见各 `servers/<平台>/server.py` 源码。\n\n## 架构\n\n```\nmcp-cn-commerce/\n├── .github/workflows/test.yml       # CI: push 自动跑 pytest\n├── shared/                           # 共享基类：签名/请求/分页\n│   └── cn_commerce_base.py           # 继承此基类即可新建平台\n├── servers/                          # 所有平台 server（单一包，按需启动）\n│   ├── oceanengine/server.py         ├── doudian/server.py\n│   ├── jd/server.py                  ├── taobao/server.py\n│   ├── pinduoduo/server.py           ├── kuaishou/server.py\n│   ├── xiaohongshu/server.py         └── weixin_store/server.py\n├── docs/platforms.md                 # 8 平台 API 对比 & 认证方式矩阵\n├── README.md / README_en.md          # 简体中文 / English\n└── LICENSE                           # MIT\n```\n\n单一包架构：`pip install mcp-cn-commerce` 一次安装，8 个平台 server 都在包内，通过 MCP 客户端配置选择使用哪些。\n\n## 安全\n\n本项目处理敏感的电商 API 凭证，安全保障：\n\n- 🔒 **本地运行** — API 密钥和凭证存在你的电脑上，不经过任何服务器\n- 📖 **代码开源** — 每一行代码都可审计\n- 👁️ **默认只读** — 全部平台工具只读数据，零写入/修改/删除操作\n- 📡 **无数据收集** — 不收集、不追踪、不上传任何使用数据\n- 🖥️ **直连平台 API** — 代码直接调用平台 API，无中间服务器或代理\n- 🔑 **环境变量配置** — 凭证通过环境变量加载，绝不硬编码\n\n## 常见问题\n\n**问：为什么不做内容发布（发视频/发笔记）？**\n答：内容发布（抖音发视频、小红书发笔记）已经有 HuiMei/Astron 等优秀项目覆盖了，没必要重复。商家经营数据（广告报表、订单、售后）才是 MCP 生态的空白地带。\n\n**问：需要企业资质吗？**\n答：部分平台需要：抖店需要企业/个体户资质，京东需要企业资质。拼多多个人可接入。详见 [docs/platforms.md](docs/platforms.md)。\n\n**问：MCP 和 CLI 哪个更好？**\n答：MCP 给 AI Agent 用（结构化 tool call，让 AI 自动分析），CLI 给人用（终端直接调，快速查数据）。Phase 2 会加 CLI 入口，共享同一套核心逻辑。\n\n**问：会支持闲鱼/美团/饿了么吗？**\n答：在 Phase 4 计划中。这些平台的 API 在 2025 年大幅收紧（ISV 白名单制），等政策明朗后再接入。\n\n**问：和 MCP 官方 Python SDK 的关系？**\n答：基于官方 [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 构建，遵循 MCP 协议标准。\n\n**问：支持哪些 AI Client？**\n答：所有支持 MCP 协议的客户端：Claude Desktop、Cherry Studio、Kimi Work、Cline、Continue 等。\n\n## 💼 Pro 版（内测招募中）\n\n开源版永久免费、功能完整（单店铺 + 手动管理 token）。如果你是**代运营公司 / 电商 SaaS / 多店铺商家**，Pro 版解决两个开源版没有的问题：\n\n| 能力 | 开源版 | Pro 版 |\n|---|---|---|\n| 8 平台只读数据工具（147 个） | ✅ | ✅ |\n| Access Token 管理 | 手动获取、过期手动换 | **自动刷新**（过期前自动续约，巨量引擎 24h 过期不再是问题） |\n| OAuth 授权 | 自己去开放平台抓 token | **`auth` 向导**：本地一条命令走完授权流程 |\n| 店铺数量 | 单店铺（一进程一套凭证） | **多店铺**：`shops.yaml` 统一管理，按别名路由，跨店聚合 |\n| 数据流向 | 全部本地 | 同样全部本地（**无任何上报**，license 离线校验） |\n| 支持 | GitHub Issues | 优先支持 |\n\n> 🎯 **正在招募首批种子用户**：免费使用 Pro 内测版，换取你的真实场景反馈。\n> 特别欢迎管理多个店铺的代运营 TP / ISV。\n> 👉 [提交 Pro 咨询](https://github.com/TonyWang-hub/mcp-cn-commerce/issues/new?labels=pro-inquiry&title=%5BPro%5D%20%E5%92%A8%E8%AF%A2&body=%E8%AF%B7%E7%AE%80%E5%8D%95%E4%BB%8B%E7%BB%8D%EF%BC%9A%0A-%20%E4%BD%A0%E7%9A%84%E8%A7%92%E8%89%B2%EF%BC%88%E5%95%86%E5%AE%B6%2F%E4%BB%A3%E8%BF%90%E8%90%A5%2FISV%2F%E5%BC%80%E5%8F%91%E8%80%85%EF%BC%89%EF%BC%9A%0A-%20%E7%AE%A1%E7%90%86%E7%9A%84%E5%BA%97%E9%93%BA%E6%95%B0%E9%87%8F%E5%92%8C%E5%B9%B3%E5%8F%B0%EF%BC%9A%0A-%20%E6%9C%80%E6%83%B3%E8%A7%A3%E5%86%B3%E7%9A%84%E9%97%AE%E9%A2%98%EF%BC%9A)\n\nPro 版闭源、私有分发（GitHub Release + 专属 token 安装），首期覆盖**巨量引擎 / 抖店 / 京东**的 token 自动刷新，其余平台按用户反馈排期。\n\n## 路线图\n\n### Phase 1 — 基础 ✅\n- 巨量引擎: 广告报表/计划读取\n- 巨量千川: 电商广告（共用巨量引擎认证）\n- 抖店: 订单/商品/售后读取\n- 京东: 订单/商品/店铺读取\n\n### Phase 2 — 主力扩展 ✅\n- 淘宝: 完整 Top API — 订单/商品/物流\n- 拼多多: 订单/商品/推广工具\n\n### Phase 3 — 长尾覆盖 ✅\n- 快手: 订单/商品/物流\n- 小红书: 订单/商品/库存\n- 微信小店: 订单/商品/售后\n\n### Phase 4 — 探索 ⬜\n- 闲鱼、美团、饿了么（等 API 政策）\n\n## 相关资源\n\n- [Model Context Protocol (MCP) 官方文档](https://modelcontextprotocol.io/)\n- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)\n- [Claude Desktop — MCP 支持](https://claude.ai/download)\n- [Cherry Studio — 多模型 MCP 客户端](https://cherry-ai.com/)\n- [平台 API 对比文档](docs/platforms.md)\n\n## 引用\n\n如果在研究或项目中使用 mcp-cn-commerce：\n\n```bibtex\n@software{mcp-cn-commerce,\n  title = {mcp-cn-commerce: MCP Servers for Chinese E-Commerce Platforms},\n  year = {2026},\n  url = {https://github.com/TonyWang-hub/mcp-cn-commerce}\n}\n```\n\n## 许可证\n\nMIT — 详见 [LICENSE](LICENSE)。\n\n<!-- MCP Registry ownership marker, do not remove -->\nmcp-name: io.github.TonyWang-hub/mcp-cn-commerce\n",
  "bytes": 12556,
  "sha": "d68a4e5271f42bd149f1e4549f8079914d4e0db223149c653a48fafd50b9637d",
  "repo_slug": "tonywang-hub/mcp-cn-commerce",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tonywang_hub_mcp_cn_commerce_b230d38e/readme"
}