amazon-order-history-csv-download-mcp

🚀 Amazon Order History CSV Download MCP

这是一个基于MCP（Model Context Protocol）的服务器，用于将亚马逊订单历史记录下载为CSV文件。它支持在16个亚马逊地区站点导出订单、商品、发货和交易信息。

🚀 快速开始

安装

# 克隆仓库
git clone https://github.com/marcusquinn/amazon-order-history-csv-download-mcp.git
cd amazon-order-history-csv-download-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 安装Playwright浏览器
npx playwright install chromium

配置

将以下内容添加到你的MCP客户端配置中（例如Claude Desktop）：

{
  "mcpServers": {
    "amazon-orders": {
      "command": "node",
      "args": ["/path/to/amazon-order-history-csv-download-mcp/dist/index.js"]
    }
  }
}

使用

配置完成后，你可以向你的AI助手提出以下请求：

• "以CSV格式下载我2024年的亚马逊订单"
• "导出我今年在亚马逊英国站购买的所有商品"
• "获取我最近亚马逊订单的发货跟踪信息"
• "为了税务目的，导出我的亚马逊支付交易记录"
• "我的亚马逊礼品卡余额是多少？"
• "显示我上个月的所有亚马逊交易记录"

✨ 主要特性

• 4种导出类型：订单摘要、商品详情、发货跟踪、支付交易
• 支持16个亚马逊地区：美国、英国、加拿大、德国、法国、西班牙、意大利等
• 浏览器自动化：使用Playwright进行可靠的数据提取
• AI助手集成：可与Claude、GPT等支持MCP的助手配合使用
• 灵活的日期范围：可按年份、日期范围或最近几个月进行导出

📦 安装指南

安装步骤

# 克隆仓库
git clone https://github.com/marcusquinn/amazon-order-history-csv-download-mcp.git
cd amazon-order-history-csv-download-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 安装Playwright浏览器
npx playwright install chromium

配置说明

将以下内容添加到你的MCP客户端配置中（例如Claude Desktop）：

{
  "mcpServers": {
    "amazon-orders": {
      "command": "node",
      "args": ["/path/to/amazon-order-history-csv-download-mcp/dist/index.js"]
    }
  }
}

💻 使用示例

基础用法

配置完成后，你可以向你的AI助手提出以下请求：

- "以CSV格式下载我2024年的亚马逊订单"
- "导出我今年在亚马逊英国站购买的所有商品"
- "获取我最近亚马逊订单的发货跟踪信息"
- "为了税务目的，导出我的亚马逊支付交易记录"
- "我的亚马逊礼品卡余额是多少？"
- "显示我上个月的所有亚马逊交易记录"

📚 详细文档

支持的地区

| 地区 | 域名 | 货币 | | -------------- | ------------- | -------- | | 美国 | amazon.com | USD | | 英国 | amazon.co.uk | GBP | | 加拿大 | amazon.ca | CAD | | 德国 | amazon.de | EUR | | 法国 | amazon.fr | EUR | | 西班牙 | amazon.es | EUR | | 意大利 | amazon.it | EUR | | 荷兰 | amazon.nl | EUR | | 日本 | amazon.co.jp | JPY | | 澳大利亚 | amazon.com.au | AUD | | 墨西哥 | amazon.com.mx | MXN | | 印度 | amazon.in | INR | | 阿联酋 | amazon.ae | AED | | 沙特阿拉伯 | amazon.sa | SAR | | 爱尔兰 | amazon.ie | EUR | | 比利时 | amazon.com.be | EUR |

导出类型

订单 (export_amazon_orders_csv)

从订单列表页面快速获取订单摘要（每10个订单约0.5秒）。适用于浏览和基本报告。 | 列名 | 描述 | | ---------------- | --------------------------------------------- | | 订单ID | 亚马逊订单标识符 (XXX-XXXXXXX-XXXXXXX) | | 订单日期 | 下单日期 (YYYY-MM-DD) | | 总计 | 订单总金额 | | 状态 | 配送状态 (已送达、已发货等) | | 商品数量 | 订单中的商品数量 | | 地址行1 - 7 | 送货地址 (最多7行) | | 订阅与节省 | 适用时的订阅频率 | | 平台 | 始终为 "amazon" | | 地区 | 亚马逊地区代码 (us, uk, de等) | | 订单URL | 订单详情页面的链接 |

商品 (export_amazon_items_csv)

详细的商品级导出，包含完整的订单上下文（每个订单约2秒）。适用于费用跟踪和会计。 | 列名 | 描述 | | ----------------- | ---------------------------------- | | 订单ID | 父订单标识符 | | 订单日期 | 下单日期 | | ASIN | 亚马逊产品标识符 | | 产品名称 | 完整的产品标题 | | 状况 | 新、二手等 | | 数量 | 商品数量 | | 单价 | 每件商品的价格 | | 商品总计 | 数量 × 单价 | | 卖家 | 卖家/商家名称 | | 订阅与节省 | 订阅频率 | | 订单小计 | 税前/运费小计 | | 订单运费 | 运费 | | 订单税 | 销售税金额 | | 订单增值税 | 增值税金额 (英国/欧盟) | | 订单促销 | 折扣金额 | | 订单总计 | 最终订单总金额 | | 订单总计（含所有费用） | 包括所有费用 | | 订单状态 | 配送状态 | | 收件人 | 送货姓名 | | 地址行1 - 7 | 完整的送货地址 | | 支付方式 | 卡类型 (Visa、Mastercard等) | | 卡后4位 | 卡的后4位数字 | | 产品URL | 产品页面的链接 | | 图片URL | 产品图片的URL | | 订单URL | 订单详情的链接 | | 地区 | 亚马逊地区代码 |

发货 (export_amazon_shipments_csv)

发货和跟踪信息（每个订单约4秒，使用 fetch_tracking_numbers 时额外增加2秒）。适用于配送跟踪。 | 列名 | 描述 | | ----------------- | ------------------------------------------ | | 订单ID | 父订单标识符 | | 订单日期 | 下单日期 | | 发货ID | 唯一的发货标识符 | | 状态 | 发货状态文本 | | 是否已送达 | 是/否/未知 | | 跟踪ID | 承运商跟踪号码 | | 承运商 | 承运商名称 (皇家邮政、DPD等) | | 跟踪URL | 承运商跟踪链接 | | 发货中的商品数量 | 商品数量 | | 商品名称 | 产品名称列表 | | 支付金额 | 收取的金额 (默认使用订单总金额) | | 退款 | 退款金额（如果有） | | 地区 | 亚马逊地区代码 |

注意：设置 fetch_tracking_numbers: true 可访问发货跟踪页面并提取实际的承运商跟踪ID（例如 "AZ218181365JE"）和承运商名称。如果不使用此选项，仅捕获亚马逊的内部跟踪URL。

交易 (export_amazon_transactions_csv)

支付交易详情，用于财务对账。 | 列名 | 描述 | | ---------------- | ------------------- | | 交易日期 | 收费日期 | | 订单ID(s) | 关联的订单(s) | | 支付方式 | 卡/支付类型 | | 卡信息 | 卡的后4位数字 | | 金额 | 交易金额 | | 货币 | 货币代码 |

礼品卡 (export_amazon_gift_cards_csv)

礼品卡活动和余额历史记录。 | 列名 | 描述 | | --------------- | ------------------------- | | 日期 | 交易日期 | | 描述 | 活动描述 | | 类型 | 添加/应用/退款 | | 金额 | 交易金额 | | 期末余额 | 交易后的余额 | | 订单ID | 关联的订单（如果有） | | 兑换码 | 礼品卡兑换码 | | 序列号 | 礼品卡序列号 | | 货币 | 货币代码 | | 地区 | 亚马逊地区代码 |

附加工具

查询工具

| 工具 | 描述 | | ----------------------------------- | --------------------------------------------- | | get_amazon_orders | 获取订单，可选择包含商品/发货信息 | | get_amazon_order_details | 获取特定订单的完整详情 | | get_amazon_transactions | 从交易页面获取所有交易记录 | | get_amazon_gift_card_balance | 获取当前余额和历史记录 | | get_amazon_gift_card_transactions | 获取详细的礼品卡活动 | | check_amazon_auth_status | 检查浏览器是否已登录 |

交易页面 (get_amazon_transactions)

从亚马逊专用的交易页面 (/cpe/yourpayments/transactions) 提取所有支付交易记录。比从单个订单页面提取快得多。

{
  "region": "us",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31"
}

礼品卡余额 (get_amazon_gift_card_balance)

从 /gc/balance 获取你当前的亚马逊礼品卡余额和近期活动。

{
  "region": "us"
}

返回：

• 当前余额
• 近期礼品卡活动 (充值/消费)
• 关联的订单ID

身份验证检查 (check_amazon_auth_status)

在运行导出之前，验证浏览器会话是否已通过身份验证。

{
  "region": "uk"
}

返回身份验证状态、登录后的用户名，或未登录时的登录URL。

🔧 技术细节

超时与大量订单历史记录

当导出大量订单历史记录（100个以上订单）时，提取过程可能需要几分钟。MCP客户端通常有超时限制，可能需要进行调整。

估计处理时间

| 订单数量 | 估计时间 | | ------ | -------------- | | 10 | ~15秒 | | 50 | ~1.5分钟 | | 100 | ~3分钟 | | 500 | ~15分钟 |

建议

1. 使用 max_orders 参数 限制提取范围
2. 按年份导出 而不是整个历史记录
3. 必要时配置客户端超时时间（见下文）

客户端超时配置

对于OpenCode/Claude Desktop，超时时间通常在MCP客户端配置中设置。如果你看到 MCP error -32001: Maximum total timeout exceeded，你可能需要：

1. 使用 max_orders 进行小批量导出
2. 配置你的MCP客户端的 maxTotalTimeout 设置（如果可用）
3. 如果客户端启用了 resetTimeoutOnProgress，服务器发送的进度通知可以重置超时时间

进度通知

服务器在提取过程中发送进度通知：

• Order X/Y (order-id) - ETA: ~Xm Xs 这些通知有助于跟踪进度，如果配置正确，还可以重置客户端的超时时间。

开发

# 以开发模式运行
npm run dev

# 运行测试
npm test

# 类型检查
npm run typecheck

# 代码检查
npm run lint

使用MCP Inspector进行测试

为了开发和调试，建议使用官方的 MCP Inspector 工具，而不是通过AI助手运行。这提供了：

• 直接调用工具 - 使用自定义参数直接调用MCP工具
• 实时查看响应 - 查看完整的JSON响应，无需AI解释
• 更快的迭代 - 无需等待AI处理请求
• 调试可见性 - 查看原始服务器输出和错误

快速开始

# 全局安装MCP Inspector
npm install -g @modelcontextprotocol/inspector

# 使用此服务器运行检查器
npx @modelcontextprotocol/inspector node dist/index.js

然后在浏览器中打开 http://localhost:5173 以：

1. 查看所有可用工具列表
2. 点击工具查看其架构
3. 填写参数并执行
4. 查看原始JSON响应

示例测试工作流程

1. 测试身份验证：使用 {"region": "uk"} 调用 check_amazon_auth_status
2. 测试订单获取：使用小日期范围调用 get_amazon_orders
3. 测试订单详情：使用已知订单ID调用 get_amazon_order_details
4. 测试导出：调用任何 export_amazon_*_csv 工具

这是以下场景的推荐方法：

• 调试提取问题
• 验证新功能是否正常工作
• 测试特定地区的行为
• 调查错误响应

架构

本项目使用插件架构，旨在实现可扩展性：

• 核心框架：用于CSV、日期、货币、浏览器自动化的共享实用程序
• 平台插件：亚马逊特定的提取逻辑（未来：eBay、AliExpress等）

详细的架构文档请参阅 AGENTS.md。

相关项目

• QuickFile MCP - 用于QuickFile英国会计软件的MCP服务器。将亚马逊订单导出与QuickFile结合使用，进行费用跟踪和增值税对账。
• OpenCode - 支持MCP的开源AI编码助手
• QuickFile - 英国会计软件
• QuickFile API - QuickFile API文档
• Model Context Protocol - AI工具集成的协议规范
• AI DevOps Framework - 全面的AI基础设施管理

致谢

本项目受到 AZAD 的启发，这是一个用于亚马逊订单历史记录导出的Chrome扩展。这是一个作为MCP服务器的原创实现，并非分支或衍生作品。

完整的致谢信息请参阅 CREDITS.md。

📄 许可证

本项目采用MIT许可证，详细信息请参阅 LICENSE。

贡献

欢迎贡献代码！请阅读 AGENTS.md 了解开发指南。