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

📚 详细文档

支持的地区

导出类型

订单 (export_amazon_orders_csv)

从订单列表页面快速获取订单摘要（每10个订单约0.5秒）。适用于浏览和基本报告。

商品 (export_amazon_items_csv)

详细的商品级导出，包含完整的订单上下文（每个订单约2秒）。适用于费用跟踪和会计。

发货 (export_amazon_shipments_csv)

发货和跟踪信息（每个订单约4秒，使用 fetch_tracking_numbers 时额外增加2秒）。适用于配送跟踪。

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

交易 (export_amazon_transactions_csv)

支付交易详情，用于财务对账。

礼品卡 (export_amazon_gift_cards_csv)

礼品卡活动和余额历史记录。

附加工具

查询工具

交易页面 (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客户端通常有超时限制，可能需要进行调整。

估计处理时间

建议

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 了解开发指南。