# JD Taobao MCP

> 这是一个基于 Python 与 Playwright 开发的电商网页自动化 MCP Server，主要用于模拟用户在京东、淘宝等电商平台上的浏览和操作，并将网页信息以结构化数据形式提供给大模型或智能体调用。 项目支持商品搜索、商品列表读取、详情页访问、商品参数提取、价格与店铺信息获取、部分用户评价整理、页面截图及链接返回等功能。MCP Server 负责接收智能体指令，调用本地浏览器完成页面操作，返回支持 MCP 协议的客户端。

- **Type:** MCP server
- **Install:** `agentstack add mcp-haonanyu123-jd-taobao-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [HaonanYu123](https://agentstack.voostack.com/s/haonanyu123)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [HaonanYu123](https://github.com/HaonanYu123)
- **Source:** https://github.com/HaonanYu123/JD-Taobao-MCP

## Install

```sh
agentstack add mcp-haonanyu123-jd-taobao-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# JD-Taobao Browser MCP

一个本地运行、人工参与的 MCP Server。它通过 Playwright 打开真实、可见的 Chromium 浏览器，让 Codex 或其他 MCP 客户端在京东、淘宝、天猫页面中进行低频浏览、商品搜索、详情提取和截图。

> 本项目默认只读。用户必须自己完成扫码、密码、验证码、滑块和安全验证；工具不会绕过平台风控，也不会自动购买、加购、结算或支付。

## 功能

- 打开京东、淘宝登录页，并复用独立浏览器资料目录中的登录状态。
- 搜索京东或淘宝商品，返回标题、价格、店铺、评论文本、商品链接和图片。
- 打开商品详情页，提取标题、价格、店铺、规格、图片、产品参数、好评、差评、Meta、JSON-LD 和页面文本摘要。
- 商品详情输出带硬约束：必须包含 `product_url`、`product_parameters`、`good_reviews`、`bad_reviews` 及对应 `status` 字段；`good_reviews` 最多 5 条，`bad_reviews` 最多 2 条。
- 支持通用浏览器操作：打开 URL、页面快照、列出可交互元素、点击普通元素、普通输入、滚动、返回、截图。
- 只允许访问 `*.jd.com`、`*.360buy.com`、`*.taobao.com`、`*.tmall.com`。

## 项目结构

```text
JD-Taobao-MCP/
├─ server.py                       MCP 工具入口
├─ jd_taobao_mcp/
│  ├─ browser.py                   Playwright 持久化浏览器与通用操作
│  ├─ service.py                   搜索和详情页流程
│  ├─ safety.py                    域名、敏感输入与交易动作防护
│  └─ extractors/                  京东/淘宝页面提取器
├─ config_examples/
│  ├─ codex-config.toml            Codex 配置示例
│  └─ mcp-client.json              Cursor、Claude Desktop 等配置示例
├─ scripts/
│  ├─ install_windows.ps1          Windows 安装脚本
│  └─ start_windows.bat            Windows 启动脚本
├─ .env.example                    环境变量示例
├─ pyproject.toml                  Python 包配置
└─ README.md                       项目主页文档
```

## Windows 安装

要求：

- Windows 10/11
- Python 3.11+，推荐 Python 3.12
- Codex CLI 或其他支持 MCP 的客户端

在 PowerShell 中执行：

```powershell
git clone https://github.com/HaonanYu123/JD-Taobao-MCP.git
cd JD-Taobao-MCP
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install_windows.ps1
```

脚本会完成：

- 创建 `.venv`
- 安装本项目和 MCP SDK
- 安装 Playwright Chromium
- 首次复制 `.env.example` 为 `.env`
- 设置本地 Playwright 浏览器目录 `.ms-playwright`

手动安装：

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e "."
.\.venv\Scripts\python.exe -m playwright install chromium
copy .env.example .env
```

本地启动测试：

```powershell
.\.venv\Scripts\python.exe server.py
```

如果服务进入等待状态，没有立即退出，说明 MCP stdio 服务可以被客户端拉起。按 `Ctrl+C` 退出。

## Codex 配置

Codex 的 MCP 配置文件通常位于：

```text
%USERPROFILE%\.codex\config.toml
```

把下面配置追加到 `config.toml`，并把 `` 替换为本仓库的绝对路径，例如：

```text
C:\Users\你的用户名\Desktop\JD-Taobao-MCP
```

```toml
[mcp_servers.jd_taobao_browser]
command = "/.venv/Scripts/python.exe"
args = ["/server.py"]
cwd = ""
enabled = true
required = false
startup_timeout_sec = 30
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"

[mcp_servers.jd_taobao_browser.env]
PLAYWRIGHT_HEADLESS = "false"
ALLOW_STATE_CHANGING_ACTIONS = "false"
PLAYWRIGHT_BROWSERS_PATH = ".ms-playwright"
BROWSER_PROFILE_DIR = ".tmp/browser-profile"
ARTIFACTS_DIR = "artifacts"
TAOBAO_SEARCH_MODE = "mobile"
```

也可以用命令添加：

```powershell
codex mcp add jd-taobao-browser --env PLAYWRIGHT_HEADLESS=false --env ALLOW_STATE_CHANGING_ACTIONS=false --env PLAYWRIGHT_BROWSERS_PATH=.ms-playwright --env BROWSER_PROFILE_DIR=.tmp/browser-profile --env ARTIFACTS_DIR=artifacts --env TAOBAO_SEARCH_MODE=mobile -- C:\Users\你的用户名\Desktop\JD-Taobao-MCP\.venv\Scripts\python.exe C:\Users\你的用户名\Desktop\JD-Taobao-MCP\server.py
codex mcp list
```

配置后重启 Codex。看到 `jd-taobao-browser` 或 `jd_taobao_browser` 已启用后即可调用工具。

## Cursor、Claude Desktop 等 JSON 客户端配置

参考 `config_examples/mcp-client.json`：

```json
{
  "mcpServers": {
    "jd-taobao-browser": {
      "command": "\\.venv\\Scripts\\python.exe",
      "args": ["\\server.py"],
      "env": {
        "PLAYWRIGHT_HEADLESS": "false",
        "ALLOW_STATE_CHANGING_ACTIONS": "false",
        "PLAYWRIGHT_BROWSERS_PATH": ".ms-playwright",
        "BROWSER_PROFILE_DIR": ".tmp/browser-profile",
        "ARTIFACTS_DIR": "artifacts",
        "TAOBAO_SEARCH_MODE": "mobile"
      }
    }
  }
}
```

## 首次使用流程

1. 调用 `browser_start()` 启动可见浏览器。
2. 调用 `open_login(platform="jd")` 或 `open_login(platform="taobao")`。
3. 在浏览器里手动扫码、输入密码、完成验证码或安全验证。
4. 调用 `check_login(platform="jd")` 或 `check_login(platform="taobao")`。
5. 调用 `search_products(...)` 或 `get_product_detail(url)` 提取商品数据。

示例提示：

```text
用 jd-taobao-browser MCP 搜索京东的“RTX 5070 笔记本”，最多返回 10 个，价格 7000 到 12000 元，并按价格从低到高排序。不要点击购买或购物车。
```

```text
打开这个淘宝商品链接，提取标题、当前页面价格、店铺、产品参数、最多 5 条好评和最多 2 条差评；页面要求验证时停止并让我手动处理。
```

## 工具清单

| 工具 | 作用 |
|---|---|
| `browser_start` | 启动可见 Chromium 浏览器 |
| `browser_status` | 查看京东、淘宝浏览器状态 |
| `open_login` | 打开京东或淘宝登录页 |
| `check_login` | 检查是否可能已登录，不返回 Cookie 值 |
| `open_url` | 打开允许域名下的 URL |
| `search_products` | 搜索商品并结构化提取 |
| `get_product_detail` | 提取商品详情，包含硬约束字段 |
| `page_snapshot` | 获取当前页面文本、链接、表单和基础元数据 |
| `extract_current_page` | 对当前页面执行快照和商品字段提取 |
| `list_page_elements` | 列出当前可交互元素并分配临时 ref |
| `click_page_element` | 点击普通元素，默认阻止交易和状态变更动作 |
| `type_into_element` | 输入普通文本，拒绝密码、验证码、支付等敏感字段 |
| `scroll_page` | 页面滚动 |
| `go_back` | 返回上一页 |
| `take_screenshot` | 保存截图到 `ARTIFACTS_DIR` |
| `browser_close` | 关闭浏览器 |

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `PLAYWRIGHT_HEADLESS` | `false` | 是否无头运行；建议保持 `false`，便于人工登录和验证 |
| `BROWSER_CHANNEL` | 空 | 可填 `msedge` 或 `chrome`，留空使用 Playwright Chromium |
| `BROWSER_EXECUTABLE_PATH` | 空 | 指定通用浏览器可执行文件路径 |
| `JD_BROWSER_EXECUTABLE_PATH` | 空 | 单独指定京东浏览器路径 |
| `TAOBAO_BROWSER_EXECUTABLE_PATH` | 空 | 单独指定淘宝/天猫浏览器路径 |
| `TAOBAO_SEARCH_MODE` | `mobile` | 淘宝搜索模式，可选 `mobile` 或 `pc` |
| `BROWSER_PROFILE_DIR` | `~/.jd-taobao-browser-mcp/browser-profile` | 独立浏览器资料目录 |
| `ARTIFACTS_DIR` | `~/.jd-taobao-browser-mcp/artifacts` | 截图等产物目录 |
| `PLAYWRIGHT_BROWSERS_PATH` | `.ms-playwright` | Playwright 浏览器下载目录 |
| `NAVIGATION_TIMEOUT_MS` | `45000` | 页面导航超时 |
| `ACTION_TIMEOUT_MS` | `15000` | 单步操作超时 |
| `ACTION_DELAY_MS` | `700` | 操作间隔 |
| `SLOW_MO_MS` | `80` | Playwright 慢动作延迟 |
| `MAX_PAGE_TEXT_CHARS` | `18000` | 页面文本摘要最大长度 |
| `MAX_SEARCH_RESULTS` | `30` | 单次搜索最多返回数量 |
| `ALLOW_STATE_CHANGING_ACTIONS` | `false` | 是否允许购买、加购、关注等状态变更动作；不建议开启 |
| `PROXY` | 空 | 可选代理，例如 `http://127.0.0.1:7897` |

## 安全边界

- 不绕过验证码、滑块、安全验证或平台风控。
- 不注入反检测脚本，不伪造浏览器环境。
- 不读取或返回 Cookie 值，只在登录检查时返回 Cookie 名称。
- 密码、验证码、支付密码、银行卡、身份证、OTP 等字段禁止自动输入。
- 默认拒绝购买、加购、结算、支付、关注、收藏、删除和账户信息修改。
- 不适合高频、大规模采集。

## 常见问题

### 为什么不要使用日常 Chrome/Edge 用户目录？

Playwright 持久化上下文会保存 Cookie、本地存储和登录状态。不要把 `BROWSER_PROFILE_DIR` 指向日常浏览器默认用户目录；浏览器可能拒绝并发使用，也会增加误操作风险。

### 页面要求验证怎么办？

工具会返回 `requires_user_verification=true` 或在状态字段里说明原因。此时需要用户在可见浏览器中手动完成验证，然后再继续调用工具。

### GitHub 主页为什么会空？

GitHub 只会把仓库根目录的 `README.md` 显示在项目主页。详细文档必须放在仓库根目录，而不是只放在子目录或缺失的路径下。

## 开发命令

```powershell
.\.venv\Scripts\python.exe -m pytest
```

```powershell
.\scripts\start_windows.bat
```

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [HaonanYu123](https://github.com/HaonanYu123)
- **Source:** [HaonanYu123/JD-Taobao-MCP](https://github.com/HaonanYu123/JD-Taobao-MCP)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-haonanyu123-jd-taobao-mcp
- Seller: https://agentstack.voostack.com/s/haonanyu123
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.