Amazon Order History Csv Download MCP

🚀 Amazon Order History CSV Download MCP

MCP（モデルコンテキストプロトコル）サーバーで、Amazonの注文履歴をCSVファイルとしてダウンロードすることができます。16のAmazon地域サイトにまたがる注文、商品、出荷、および取引のエクスポートに対応しています。

✨ 主な機能

• 4種類のエクスポートタイプ：注文の概要、商品の詳細、出荷追跡、支払い取引
• 16のAmazonリージョン：米国、英国、カナダ、ドイツ、フランス、スペイン、イタリアなど
• ブラウザ自動化：信頼性の高いデータ抽出に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アシスタントに以下のように問い合わせることができます。

- "2024年のAmazon注文をCSVとしてダウンロードして"
- "今年、Amazon UKで購入したすべての商品をエクスポートして"
- "最近のAmazon注文の出荷追跡情報を取得して"
- "税務目的でAmazonの支払い取引をエクスポートして"
- "私のAmazonギフトカードの残高はいくら？"
- "先月のすべてのAmazon取引を表示して"

対応リージョン

エクスポートタイプ

注文 (export_amazon_orders_csv)

注文リストページからの高速な注文概要（注文10件あたり約0.5秒）。閲覧や基本的なレポートに最適です。

商品 (export_amazon_items_csv)

完全な注文コンテキストを含む詳細な商品レベルのエクスポート（注文1件あたり約2秒）。経費追跡や会計に最適です。

出荷 (export_amazon_shipments_csv)

出荷と追跡情報（注文1件あたり約4秒、fetch_tracking_numbers を使用すると+2秒）。配送追跡に最適です。

⚠️ 重要提示

fetch_tracking_numbers: true を設定すると、出荷追跡ページにアクセスし、実際の運送会社の追跡ID（例："AZ218181365JE"）と運送会社名を抽出します。このオプションを使用しない場合、Amazonの内部追跡URLのみが取得されます。

取引 (export_amazon_transactions_csv)

財務調整のための支払い取引の詳細情報です。

ギフトカード (export_amazon_gift_cards_csv)

ギフトカードのアクティビティと残高履歴です。

追加ツール

クエリツール

取引ページ (get_amazon_transactions)

Amazonの専用取引ページ（/cpe/yourpayments/transactions）からすべての支払い取引を抽出します。個々の注文ページから抽出するよりもはるかに高速です。

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

ギフトカード残高 (get_amazon_gift_card_balance)

/gc/balance から現在のAmazonギフトカードの残高と最近のアクティビティを取得します。

{
  "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 が有効になっている場合、これによりタイムアウトをリセットすることができます。

進捗通知

サーバーは抽出中に進捗通知を送信します。

• 注文 X/Y (注文ID) - 予想残り時間: ~X分 X秒 これらの通知は進捗を追跡するのに役立ち、設定に応じてクライアントのタイムアウトをリセットすることができます。

開発

# 開発モードで実行
npm run dev

# テストを実行
npm test

# 型チェック
npm run typecheck

# リント
npm run lint

MCPインスペクターでのテスト

開発やデバッグには、AIアシスタントを介さずに公式の MCPインスペクター ツールを使用します。これにより以下のことが可能になります。

• 直接的なツール呼び出し：カスタムパラメータでMCPツールを直接呼び出す
• リアルタイムのレスポンス表示：AIによる解釈なしで完全なJSONレスポンスを表示する
• 高速な反復開発：AIがリクエストを処理するのを待たない
• デバッグ可視性：生のサーバー出力とエラーを表示する

クイックスタート

# MCPインスペクターをグローバルにインストール
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、日付、通貨、ブラウザ自動化のための共有ユーティリティ
• プラットフォームプラグイン：Amazon固有の抽出ロジック（将来的にはeBay、AliExpressなど）

詳細なアーキテクチャドキュメントについては AGENTS.md を参照してください。

関連プロジェクト

• QuickFile MCP - QuickFile UK会計ソフトウェア用のMCPサーバー。Amazonの注文エクスポートをQuickFileで使用して経費追跡やVAT調整を行うことができます。
• OpenCode - MCPサポートを備えたオープンソースのAIコーディングアシスタント
• QuickFile - 英国の会計ソフトウェア
• QuickFile API - QuickFile APIのドキュメント
• Model Context Protocol - AIツール統合のためのプロトコル仕様
• AI DevOps Framework - 包括的なAIインフラストラクチャ管理

クレジット

このプロジェクトは、Amazon注文履歴エクスポート用のChrome拡張機能である AZAD から着想を得ています。これはMCPサーバーとして独自に実装されたもので、フォークや派生作品ではありません。 完全な謝辞については CREDITS.md を参照してください。

📄 ライセンス

MITライセンス - 詳細については LICENSE を参照してください。

コントリビューション

コントリビューションを歓迎します！開発ガイドラインについては AGENTS.md を読んでください。