内容
# 亚马逊购物 MCP
一个 **模型上下文协议（MCP）** 服务器，允许克劳德（Claude）为您在亚马逊上购物 — 端到端。它搜索产品，抓取完整的规格和评论，并（登录后）可以将商品添加到购物车并使用您亚马逊账户中已保存的卡和地址下单。
使用 **Playwright** 构建，可靠的浏览不会像简单的 HTTP 请求那样被阻止。
## 功能
- **搜索亚马逊** — 搜索任何亚马逊域名（.ca，.com，.co.uk等）并获取结构化结果，包括价格、评分、评论数和 Prime 状态
- **产品详情** — 抓取完整的产品页面，获取规格、功能、描述、可用颜色/尺寸、品牌、定价（当前 + 列表价格）、图片和可用性。支持 **并行抓取** 多个产品以进行快速比较
- **产品评论** — 拉取评分分布（5星细分）、总体评分和个别评论，包括标题、正文、星级、日期和验证购买状态
- **购买产品** — 登录一次，然后列出已保存的地址和卡片，将商品添加到购物车，查看购物车并下单。**结账需要明确的确认步骤**，因此在您确认之前永远不会购买任何商品
- **从不显示原始卡号** — 购买使用您亚马逊账户中已保存的卡片和地址；服务器只会看到亚马逊自己显示的最后 4 位数字
- **CAPTCHA 检测** — 自动检测亚马逊何时显示机器人检查并返回清晰的错误而不是垃圾数据
## 工具
### 浏览（无需登录）
| 工具 | 描述 |
|---|---|
| `amazon_search` | 搜索亚马逊。返回最多 20 个结果，包括标题、价格、评分、评论数、Prime 徽章、ASIN 和产品网址 |
| `amazon_product_details` | 并行抓取一个或多个产品页面。返回规格、功能、描述、颜色、尺寸、品牌、价格、图片、可用性 |
| `amazon_product_reviews` | 从产品页面获取评论。返回星级分布、总体评分、评论总数和个别评论 |
### 购买（需要先 `amazon_login`）
| 工具 | 描述 |
|---|---|
| `amazon_login` | 打开一个 **真实、可见** 的浏览器窗口，以便您手动登录（包括 2FA）。会话保存到磁盘并被以下每个工具重用 |
| `amazon_login_status` | 检查保存的会话是否仍登录，以及登录用户 |
| `amazon_list_addresses` | 列出您账户中保存的运费地址，每个地址都有一个用于结账的 `index` |
| `amazon_list_payment_methods` | 列出已保存的卡片 — **仅显示后 4 位数字、网络和到期日期**，每个都有一个 `index` |
| `amazon_add_to_cart` | 将产品（按 ASIN 或网址）添加到购物车，可选数量 |
| `amazon_view_cart` | 查看购物车商品、数量和子总计 |
| `amazon_place_order` | 完成结账。默认 = **仅预览** （返回收货地址/付款/总计）。再次调用时添加 `confirm=true` 以实际下单 |
| `amazon_subscribe` | 在产品上设置订阅并保存。默认 = **仅预览** （基本价格/折扣/频率）。`confirm=true` 创建 **循环** 订阅 |
### 订单和退货（需要先 `amazon_login`）
| 工具 | 描述 |
|---|---|
| `amazon_list_orders` | 列出最近的订单 — 订单号、日期、总计、商品、配送状态以及当前是否提供退货 |
| `amazon_view_returns` | 列出正在进行/过去的退货及其状态（从退货筛选的订单历史记录中） |
| `amazon_start_return` | 为订单打开退货向导。默认 = **仅预览** （可退货商品 + 原因选项）；`confirm=true` 提交 |
## 设置
### 先决条件
- Python 3.11+
- [uv](https://docs.astral.sh/uv/) （推荐）或 pip
### 安装
```bash
git clone https://github.com/duaragha/amazon-shopping-mcp.git
cd amazon-shopping-mcp
uv sync
```
为 Playwright 安装浏览器：
```bash
# 使用捆绑的 Chromium（在任何地方都有效，推荐）
.venv/bin/playwright install chromium
# 或通过设置 BROWSER_CHANNEL 使用现有浏览器：
# "chrome", "msedge" 等 — 不需要 Playwright 安装
```
### 添加到克劳德代码
```bash
# 使用捆绑的 Chromium（默认）
claude mcp add --scope user amazon-shopping -- /path/to/amazon-shopping-mcp/.venv/bin/python -m amazon_mcp
# 或使用特定浏览器（例如 Edge、Chrome）：
claude mcp add --scope user -e BROWSER_CHANNEL=msedge amazon-shopping -- /path/to/amazon-shopping-mcp/.venv/bin/python -m amazon_mcp
```
将 `/path/to/amazon-shopping-mcp` 替换为实际的存储库克隆路径。
然后重启克劳德代码（或启动新会话）以获取新工具。
### 添加到克劳德桌面版
将以下内容添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"amazon-shopping": {
"command": "/path/to/amazon-shopping-mcp/.venv/bin/python",
"args": ["-m", "amazon_mcp"]
}
}
}
```
## 用法
配置完成后，直接自然地询问克劳德：
> “在亚马逊上为我找到一款价格低于 100 美元的最佳网络摄像头”
克劳德将：
1. **搜索** 亚马逊上的网络摄像头
2. **抓取** 顶级候选产品的详细信息（并行）
3. **阅读** 最终产品的评论
4. **比较** 所有内容并为您提供前 3 名，并附上理由和直接链接
您也可以更具体：
> “比较亚马逊上的这两个产品：[url1] 和 [url2]”
> “[url] 的评论中人们在抱怨什么？”
> “在亚马逊美国站搜索机械键盘，价格低于 150 美元，并告诉我哪一个的做工最好”
### 购买商品
首先，登录（每个会话生命周期一次）：
> “请帮我登录亚马逊”
这会打开一个真正的浏览器窗口 — 输入您的密码和任何 2FA 代码，会话就会被保存。然后：
> “列出我的亚马逊地址和卡片”
> “将罗技 MX Master 3S 添加到我的购物车”
> “查看运费到我家地址使用维萨卡 — 但在下单前显示总计”
克劳德预览订单（商品、收货地址、付款、总计）。只有当您确认：
> “是的，下单”
… 才会实际购买。**在明确确认之前，绝不会购买任何商品。**
### 配置（环境变量）
| 变量 | 默认值 | 目的 |
|---|---|---|
| `AMAZON_DOMAIN` | `ca` | 账户/购物车/结账的默认商店 |
| `AMAZON_USER_DATA_DIR` | `~/.amazon-mcp/user-data` | 登录浏览器配置文件存储位置 |
| `AMAZON_HEADLESS` | `1` | 设置为 `0` 以观察购买工具驱动浏览器（对于调试结账有帮助） |
| `BROWSER_CHANNEL` | _(未设置)_ | 使用已安装的浏览器（`chrome`、`msedge`）代替捆绑的 Chromium |
### 参数
**`amazon_search`**
- `query` — 搜索词（例如“价格低于 50 美元的无线耳塞”）
- `domain` — 亚马逊域名后缀：“`ca`”（默认）、`“com”`、`“co.uk”`等
- `max_results` — 返回的结果数量（默认：20）
**`amazon_product_details`**
- `urls` — 亚马逊产品页面网址列表（并行抓取，最多 8 个并发）
**`amazon_product_reviews`**
- `url` — 亚马逊产品页面网址
- `max_reviews` — 要返回的最大评论数（默认：15）
## 工作原理
使用 Playwright 和无头浏览器加载实际的亚马逊页面，然后使用 JavaScript 评估从 DOM 中提取数据。这种方法比基于 API 的爬虫更可靠，因为：
- 像真正的浏览器一样渲染完整页面
- 处理通过 JavaScript 加载的动态内容
- 不需要任何 API 密钥或联盟账户
- 支持任何亚马逊域名
服务器使用 MCP 协议通过 stdio 运行，因此它与任何兼容 MCP 的客户端一起工作。
## 限制和注意事项
- **购买工具自动化登录会话，这违反亚马逊的使用条款。** 重度或类似机器人的使用可能会导致您的账户被标记或限制。请谨慎使用并自担风险。
- **登录是人机协作的。** 密码和 2FA/OTP 由您在真正的浏览器窗口中输入；它们绝不会被存储或自动化。因此，`amazon_login` 需要图形显示。
- **结账 DOM 严重混淆且特定于地区。** 地址/付款选择和下单选择器是尽力而为的，可能需要在亚马逊布局更改后进行调整 — 运行 `AMAZON_HEADLESS=0` 以查看和调整。`amazon_place_order` 只有在您传递 `confirm=true` 时才会点击“下单”。
- 亚马逊可能会在大量使用时偶尔显示验证码 — 服务器会检测到这一点并报告
- 评论从产品页面抓取（最多约 10-15 条评论），而不是需要登录的专用评论页面
- 产品页面布局各不相同 — 某些字段对于某些产品可能是空的
- 爬取速度取决于您的连接和亚马逊的响应时间
## 许可证
MIT
