内容
# eshop-mcp
<div align="center">
**为 AI 助手提供淘宝/天猫生态结构化数据接口的 MCP Server**
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
覆盖消费者视角（C 端搜索、商品详情、评论、问大家）和商家视角（万相台投放数据、达摩盘人群资产与竞品分析）
[快速开始](#快速开始) • [功能特性](#功能特性) • [架构设计](#架构设计) • [使用文档](#使用文档)
</div>
---
## 功能特性
### 🔐 登录认证
- **阿里妈妈统一登录**：通过 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 客户端配置中添加：
```json
{
"mcpServers": {
"eshop": {
"command": "npx",
"args": ["-y", "eshop-mcp"]
}
}
}
```
如需配置环境变量：
```json
{
"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` 中设置：
```bash
# 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
```
### 本地开发
```bash
# 克隆项目
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：
```json
{
"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 调试模式**（首次使用前手动启动）：
```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 \
--user-data-dir=~/ChromeDebug
```
2. **执行登录**：
```typescript
// 阿里妈妈登录（万相台/达摩盘）
await alimama_login()
// 淘宝 C 端登录（可使用不同账号）
await tb_login()
```
3. **Cookie 管理**：
- 买家/卖家账号分离管理
- Cookie 通常可持续数天
- 过期后重新调用对应登录工具即可
- `TAOBAO_BACKEND=cdp` 时，商品采集工具只复用淘宝数据工作页；登录页或淘宝自身跳转只应出现在显式登录/刷新工具中
### DMP 工具使用顺序
```typescript
// 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` 文件中的敏感信息
---
## 开发指南
### 运行测试
```bash
# 单元测试
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：
```bash
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](LICENSE) 文件
---
## 相关链接
- [MCP 协议文档](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)
- [项目远程仓库](https://cnb.cool/turingdistract/eshop-data-extract-mcp)
---
<div align="center">
**Made with ❤️ by TuringDistract**
</div>
