Amazon Order History CSV Download MCP

Instructions

Implementation Reference

• src/tools/export-csv.ts:35-56 (handler)

  Core handler function that executes the CSV export logic: transforms OrderCSVData[] using predefined ORDER_CSV_COLUMNS and writes to the specified output file path.

  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/index.ts:226-262 (schema)

  Tool definition including name, description, and input schema for validation.

    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 dispatcher: validates parameters, fetches orders, generates output path, calls exportOrdersCSV, computes timing estimates, and returns JSON response with 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/csv-columns.ts:92-160 (helper)

  Defines the column structure and formatting functions for order CSV export, used by exportOrdersCSV.

  export const ORDER_CSV_COLUMNS: CSVColumn<OrderCSVData>[] = [
    // Identification
    { key: "orderId", header: "Order ID", getValue: (o) => o.id },
    { key: "date", header: "Order Date", getValue: (o) => formatDate(o.date) },
  
    // Financial - only Total is reliably available from list view
    { key: "total", header: "Total", getValue: (o) => formatMoney(o.total) },
  
    // Status
    { key: "status", header: "Status", getValue: (o) => o.status?.label || "" },
  
    // Items count (from order list page)
    {
      key: "itemCount",
      header: "Items",
      getValue: (o) => o.itemCount ?? o.items?.length ?? 0,
    },
  
    // Shipping address (up to 7 lines) - available from order card popover
    {
      key: "addressLine1",
      header: "Address Line 1",
      getValue: (o) => o.shippingAddress?.line1 || "",
    },
    {
      key: "addressLine2",
      header: "Address Line 2",
      getValue: (o) => o.shippingAddress?.line2 || "",
    },
    {
      key: "addressLine3",
      header: "Address Line 3",
      getValue: (o) => o.shippingAddress?.line3 || "",
    },
    {
      key: "addressLine4",
      header: "Address Line 4",
      getValue: (o) => o.shippingAddress?.line4 || "",
    },
    {
      key: "addressLine5",
      header: "Address Line 5",
      getValue: (o) => o.shippingAddress?.line5 || "",
    },
    {
      key: "addressLine6",
      header: "Address Line 6",
      getValue: (o) => o.shippingAddress?.line6 || "",
    },
    {
      key: "addressLine7",
      header: "Address Line 7",
      getValue: (o) => o.shippingAddress?.line7 || "",
    },
  
    // Subscribe & Save frequency (e.g., "Every 1 month")
    {
      key: "subscribeAndSave",
      header: "Subscribe & Save",
      getValue: (o) => o.subscribeAndSave || "",
    },
  
    // Platform/region
    { key: "platform", header: "Platform", getValue: (o) => o.platform || "" },
    { key: "region", header: "Region", getValue: (o) => o.region },
  
    // URL
    { key: "detailUrl", header: "Order URL", getValue: (o) => o.detailUrl },
  ];

• src/tools/export-csv.ts:327-343 (helper)

  Helper function to generate default output file path in ~/Downloads with descriptive filename based on region, type, and date range.

  export function getOutputPath(
    outputPath: string | undefined,
    exportType: "orders" | "items" | "shipments" | "transactions" | "gift-cards",
    region: string,
    options?: {
      year?: number;
      startDate?: string;
      endDate?: string;
    },
  ): string {
    if (outputPath) {
      return outputPath;
    }
  
    const filename = generateExportFilename(exportType, region, options);
    return join(getDefaultDownloadsPath(), filename);
  }