eshop-mcp

为 AI 助手提供淘宝/天猫生态结构化数据接口的 MCP Server

覆盖消费者视角（C 端搜索、商品详情、评论、问大家）和商家视角（万相台投放数据、达摩盘人群资产与竞品分析）

快速开始 • 功能特性 • 架构设计 • 使用文档

功能特性

🔐 登录认证

• 阿里妈妈统一登录：通过 CDP 打开 Chrome，引导用户完成 SSO 登录后自动提取万相台和达摩盘的 cookie
• 淘宝 C 端登录：独立的淘宝登录管理，支持与阿里妈妈使用不同账号

🛒 消费者视角工具

| 工具 | 描述 | |------|------| | tb_search | 淘宝关键词搜索，支持排序（综合/销量/价格）和价格筛选 | | tb_item_detail | 获取商品详情：标题、价格、主图、SKU、属性、描述图片 | | tb_item_reviews | 获取商品评论，支持好/中/差评和有图筛选，自动翻页（最多100条） | | tb_item_qa | 获取商品「问大家」数据，支持获取每个问题的全部回答（最多50条） |

📊 商家视角工具

万相台（WXT）

| 工具 | 描述 | |------|------| | get_wxt_overview | 拉取各场景汇总报表数据 | | get_wxt_plans | 拉取计划明细，支持按场景/日期/状态/商品 ID 列表筛选 |

达摩盘（DMP）

• 店铺管理：商品类目列表、商品筛选（按类目/关键词/生命周期）
• 商品洞察：生命周期分析、人群资产（OVITRW 六层）、成长诊断
• 竞争分析：竞品识别、人群流向分析、竞争力诊断
• 对比报表：关键经营指标、推广场景效果、人群结构对比

🐍 数据分析

• run_python_on_data：在 E2B 隔离沙箱中执行 Python 代码（预装 pandas/numpy/matplotlib 等）

快速开始

前置要求

• Node.js >= 18
• Google Chrome（登录功能需要）

通过 npx 使用

在 MCP 客户端配置中添加：

{
  "mcpServers": {
    "eshop": {
      "command": "npx",
      "args": ["-y", "eshop-mcp"]
    }
  }
}

如需配置环境变量：

{
  "mcpServers": {
    "eshop": {
      "command": "npx",
      "args": ["-y", "eshop-mcp"],
      "env": {
        "CDP_PORT": "9222",
        "CHROME_USER_DATA_DIR": "~/ChromeDebug",
        "TAOBAO_BACKEND": "cdp",
        "ESHOP_MCP_TRUNCATE": "false"
      }
    }
  }
}

配置

本地开发时可在项目根目录创建 .env 文件；通过 MCP 客户端使用 npx 时，推荐在客户端配置的 env 中设置：

# Chrome DevTools Protocol 端口
CDP_PORT=9222

# Chrome 用户数据目录
CHROME_USER_DATA_DIR=~/ChromeDebug

# 淘宝 C 端后端：cdp（默认）或 mtop
# CDP 模式会打开/复用一个淘宝数据工作页，不会在商品采集工具中主动打开登录页
# TAOBAO_BACKEND=mtop

# 数据存储目录
# ESHOP_MCP_DATA_DIR=~/.eshop-mcp

# 输出截断策略（默认 false 返回完整数据）
ESHOP_MCP_TRUNCATE=false

# E2B 沙箱 API Key（可选，仅 run_python_on_data 需要）
# E2B_API_KEY=your_api_key_here

本地开发

# 克隆项目
git clone https://cnb.cool/turingdistract/eshop-data-extract-mcp.git
cd eshop-data-extract-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式（热重载）
npm run dev

接入 Claude Desktop / Claude Code

如需使用本地构建产物而不是 npx：

{
  "mcpServers": {
    "eshop": {
      "command": "node",
      "args": ["/path/to/eshop-data-extract-mcp/dist/index.js"]
    }
  }
}

架构设计

eshop-mcp/
├── src/
│   ├── index.ts           # MCP Server 入口
│   ├── tools/             # MCP 工具定义
│   ├── taobao/            # 淘宝 C 端 API
│   │   └── api/           # MTOP API + CDP 后端
│   ├── wxt/               # 万相台 API
│   ├── dmp/               # 达摩盘 API
│   ├── cookie/            # Cookie 管理系统
│   └── e2b/               # Python 沙箱
├── dist/                  # 编译输出
└── tests/                 # 测试文件

技术栈

• Runtime: Node.js (ES2022, ESM)
• Language: TypeScript 5.0+
• MCP SDK: @modelcontextprotocol/sdk
• Validation: Zod
• Testing: Vitest
• Automation: Chrome DevTools Protocol (CDP)

使用文档

登录与 Cookie 管理

1. 启动 Chrome 调试模式（首次使用前手动启动）：

   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
     --remote-debugging-port=9222 \
     --user-data-dir=~/ChromeDebug

2. 执行登录：

   // 阿里妈妈登录（万相台/达摩盘）
   await alimama_login()
   
   // 淘宝 C 端登录（可使用不同账号）
   await tb_login()

3. Cookie 管理：

   • 买家/卖家账号分离管理
   • Cookie 通常可持续数天
   • 过期后重新调用对应登录工具即可
   • TAOBAO_BACKEND=cdp 时，商品采集工具只复用淘宝数据工作页；登录页或淘宝自身跳转只应出现在显式登录/刷新工具中

DMP 工具使用顺序

// 1. 获取商品列表（打爆路径）
dmp_boom_list_shop_items({ category_id: "xxx" })

// 2. 查看商品生命周期（打爆路径）
dmp_boom_get_item_info({ item_id: "123" })

// 3. 获取对标选项（单品洞察）
dmp_insight_get_benchmark_list({ item_id: "123" })

// 4. 诊断分析（单品洞察，使用 benchmark_id）
dmp_insight_get_grow_diagnose({
  item_id: "123",
  benchmark_id: "benchmark_123"
})

// 5. 成功品对比（打爆路径）
dmp_boom_compare_key_metrics({
  my_item_id: "123",
  comp_item_id: "456"
})

注意事项

⚠️ 反爬风险

• 高频调用可能触发滑块验证
• 建议控制调用频率
• 遇到验证时需在 Chrome 中手动完成

📁 数据存储

• 工具输出数据保存在 ~/.eshop-mcp/ 目录
• 按模块分目录（taobao/、wxt/、dmp/）
• ESHOP_MCP_TRUNCATE=true 时截断输出并保存完整数据

🔒 隐私与安全

• Cookie 数据仅存储在本地
• 不会上传到任何远程服务器
• 请妥善保管 .env 文件中的敏感信息

开发指南

运行测试

# 单元测试
npm test

# 集成测试
npm run test:integration

# 测试监视模式
npm run test:watch

项目脚本

| 命令 | 描述 | |------|------| | npm run build | 编译 TypeScript | | npm run dev | 开发模式（热重载） | | npm start | 运行编译后的服务器 | | npm test | 运行单元测试 | | npm run test:integration | 运行集成测试 |

发布到 npm

本仓库包含 CNB 发布流水线：

• main 分支 push 和 PR 会执行安装、构建、测试、npm pack --dry-run
• 推送 tag 时会执行 npm publish --access public

发布前需要在 CNB 仓库密钥中配置 NPM_TOKEN。发布版本时先更新 package.json 的 version，再推送 tag：

npm version patch
git push --follow-tags

贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

相关链接

• MCP 协议文档
• Claude Desktop
• 项目远程仓库

Made with ❤️ by TuringDistract