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 瞭解開發指南。