yooztech-mcp-taobao-search 0.0.1

MCP server for Taobao search and data scraping

yooztech_mcp_taobao_search —— 淘宝搜索采集 MCP 工具

基于 MCP (Model Context Protocol) 的淘宝搜索和商品数据采集工具，自动搜索关键词、提取商品信息并导出为 CSV。

功能概述

• taobao_search(keyword, ...): 搜索淘宝关键词，采集商品数据并导出 CSV

在 Cursor 中配置

{
  "mcpServers": {
    "yooztech_mcp_taobao_search": {
      "command": "yooztech_mcp_taobao_search",
      "args": []
    }
  }
}

或使用 uvx 方式：

{
  "mcpServers": {
    "yooztech_mcp_taobao_search": {
      "command": "uvx",
      "args": ["yooztech_mcp_taobao_search"]
    }
  }
}

工具详解

taobao_search - 淘宝搜索采集

根据关键词搜索淘宝商品，自动采集商品信息并导出为 CSV 文件。

参数：

• keyword (必填): 搜索关键词
• max_items (可选): 最大采集数量，默认 50，范围 1-200
• slowly (可选): 是否慢速操作（推荐），默认 true，避免操作过快
• output_csv (可选): CSV 输出路径，默认 ./tmp/taobao_<keyword>_<timestamp>.csv
• cdp_endpoint (可选): Chrome CDP 端点（如 ws://127.0.0.1:9222），如果提供则连接到已运行的 Chrome，否则启动新浏览器

返回：

• success: 是否成功
• csv_path: CSV 文件路径
• total_collected: 采集到的商品数量
• items: 商品数据列表（前 10 条预览）
• notes: 提取说明（如有）

CSV 列：

• 排位: 商品排名（1-based）
• 标题: 商品标题
• 付款人数: 付款/收货人数
• 链接: 商品详情页链接
• 店铺名: 店铺名称

使用示例：

{
  "tool": "taobao_search",
  "args": {
    "keyword": "iPhone 15",
    "max_items": 30,
    "slowly": true
  }
}

工作原理

1. 打开浏览器: 使用 Playwright 通过 Chrome DevTools Protocol (CDP) 控制浏览器
   • 可以连接到已运行的 Chrome（通过 cdp_endpoint 参数）
   • 或启动新的 headed 浏览器（可见模式）
2. 检测登录: 访问淘宝首页，检测是否已登录
3. 等待登录: 如果未登录，提示用户手动登录，等待最多 5 分钟
4. 直接导航: 构造并导航到搜索结果 URL https://s.taobao.com/search?page=1&q=<keyword>&tab=all（不操作搜索框）
5. 采集数据: 滚动页面加载更多商品，使用 JavaScript 在页面内提取商品信息
6. 去重导出: 根据商品链接去重，导出为 CSV（UTF-8 BOM，Excel 兼容）

注意事项

• 浏览器要求: 需要 Chrome/Chromium 浏览器
• 首次使用: 首次运行需要安装浏览器驱动：playwright install chromium
• 登录检测: 工具会自动检测登录状态，未登录时会等待用户手动登录
• CDP 连接: 如果 OpenClaw 或其他工具已启动 Chrome，可通过 cdp_endpoint 参数连接（如 ws://127.0.0.1:9222）
• 页面结构: 淘宝页面可能 A/B 测试或更新，如果解析失败，可能需要调整选择器
• 慢速模式: 建议设置 slowly=true 避免操作过快被限制

依赖

• Python >= 3.10
• mcp >= 1.2.0
• playwright >= 1.40.0

安装

# 安装 Python 依赖
pip install -e .

# 安装浏览器驱动（首次使用必须）
playwright install chromium

许可证

MIT (见 LICENSE)