Instacart MCP Server

Instructions

Implementation Reference

• src/index.ts:369-433 (handler)

  Tool handler for instacart_place_order - validates confirm parameter and either returns a preview or calls placeOrder function. Ensures explicit user confirmation before placing order.

  case "instacart_place_order": {
    const { confirm = false } = args as { confirm?: boolean };
  
    if (!confirm) {
      const preview = await previewOrder();
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                success: true,
                requiresConfirmation: true,
                preview,
                message:
                  "Order not placed. To place the order, call instacart_place_order with confirm=true. " +
                  "IMPORTANT: Only do this after getting explicit user confirmation.",
              },
              null,
              2
            ),
          },
        ],
      };
    }
  
    const result = await placeOrder(true);
  
    if ("requiresConfirmation" in result) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                success: false,
                requiresConfirmation: result.requiresConfirmation,
                preview: result.preview,
              },
              null,
              2
            ),
          },
        ],
      };
    }
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              success: true,
              orderPlaced: true,
              confirmation: result,
              message: `Order ${result.orderId} placed successfully! Estimated delivery: ${result.estimatedDelivery}`,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/index.ts:143-156 (registration)

  Tool registration and schema definition for instacart_place_order. Defines the input schema with the confirm boolean parameter and detailed description about user confirmation requirement.

    name: "instacart_place_order",
    description:
      "Place the order. IMPORTANT: Set confirm=true only when you have explicit user confirmation. Without confirm=true, this returns a preview instead of placing the order.",
    inputSchema: {
      type: "object",
      properties: {
        confirm: {
          type: "boolean",
          description:
            "Set to true to actually place the order. If false or omitted, returns a preview instead. NEVER set to true without explicit user confirmation.",
        },
      },
    },
  },

• src/browser.ts:499-557 (handler)

  Core placeOrder implementation - performs browser automation to checkout, verifies order can be placed, clicks place order button, waits for confirmation page, and extracts order details (orderId, estimatedDelivery, total, storeName).

  export async function placeOrder(confirmPlacement: boolean): Promise<OrderConfirmation | { requiresConfirmation: true; preview: Awaited<ReturnType<typeof previewOrder>> }> {
    if (!confirmPlacement) {
      const preview = await previewOrder();
      return {
        requiresConfirmation: true,
        preview,
      };
    }
  
    const { page, context } = await initBrowser();
  
    try {
      // Navigate to checkout
      await page.goto(`${INSTACART_BASE_URL}/store/checkout`, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
      await page.waitForTimeout(2000);
  
      // Verify we can place order
      const preview = await previewOrder();
      if (!preview.canPlace) {
        throw new Error(`Cannot place order: ${preview.issues?.join(", ") || "Unknown issue"}`);
      }
  
      // Click place order button
      const placeOrderButton = await page.$(
        '[data-testid="place-order"], button:has-text("Place order"), button:has-text("Submit order")'
      );
  
      if (!placeOrderButton) {
        throw new Error("Could not find place order button");
      }
  
      await placeOrderButton.click();
  
      // Wait for confirmation page
      await page.waitForURL(/\/orders\/|\/confirmation/, { timeout: 30000 });
      await page.waitForTimeout(2000);
  
      // Extract order confirmation details
      const confirmation = await page.evaluate(() => {
        const orderIdEl = document.querySelector('[data-testid="order-id"], [class*="OrderId"]');
        const deliveryEl = document.querySelector('[data-testid="estimated-delivery"], [class*="EstimatedDelivery"]');
        const totalEl = document.querySelector('[data-testid="order-total"], [class*="OrderTotal"]');
        const storeEl = document.querySelector('[data-testid="store-name"], [class*="StoreName"]');
  
        return {
          orderId: orderIdEl?.textContent?.trim() || "Unknown",
          estimatedDelivery: deliveryEl?.textContent?.trim() || "Unknown",
          total: totalEl?.textContent?.trim() || "Unknown",
          storeName: storeEl?.textContent?.trim() || "Unknown",
        };
      });
  
      await saveCookies(context);
  
      return confirmation;
    } catch (error) {
      throw new Error(`Failed to place order: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/browser.ts:53-58 (schema)

  OrderConfirmation type definition - defines the structure of the order confirmation response with orderId, estimatedDelivery, total, and storeName fields.

  export interface OrderConfirmation {
    orderId: string;
    estimatedDelivery: string;
    total: string;
    storeName: string;
  }