Amazon Order History CSV Download MCP

亚马逊订单历史CSV下载MCP

MCP（模型上下文协议）服务器，用于将亚马逊订单历史记录下载为CSV文件。 支持跨16个亚马逊区域站点的订单、商品、发货和交易导出。

特性

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

快速开始

安装

# Clone the repository
git clone https://github.com/marcusquinn/amazon-order-history-csv-download-mcp.git
cd amazon-order-history-csv-download-mcp

# Install dependencies
npm install

# Build
npm run build

# Install Playwright browsers
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助手：

• “将2024年以来的亚马逊订单下载为CSV”
• “导出我今年在亚马逊英国购买的所有商品”
• “获取我最近亚马逊订单的发货跟踪”
• “出于税务目的导出我的亚马逊支付交易”
• “我的亚马逊礼品卡余额是多少？”
• “显示我上个月的所有亚马逊交易”

支持的地区

导出类型

订单(export_amazon_orders_csv)

从订单列表页面快速汇总订单（每10个订单约0.5秒）。最适合浏览和基本报告。

项目(export_amazon_items_csv)

具有完整订单上下文的详细项目级导出（每个订单约2秒）。最适合费用跟踪和会计。

出货量(export_amazon_shipments_csv)

发货和跟踪信息（每份订单约4秒，+2秒 fetch_tracking_numbers).最适合跟踪交货。

备注：设置 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

这些有助于跟踪进度，如果配置了，可以重置客户端超时。

发展

# Run in development mode
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

MCP检验员测试

对于开发和调试，请使用官方 MCP检查员 工具，而不是通过AI助手运行。这提供了：

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

快速开始

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run inspector with this server
npx @modelcontextprotocol/inspector node dist/index.js

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

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

测试工作流程示例

1. 测试身份验证：呼叫 check_amazon_auth_status 随着 {"region": "uk"}
2. 测试订单获取：呼叫 get_amazon_orders 日期范围较小
3. 测试订单详细信息：呼叫 get_amazon_order_details 具有已知的订单ID
4. 测试导出：呼叫任何 export_amazon_*_csv 工具

建议采用以下方法：

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

建筑

该项目采用了一种专为可扩展性而设计的插件架构：

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

看 代理商.md 获取详细的架构文档。

相关项目

• QuickFile MCP -用于QuickFile UK会计软件的MCP服务器。使用亚马逊订单导出和QuickFile进行费用跟踪和增值税对账。
• OpenCode -支持MCP的开源AI编码助手
• QuickFile -英国会计软件
• 快速文件API -QuickFile API文档
• 模型上下文协议 -AI工具集成协议规范
• AI DevOps框架 -全面的人工智能基础设施管理

鸣谢

这个项目的灵感来自 阿扎德，Chrome浏览器 亚马逊订单历史导出扩展。这是构建的原始实现 作为MCP服务器-而不是分支或衍生作品。

看 CREDITS.md 以获得完整的致谢。

许可证

MIT许可证-请参阅 许可证 了解详情。

贡献

欢迎投稿！请阅读 代理商.md 发展指南。