eshop-data-extract-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 | 拉取计划明细，支持按场景/日期/状态筛选 |

达摩盘（DMP）

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

🐍 数据分析

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

快速开始

前置要求

Node.js >= 18
pnpm（推荐）或 npm
Google Chrome（登录功能需要）

安装

# 克隆项目
git clone https://github.com/your-username/eshop-data-extract-mcp.git
cd eshop-data-extract-mcp

# 安装依赖
pnpm install

# 构建项目
pnpm build

配置

在项目根目录创建 .env 文件：

# Chrome DevTools Protocol 端口
CDP_PORT=9222

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

# 数据存储目录
# 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

启动

# 生产模式
pnpm start

# 开发模式（热重载）
pnpm dev

接入 Claude Desktop / Claude Code

在 MCP 客户端配置中添加：

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

架构设计

eshop-data-extract-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 管理

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

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

执行登录：

// 阿里妈妈登录（万相台/达摩盘）
await alimama_login()

// 淘宝 C 端登录（可使用不同账号）
await tb_login()

Cookie 管理：
- 买家/卖家账号分离管理
- Cookie 通常可持续数天
- 过期后重新调用对应登录工具即可

DMP 工具使用顺序

// 1. 获取商品列表
dmp_list_shop_items({ category_id: "xxx" })

// 2. 查看商品生命周期
dmp_get_item_info({ item_id: "123" })

// 3. 获取对标选项
dmp_get_benchmark_list({ item_id: "123" })

// 4. 诊断分析（使用 benchmark_id）
dmp_get_grow_diagnose({
  item_id: "123",
  benchmark_id: "benchmark_123"
})

// 5. 竞品对比
dmp_compare_key_metrics({
  my_item_id: "123",
  comp_item_id: "456"
})

注意事项

⚠️ 反爬风险

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

📁 数据存储

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

🔒 隐私与安全

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

开发指南

运行测试

# 单元测试
pnpm test

# 集成测试
pnpm test:integration

# 测试监视模式
pnpm test:watch

项目脚本

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

贡献指南

欢迎提交 Issue 和 Pull Request！

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

许可证

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

MCP Servers