Amazon Order History CSV Download MCP

Instructions

Implementation Reference

• src/index.ts:915-1005 (handler)

  Top-level MCP tool handler for 'export_amazon_items_csv'. Validates region, fetches Amazon orders with detailed item extraction using fetchOrders, estimates processing time, generates output filename, exports items to CSV via exportItemsCSV, and returns success/error with timing info.
  case "export_amazon_items_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, "items", region, { year, startDate, endDate }, ); // Pre-estimate time for items extraction (slower due to invoice/detail page visits) const preEstimate = estimateExtractionTime(maxOrders || 100, { includeItems: true, includeShipments: false, useInvoice: true, }); // Warn if this might take a while if (preEstimate.warnings.length > 0) { console.error( `[export-items] Time estimate: ${preEstimate.formattedEstimate}`, ); console.error( `[export-items] Warnings: ${preEstimate.warnings.join(", ")}`, ); } const fetchResult = await fetchOrders(currentPage, amazonPlugin, { region, year, startDate, endDate, includeItems: true, includeShipments: false, maxOrders, }); // Calculate actual time estimate based on orders found const timeEstimate = estimateExtractionTime(fetchResult.orders.length, { includeItems: true, includeShipments: false, useInvoice: true, }); const exportResult = await exportItemsCSV( fetchResult.items, 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, timing: { orderCount: fetchResult.orders.length, itemCount: fetchResult.items.length, estimate: timeEstimate.formattedEstimate, warnings: timeEstimate.warnings, recommendations: timeEstimate.recommendations, }, }, null, 2, ), }, ], }; }
• src/tools/export-csv.ts:61-82 (handler)

  Core CSV export function for Amazon order items. Formats items using predefined ITEM_CSV_COLUMNS and writes to the specified output file path, returning export result.
  export async function exportItemsCSV( items: Item[], outputPath: string, ): Promise<ExportResult> { try { const csv = toCSVWithColumns(items, ITEM_CSV_COLUMNS); await writeFile(outputPath, csv, "utf-8"); return { success: true, filePath: outputPath, rowCount: items.length, }; } catch (error) { return { success: false, filePath: outputPath, rowCount: 0, error: String(error), }; } }
• src/index.ts:267-299 (schema)

  JSON Schema defining the input parameters for the tool: region (required, enum of Amazon regions), optional year/dates for filtering, output_path, and max_orders limit.
  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}-items-{year}-{date}.csv", }, max_orders: { type: "number", description: "Maximum number of orders to process. Recommended: 50-100 per batch due to ~2s/order extraction time.", }, }, required: ["region"], },
• src/index.ts:263-300 (registration)

  Tool registration entry in the MCP tools array, including name, detailed description, and input schema. Returned by listTools endpoint.
  { name: "export_amazon_items_csv", description: "Export detailed Amazon order items to CSV file. Visits each order's invoice page to extract item-level data (~2s/order). CSV columns: Order ID, Date, ASIN, Product Name, Condition, Quantity, Unit Price, Item Total, Seller, Subscribe & Save, Order financials (Subtotal, Shipping, Tax, VAT, Promotion, Total), Status, Address (7 lines), Payment Method, Product URL, Order URL, Region. Ideal for expense tracking, inventory analysis, or accounting exports.", 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}-items-{year}-{date}.csv", }, max_orders: { type: "number", description: "Maximum number of orders to process. Recommended: 50-100 per batch due to ~2s/order extraction time.", }, }, required: ["region"], }, },
• src/tools/csv-columns.ts:166-312 (helper)

  Helper defining CSV column configuration for item exports. Maps Item type fields (with order context) to CSV headers and value extractors, enabling structured output with order details, pricing, addresses, etc.
  export const ITEM_CSV_COLUMNS: CSVColumn<Item>[] = [ // Order identification { key: "orderId", header: "Order ID", getValue: (i) => i.orderHeader.id }, { key: "orderDate", header: "Order Date", getValue: (i) => formatDate(i.orderHeader.date), }, // Item identification { key: "asin", header: "ASIN", getValue: (i) => i.asin || "" }, { key: "name", header: "Product Name", getValue: (i) => i.name }, { key: "condition", header: "Condition", getValue: (i) => i.condition || "" }, // Item pricing { key: "quantity", header: "Quantity", getValue: (i) => i.quantity }, { key: "unitPrice", header: "Unit Price", getValue: (i) => formatMoney(i.unitPrice), }, { key: "totalPrice", header: "Item Total", getValue: (i) => formatMoney(i.totalPrice), }, // Seller info (name only - soldBy/suppliedBy require detail page) { key: "seller", header: "Seller", getValue: (i) => i.seller?.name || "" }, // Subscription { key: "subscriptionFrequency", header: "Subscribe & Save", getValue: (i) => i.subscriptionFrequency || "", }, // Order-level financial data { key: "orderSubtotal", header: "Order Subtotal", getValue: (i) => formatMoney(i.orderHeader.subtotal), }, { key: "orderShipping", header: "Order Shipping", getValue: (i) => formatMoney(i.orderHeader.shipping), }, { key: "orderTax", header: "Order Tax", getValue: (i) => formatMoney(i.orderHeader.tax), }, { key: "orderVat", header: "Order VAT", getValue: (i) => formatMoney(i.orderHeader.vat), }, { key: "orderPromotion", header: "Order Promotion", getValue: (i) => formatMoney(i.orderHeader.promotion), }, { key: "orderTotal", header: "Order Total", getValue: (i) => formatMoney(i.orderHeader.total), }, { key: "orderGrandTotal", header: "Order Grand Total", getValue: (i) => formatMoney(i.orderHeader.grandTotal), }, // Order status { key: "orderStatus", header: "Order Status", getValue: (i) => i.orderHeader.status?.label || "", }, // Recipient/shipping address (up to 7 lines) { key: "recipient", header: "Recipient", getValue: (i) => i.orderHeader.recipient || "", }, { key: "addressLine1", header: "Address Line 1", getValue: (i) => i.orderHeader.shippingAddress?.line1 || "", }, { key: "addressLine2", header: "Address Line 2", getValue: (i) => i.orderHeader.shippingAddress?.line2 || "", }, { key: "addressLine3", header: "Address Line 3", getValue: (i) => i.orderHeader.shippingAddress?.line3 || "", }, { key: "addressLine4", header: "Address Line 4", getValue: (i) => i.orderHeader.shippingAddress?.line4 || "", }, { key: "addressLine5", header: "Address Line 5", getValue: (i) => i.orderHeader.shippingAddress?.line5 || "", }, { key: "addressLine6", header: "Address Line 6", getValue: (i) => i.orderHeader.shippingAddress?.line6 || "", }, { key: "addressLine7", header: "Address Line 7", getValue: (i) => i.orderHeader.shippingAddress?.line7 || "", }, // Payment { key: "paymentMethod", header: "Payment Method", getValue: (i) => i.orderHeader.paymentMethod?.type || "", }, { key: "paymentLastFour", header: "Card Last 4", getValue: (i) => i.orderHeader.paymentMethod?.lastFour || "", }, // URLs { key: "productUrl", header: "Product URL", getValue: (i) => i.url || "" }, { key: "imageUrl", header: "Image URL", getValue: (i) => i.imageUrl || "" }, { key: "orderUrl", header: "Order URL", getValue: (i) => i.orderHeader.detailUrl, }, // Region { key: "region", header: "Region", getValue: (i) => i.orderHeader.region }, ];