使用说明

淘宝MCP服务器

用于抓取淘宝/天猫产品信息的模型上下文协议（MCP）服务器。

此MCP服务器使AI助手能够从淘宝和天猫获取全面的产品数据，包括产品详细信息、图像、规格、客户评论和问答部分。非常适合产品研究、比较和分析。

🌟 特性

自动链路检测：识别中文分享文本中的淘宝/天猫链接
多种输入格式：支持产品ID、直接URL、短链接和共享文本
综合数据：取消标题、价格、图片、规格、评论和问答
持续会话：浏览器会话在多个请求中保持登录状态
双语支持：同时处理英文和中文输入/输出
Markdown输出：返回结构化、AI友好的Markdown格式

📦 什么会被废弃

对于每个产品，此MCP服务器提取：

数据类型	详细信息
基本信息	Title (标题), Price (价格), Store Name (店铺), Product ID
图像	Thumbnail images (缩略图) + Detailed product images (详情图)
参数	Product specifications (参数) and attributes (属性)
评论	带有文字、评分和照片的客户评价
问答	客户问题和卖家回答

🚀 安装

先决条件

Python 3.10或更高版本
uv 包管理器（或常规 pip)
Chromium浏览器（由Playwright自动安装）

步骤1：安装依赖项

cd taobao_mcp
uv pip install -e .
# OR
pip install -e .

步骤2：安装Playwright浏览器

playwright install chromium

步骤3：配置MCP服务器

创建或编辑MCP配置文件：

适用于Claude Code CLI

创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "taobao-scraper": {
      "command": "python3",
      "args": [
        "/absolute/path/to/taobao_mcp/server.py"
      ],
      "env": {}
    }
  }
}

替换 /absolute/path/to/ 此目录的实际路径！

适用于克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "taobao-scraper": {
      "command": "python3",
      "args": [
        "/absolute/path/to/taobao_mcp/server.py"
      ]
    }
  }
}

步骤4：重新启动AI助手

克劳德代码CLI：开始新对话或重新加载
克劳德桌面版：重新启动应用程序

🎯 使用工作流程

步骤1：初始化登录（首先需要）

在刮擦任何产品之前必须初始化浏览器会话：

User: "Initialize Taobao login"
AI: [Calls taobao_initialize_login]

AI将：

启动Chrome浏览器窗口
导航到淘宝主页
检查是否需要登录
如果需要登录：等待您扫描二维码
保存会话以备将来使用

每节课只需要做一次！

步骤2：获取产品信息

初始化后，您可以使用以下任何格式获取产品：

User: "【淘宝】假一赔四 https://e.tb.cn/h.StvCjJlWxkNatsx?tk=xxx MF937 「UBV美式休闲空气层棉...」"
AI: [Calls taobao_fetch_product_info with the full text]

User: "Analyze this product: https://detail.tmall.com/item.htm?id=881280651752"
AI: [Calls taobao_fetch_product_info with the URL]

User: "Research product 881280651752"
AI: [Calls taobao_fetch_product_info with the ID]

AI将自动：

从您的消息中提取产品ID/URL
导航到产品页面
删除所有可用信息
返回结构化Markdown

🔧 可用工具

1. `taobao_initialize_login`

目的：初始化浏览器会话并处理淘宝身份验证

参数：无

何时打电话:

用户提到淘宝、天猫，或提供产品链接
必须提前致电 taobao_fetch_product_info
每个会话只需要调用一次

退货:

状态： success, login_required, already_initialized，或 error
关于后续步骤的消息

示例:

User: "帮我做一个research" + Taobao link
AI: → Calls taobao_initialize_login first

2. `taobao_fetch_product_info`

目的：抓取全面的产品信息，并以Markdown格式返回

参数:

product_url_or_id （string）：产品ID、URL、短链接或共享文本

支持格式:

产品ID: "881280651752"
直接URL： "https://detail.tmall.com/item.htm?id=881280651752"
短链接： "https://e.tb.cn/h.StvCjJlWxkNatsx?tk=xxx"
共享文本： "【淘宝】假一赔四 https://e.tb.cn/h.xxx MF937 「商品名称」"

退货:

Markdown格式的产品信息
包括元数据（抓取时间、图像计数、评论计数）
图像URL作为Markdown图像链接
参数表
结构化评审和问答

示例:

User: "【淘宝】product https://e.tb.cn/h.xxx"
AI: → Calls taobao_fetch_product_info(product_url_or_id='【淘宝】product https://e.tb.cn/h.xxx')

🤖 人工智能助理将如何使用它

自动检测

当你提到淘宝相关关键词或提供链接时，AI会自动：

触发器关键字 （中文）：

淘宝、天猫、产品、刮刮、研究、分析、比较、评论

触发器关键字 （中文）：

淘宝, 天猫, 商品, 分析, 对比, 评价, 价格

触发模式:

以开头的URL https://e.tb.cn/
URL包含 detail.tmall.com 或 item.taobao.com
像这样共享文本 【淘宝】...

对话示例

场景1：研究请求

User: "帮我做一个research" + [Taobao link]

AI思考:
1. User wants to research a Taobao product
2. Need to initialize first (if not already done)
3. Then fetch the product info

AI执行:
→ taobao_initialize_login()
→ taobao_fetch_product_info(product_url_or_id='[link]')
→ Analyzes the returned Markdown and presents insights

场景2：产品比较

User: "Compare these two products: [link1] and [link2]"

AI执行:
→ taobao_initialize_login() (if needed)
→ taobao_fetch_product_info([link1])
→ taobao_fetch_product_info([link2])
→ Compares prices, specs, reviews, etc.

场景3：用户不知道MCP

User: "Can you help me browse Taobao?"

AI:
"I can help you research Taobao products! I have access to a Taobao scraping tool.

First, I need to initialize the browser session. This will open a browser window where you may need to scan a QR code if login is required.

Let me start the initialization..."

→ taobao_initialize_login()

⚠️ 重要说明

先决条件

总是打电话 taobao_initialize_login 第一
- 在任何产品报废之前，这是强制性的
- 人工智能在检测淘宝内容时应该自动执行此操作
浏览器必须保持打开状态
- 浏览器窗口将保持打开状态以维持会话
- 刮擦时不要手动关闭
二维码登录
- 如果淘宝需要登录，请扫描浏览器窗口中的二维码
- 使用淘宝手机应用程序进行扫描
- 会话将被保存以备将来使用

数据新鲜度

从淘宝/天猫抓取实时数据
评论和价格是最新的刮时间
报废数据立即返回（不缓存）

局限性

仅适用于公共产品页面
某些产品可能需要登录才能查看完整详细信息
速率限制可能适用于短时间内太多的请求
页面结构更改可能需要更新选择器

🐛 故障排除

错误：“浏览器未初始化”

原因：初始化前尝试获取产品

解决方案:

AI should call: taobao_initialize_login()

错误：“无法提取产品ID”

原因：产品链接或ID格式无效

解决方案：验证输入格式是否与以下之一匹配：

产品ID（12-13位数字）： 881280651752
直接URL： https://detail.tmall.com/item.htm?id=881280651752
短链接： https://e.tb.cn/h.xxx
分享包含上述内容的文本

错误：“需要登录”

原因：会话已过期或未登录

解决方案:

呼叫 taobao_initialize_login 再次
如有提示，在浏览器中扫描二维码
重新尝试获取产品

浏览器无法打开

原因：未安装Playwright浏览器或权限问题

解决方案:

playwright install chromium
# Verify installation
python3 -c "from playwright.sync_api import sync_playwright; p = sync_playwright().start(); browser = p.chromium.launch(); print('✓ OK'); browser.close(); p.stop()"

短链接解析失败

原因：网络问题或无效的短链接

解决方案：请尝试使用直接产品URL或ID

MCP服务器连接失败（克劳德代码）

症状:

MCP服务器在中显示为“失败” /mcp 管理面板
日志错误： "No such file or directory (os error 2)"
日志位置： /Users/yourusername/Library/Caches/claude-cli-nodejs/-Users-yourusername-Desktop-test/mcp-logs-taobao-scraper/

常见原因:

路径不正确 .mcp.json：配置文件可能有错误的目录路径
使用错误的Python解释器：不使用虚拟环境的Python
双嵌套目录：路径式 /path/to/taobao_mcp/taobao_mcp （不正确）

解决方案:

检查你的 .mcp.json 配置 （位于项目根目录中）：

{
  "mcpServers": {
    "taobao-scraper": {
      "command": "/absolute/path/to/taobao_mcp/.venv/bin/python",
      "args": [
        "/absolute/path/to/taobao_mcp/server.py"
      ],
      "env": {}
    }
  }
}

验证路径是否正确:

# Check Python exists
ls -la /path/to/taobao_mcp/.venv/bin/python

# Check server.py exists
ls -la /path/to/taobao_mcp/server.py

# Test server can start
/path/to/taobao_mcp/.venv/bin/python /path/to/taobao_mcp/server.py <<< '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

应避免的常见错误:
- ❌ 使用 python3 而不是venv Python的完整路径
- ❌ 路径类 /path/to/taobao_mcp/taobao_mcp/server.py （双目录）
- ❌ 相对路径，如 ./server.py （使用绝对路径）
- ✅ 正确：Python和server.py的完整绝对路径
修复后，重新启动Claude Code 重新加载MCP服务器

调试提示:

跑 claude --debug 查看详细日志
检查中的日志文件 ~/Library/Caches/claude-cli-nodejs/
在中查找最新的日志文件 mcp-logs-taobao-scraper/ 目录

📂 文件结构

taobao_mcp/
├── README.md              # This file (comprehensive documentation)
├── server.py              # Main MCP server with tool registration
├── taobao_scraper.py      # Core scraping logic and browser automation
├── pyproject.toml         # Python dependencies
├── USAGE.txt              # Quick reference guide
└── .venv/                 # Virtual environment (created during install)

🔄 更新和维护

更新MCP服务器

cd taobao_mcp
git pull  # If using git
uv pip install -e . --force-reinstall

清除浏览器缓存

如果遇到问题，请清除浏览器配置文件：

rm -rf ../user_data/chrome_profile

然后重新初始化并再次登录。

版本信息

当前版本: 1.2
最后更新: 2025-11-17
MCP协议版本: 1.0
Python SDK版本：与mcp兼容>=0.9.0

💡 最佳结果提示

直接使用中文共享文本 -无需手动提取链接
每个会话初始化一次 -除非登录过期，否则不要重新初始化
等待初始化完成 -出现提示时扫描二维码
保持浏览器窗口打开 -刮擦时不要关闭它
尽可能使用直接URL -比解析短链接更快

🌐 语言支持

此MCP服务器完全支持：

英语：所有工具说明和错误消息
Chinese (中文)：识别中文产品名称、描述和共享文本
混合输入：无缝处理双语文本

📝 许可证和信用证

用于研究和产品分析目的。

依赖项:

MCP Python SDK-模型上下文协议实现
剧作家-浏览器自动化
Pydantic-输入验证
aiohttp-HTTP客户端

🆘 支持

如果您遇到问题：

仔细检查此README
验证是否正确遵循了安装步骤
检查浏览器配置文件权限
尝试清除浏览器缓存并重新初始化
确保淘宝网站可从您的网络访问

快乐刮！ 🎉

这个MCP服务器帮助人工智能助手高效地研究淘宝产品。

使用说明

淘宝MCP服务器

🌟 特性

📦 什么会被废弃

🚀 安装

先决条件

步骤1：安装依赖项

步骤2：安装Playwright浏览器

步骤3：配置MCP服务器

适用于Claude Code CLI

适用于克劳德桌面

步骤4：重新启动AI助手

🎯 使用工作流程

步骤1：初始化登录（首先需要）

步骤2：获取产品信息

🔧 可用工具

1. taobao_initialize_login

2. taobao_fetch_product_info

🤖 人工智能助理将如何使用它

自动检测

对话示例

⚠️ 重要说明

先决条件

数据新鲜度

局限性

🐛 故障排除

错误：“浏览器未初始化”

错误：“无法提取产品ID”

错误：“需要登录”

浏览器无法打开

短链接解析失败

MCP服务器连接失败（克劳德代码）

📂 文件结构

🔄 更新和维护

更新MCP服务器

清除浏览器缓存

版本信息

💡 最佳结果提示

🌐 语言支持

📝 许可证和信用证

🆘 支持

相关 MCP

Markdown微信排版发布工具

谷歌表格集成工具

JavaScript逆向标准化服务

OBS控制服务器

Kali Linux MCP服务器

Metabase MCP 服务器

1. `taobao_initialize_login`

2. `taobao_fetch_product_info`