Amazon Order History CSV Download MCP

Instructions

Implementation Reference

• src/index.ts:301-344 (registration)

  Tool registration in the MCP tools array, including name, description, and complete input schema
  { name: "export_amazon_shipments_csv", description: "Export Amazon shipment tracking data to CSV file. Visits each order's detail page to extract tracking info (~4s/order). CSV columns: Order ID, Date, Shipment ID, Status, Delivered (Yes/No/Unknown), Tracking ID, Tracking URL, Items in Shipment, Item Names, Payment Amount, Refund. Useful for tracking deliveries and reconciling shipments.", 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}-shipments-{year}-{date}.csv", }, max_orders: { type: "number", description: "Maximum number of orders to process. Recommended: 25-50 per batch due to ~4s/order extraction time.", }, fetch_tracking_numbers: { type: "boolean", description: "Extract actual carrier tracking numbers (e.g., AZ218181365JE) by visiting each shipment's 'Track package' page. Adds ~2s per shipment.", default: false, }, }, required: ["region"], }, },
• src/index.ts:1007-1083 (handler)

  MCP tool call handler (switch case) that validates input, fetches shipment data using fetchOrders with includeShipments=true, computes time estimate, exports via exportShipmentsCSV, and returns result with file path
  case "export_amazon_shipments_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 fetchTrackingNumbers = args?.fetch_tracking_numbers as | boolean | undefined; const outputPath = getOutputPath( args?.output_path as string | undefined, "shipments", region, { year, startDate, endDate }, ); const fetchResult = await fetchOrders(currentPage, amazonPlugin, { region, year, startDate, endDate, includeItems: false, includeShipments: true, fetchTrackingNumbers: fetchTrackingNumbers ?? false, maxOrders, }); const timeEstimate = estimateExtractionTime(fetchResult.orders.length, { includeItems: false, includeShipments: true, }); const exportResult = await exportShipmentsCSV( fetchResult.shipments, outputPath, ); return { content: [ { type: "text", text: JSON.stringify( { status: exportResult.success ? "success" : "error", params: { region, year, startDate, endDate, maxOrders, fetchTrackingNumbers, outputPath, }, filePath: exportResult.filePath, rowCount: exportResult.rowCount, error: exportResult.error, fetchErrors: fetchResult.errors, timing: { orderCount: fetchResult.orders.length, shipmentCount: fetchResult.shipments.length, estimate: timeEstimate.formattedEstimate, warnings: timeEstimate.warnings, recommendations: timeEstimate.recommendations, }, }, null, 2, ), }, ], }; }
• src/tools/export-csv.ts:87-107 (handler)

  Primary handler function that formats the shipment data into CSV using predefined columns and writes the file to disk
  export async function exportShipmentsCSV( shipments: Shipment[], outputPath: string, ): Promise<ExportResult> { try { const csv = toCSVWithColumns(shipments, SHIPMENT_CSV_COLUMNS); await writeFile(outputPath, csv, "utf-8"); return { success: true, filePath: outputPath, rowCount: shipments.length, }; } catch (error) { return { success: false, filePath: outputPath, rowCount: 0, error: String(error), }; }
• src/tools/csv-columns.ts:317-366 (helper)

  Helper defining the exact CSV column structure, headers, and value extraction logic for shipment exports
  export const SHIPMENT_CSV_COLUMNS: CSVColumn<Shipment>[] = [ { key: "orderId", header: "Order ID", getValue: (s) => s.orderHeader.id }, { key: "orderDate", header: "Order Date", getValue: (s) => formatDate(s.orderHeader.date), }, { key: "shipmentId", header: "Shipment ID", getValue: (s) => s.shipmentId }, { key: "status", header: "Status", getValue: (s) => s.status }, { key: "delivered", header: "Delivered", getValue: (s) => { switch (s.delivered) { case DeliveryStatus.YES: return "Yes"; case DeliveryStatus.NO: return "No"; default: return "Unknown"; } }, }, { key: "trackingId", header: "Tracking ID", getValue: (s) => s.trackingId }, { key: "carrier", header: "Carrier", getValue: (s) => s.carrier || "" }, { key: "trackingLink", header: "Tracking URL", getValue: (s) => s.trackingLink, }, { key: "itemCount", header: "Items in Shipment", getValue: (s) => s.items.length, }, { key: "itemNames", header: "Item Names", getValue: (s) => s.items.map((i) => i.name).join("; "), }, { key: "paymentAmount", header: "Payment Amount", getValue: (s) => formatMoney(s.transaction?.paymentAmount) || formatMoney(s.orderHeader.total), }, { key: "refund", header: "Refund", getValue: (s) => formatMoney(s.refund) }, { key: "region", header: "Region", getValue: (s) => s.orderHeader.region }, ];