Amazon Order History CSV Download MCP

Instructions

Implementation Reference

• src/index.ts:263-300 (registration)

  Tool registration in MCP tools array, including full input schema, description, and parameters for region, dates, output path, and max_orders.
  { 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/index.ts:915-1005 (handler)

  Primary handler logic in MCP server: validates region, fetches orders including item details via fetchOrders, estimates time, exports to CSV via exportItemsCSV, returns file path and metadata.
  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 items: transforms Item array to CSV using predefined columns and writes to specified file path.
  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/tools/csv-columns.ts:166-312 (schema)

  Output schema: CSV column definitions for item exports, mapping Item fields (with order header context) to formatted CSV headers and values.
  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 }, ];