Amazon Order History CSV Download MCP

Instructions

Implementation Reference

• src/index.ts:225-261 (registration)

  Tool registration: defines name, description, and input schema for 'export_amazon_orders_csv'
  { name: "export_amazon_orders_csv", description: "Export Amazon orders summary to CSV file. Fast extraction from order list page (~0.5s per 10 orders). CSV columns: Order ID, Date, Total, Status, Item Count, Address (7 lines), Subscribe & Save, Platform, Region, Order URL. Defaults to ~/Downloads with auto-generated filename. For large accounts (500+ orders), use max_orders to batch exports and avoid timeouts.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, year: { type: "number", description: "Year to export (defaults to current year)", }, start_date: { type: "string", description: "Start date in ISO format (YYYY-MM-DD)", }, end_date: { type: "string", description: "End date in ISO format (YYYY-MM-DD)", }, output_path: { type: "string", description: "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-orders-{year}-{date}.csv", }, max_orders: { type: "number", description: "Maximum number of orders to export. Recommended: 100-200 per batch for large accounts.", }, }, required: ["region"], },
• src/index.ts:841-913 (handler)

  MCP tool handler: validates input, fetches order headers from list pages (fast mode, no per-order details), estimates timing, exports to CSV, returns file path and metadata
  case "export_amazon_orders_csv": { const regionParam = args?.region as string | undefined; const regionError = validateRegion(regionParam, args); if (regionError) return regionError; const region = regionParam!; const currentPage = await getPage(); const year = args?.year as number | undefined; const startDate = args?.start_date as string | undefined; const endDate = args?.end_date as string | undefined; const maxOrders = args?.max_orders as number | undefined; const outputPath = getOutputPath( args?.output_path as string | undefined, "orders", region, { year, startDate, endDate }, ); const fetchResult = await fetchOrders(currentPage, amazonPlugin, { region, year, startDate, endDate, includeItems: false, includeShipments: false, maxOrders, }); // Calculate time estimate for informational purposes const timeEstimate = estimateExtractionTime(fetchResult.orders.length, { includeItems: false, includeShipments: false, }); const exportResult = await exportOrdersCSV( fetchResult.orders, outputPath, ); return { content: [ { type: "text", text: JSON.stringify( { status: exportResult.success ? "success" : "error", params: { region, year, startDate, endDate, maxOrders, outputPath, }, filePath: exportResult.filePath, rowCount: exportResult.rowCount, error: exportResult.error, fetchErrors: fetchResult.errors, // Include timing info for transparency timing: { orderCount: fetchResult.orders.length, estimate: timeEstimate.formattedEstimate, warnings: timeEstimate.warnings, recommendations: timeEstimate.recommendations, }, }, null, 2, ), }, ], }; }
• src/tools/export-csv.ts:35-56 (helper)

  Helper function to convert order data to CSV using predefined columns and write to file
  export async function exportOrdersCSV( orders: OrderCSVData[], outputPath: string, ): Promise<ExportResult> { try { const csv = toCSVWithColumns(orders, ORDER_CSV_COLUMNS); await writeFile(outputPath, csv, "utf-8"); return { success: true, filePath: outputPath, rowCount: orders.length, }; } catch (error) { return { success: false, filePath: outputPath, rowCount: 0, error: String(error), }; } }
• src/tools/export-csv.ts:236-322 (helper)

  Helper to estimate extraction time and generate warnings/recommendations based on order count and extraction mode (used for transparency in handler response)
  export function estimateExtractionTime( orderCount: number, options: { includeItems?: boolean; includeShipments?: boolean; useInvoice?: boolean; } = {}, ): TimeEstimate { const { includeItems = false, includeShipments = false, useInvoice = true, } = options; // Calculate base time let timePerOrder = TIME_PER_ORDER.listOnly; if (includeItems || includeShipments) { if (includeShipments) { timePerOrder = TIME_PER_ORDER.withShipments; } else if (useInvoice) { timePerOrder = TIME_PER_ORDER.invoiceExtraction; } else { timePerOrder = TIME_PER_ORDER.detailExtraction; } } // Add overhead for pagination (roughly 2 seconds per 10 orders for page loads) const paginationOverhead = Math.ceil(orderCount / 10) * 2; const estimatedSeconds = Math.ceil( orderCount * timePerOrder + paginationOverhead, ); const estimatedMinutes = Math.ceil(estimatedSeconds / 60); const warnings: string[] = []; const recommendations: string[] = []; // Check against common timeouts if (estimatedSeconds > COMMON_TIMEOUTS.conservative) { if (estimatedSeconds > COMMON_TIMEOUTS.opencode) { warnings.push( `Estimated time (${estimatedMinutes}min) exceeds most client timeouts`, ); recommendations.push( `Consider using max_orders to limit batch size (e.g., max_orders: 100)`, ); recommendations.push( `Process in yearly batches for large order histories`, ); } else if (estimatedSeconds > COMMON_TIMEOUTS.cursor) { warnings.push( `Estimated time (${estimatedMinutes}min) may exceed some client timeouts`, ); recommendations.push( `If timeout occurs, try with max_orders: ${Math.floor(COMMON_TIMEOUTS.cursor / timePerOrder)}`, ); } else if (estimatedSeconds > COMMON_TIMEOUTS.claude) { warnings.push( `Estimated time (${estimatedMinutes}min) may exceed Claude Desktop timeout (2min)`, ); recommendations.push( `For Claude Desktop, consider max_orders: ${Math.floor(COMMON_TIMEOUTS.claude / timePerOrder)}`, ); } } // Format estimate string let formattedEstimate: string; if (estimatedSeconds < 60) { formattedEstimate = `~${estimatedSeconds} seconds`; } else if (estimatedMinutes < 60) { formattedEstimate = `~${estimatedMinutes} minutes`; } else { const hours = Math.floor(estimatedMinutes / 60); const mins = estimatedMinutes % 60; formattedEstimate = `~${hours}h ${mins}m`; } return { estimatedSeconds, estimatedMinutes, formattedEstimate, warnings, recommendations, }; }