Instacart MCP server for AI agents

Let Claude, ChatGPT or your own agent read Instacart: 17 typed functions through one MCP server. No Instacart API key needed.

Functions
17
Sign-in
For account actions
Works with
MCP, HTTP, Node, Python

Connect

Just Instacart

An MCP server for Instacart alone, with one tool per function. Paste it into Claude, ChatGPT, Cursor or any MCP client as a remote server.

https://api.bowmark.ai/mcp/site/instacart
Every site

One MCP server for Instacart and every other site Bowmark covers. Your agent looks up what it needs and calls it.

https://api.bowmark.ai/mcp
Set it up in your client

Both need a Bowmark API key. The quickstart gets you one and a first result in a few minutes. Functions that need a login use the person's own account: how sign-in works.

Functions

Open a function to see its arguments, what it returns and how to call it.

Read 17
  • compareStoresSearches every store that serves a location at once ("milk" across Costco, Safeway, Aldi…) and returns the best matches per store with price, so an…

    Arguments

    NameTypeRequired
    querystringYes
    postalCodestringYes
    latitudenumberYes
    longitudenumberYes
    maxStoresnumber
    Default 10, max 30.
    No
    itemsPerStorenumber
    Default 5, max 20.
    No

    Returns InstacartCompareStoresResult

    interface InstacartStore {
      shopId: string;
      retailerId: string;
      slug: string;
      name: string;
      retailerType: string;
      serviceType: string;
      logoUrl: string | null;
    }
    
    interface InstacartItem {
      itemId: string;
      productId: string;
      name: string;
      size: string | null;
      brand: string | null;
      price: string | null;
      fullPrice: string | null;
      pricePerUnit: string | null;
      available: boolean | null;
      stockLevel: string | null;
      imageUrl: string | null;
    }
    
    interface InstacartStoreMatches {
      shopId: string;
      retailerId: string;
      store: InstacartStore | null;
      items: InstacartItem[];
    }
    
    interface InstacartCompareStoresResult {
      query: string;
      zoneId: string;
      stores: InstacartStoreMatches[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/compareStores

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.compareStores({
      query: "milk",
      postalCode: "94103",
      latitude: 37.77502,
      longitude: -122.41934,
      maxStores: 3,
      itemsPerStore: 2
    });
  • findLocationTurns a ZIP code or address text into the location every other Instacart function takes.

    Arguments

    NameTypeRequired
    querystringYes

    Returns InstacartLocation

    interface InstacartLocation {
      postalCode: string;
      latitude: number;
      longitude: number;
      city: string | null;
      state: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/findLocation

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.findLocation("94103");
  • getCartReturns one cart's contents: each item with quantity, price, any sale, and the cart's subtotal, fees and estimated total.

    Arguments

    NameTypeRequired
    cartIdstring
    From listCarts()[i].id.
    Yes

    Returns InstacartCart

    interface InstacartCartItem {
      itemId: string | null;
      productId: string | null;
      name: string | null;
      quantity: number | null;
      price: string | null;        // the site's own display string, e.g. "$4.99"
    }
    
    interface InstacartCart {
      id: string;
      retailer: string | null;
      items: InstacartCartItem[];
      subtotal: string | null;     // display string
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/getCart

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.getCart({ cartId: "1" });
  • getDeliveryEstimateSays how soon a store can deliver to, or have pickup ready at, a location.

    Arguments

    NameTypeRequired
    retailerIdstringYes
    postalCodestringYes
    latitudenumberYes
    longitudenumberYes
    serviceType"DELIVERY" | "PICKUP"
    Default both.
    No

    Returns InstacartDeliveryEstimate[]

    interface InstacartDeliveryEstimate {
      retailerId: string;
      serviceType: "DELIVERY" | "PICKUP";
      available: boolean;
      etaSeconds: number | null;
      etaString: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/getDeliveryEstimate

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.getDeliveryEstimate({
      retailerId: "5",
      postalCode: "94103",
      latitude: 37.77502,
      longitude: -122.41934,
      serviceType: "DELIVERY"
    });
  • getMyAccountReturns the signed-in customer's own account: id, name, email and phone.

    Arguments

    None.

    Returns InstacartAccount

    interface InstacartAccount {
      id: string;
      firstName: string | null;
      lastName: string | null;
      email: string | null;
      phone: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/getMyAccount

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.getMyAccount();
  • getProductReturns one product's detail: name, brand, size, category, description, ingredients, directions and warnings, plus.

    Arguments

    NameTypeRequired
    productIdstringNo
    itemIdstringNo
    shopIdstringNo
    postalCodestringYes
    latitudenumberYes
    longitudenumberYes

    Returns InstacartProduct

    interface InstacartItem {
      itemId: string;
      productId: string;
      name: string;
      size: string | null;
      brand: string | null;
      price: string | null;
      fullPrice: string | null;
      pricePerUnit: string | null;
      available: boolean | null;
      stockLevel: string | null;
      imageUrl: string | null;
    }
    
    interface InstacartProduct {
      productId: string;
      name: string;
      brand: string | null;
      size: string | null;
      category: string | null;
      description: string | null;
      sections: { kind: string; heading: string; text: string }[];
      ingredients: string | null;
      warnings: string | null;
      startingPrice: number | null;
      store: (InstacartItem & { shopId: string }) | null;
      dietaryLabels: string[];
      nutrition: { label: string; value: string; unit: string | null }[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/getProduct

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.getProduct({
      productId: "2798606",
      postalCode: "94103",
      latitude: 37.77502,
      longitude: -122.41934
    });
  • getStoreReturns one store by its Instacart slug ("costco", "safeway") at a location: shop id, retailer id, store type, service type and logo.

    Arguments

    NameTypeRequired
    slugstringYes
    postalCodestringYes
    latitudenumberYes
    longitudenumberYes

    Returns InstacartStore

    interface InstacartStore {
      shopId: string;
      retailerId: string;
      slug: string;
      name: string;
      retailerType: string;
      serviceType: string;
      logoUrl: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/getStore

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.getStore({
      slug: "costco",
      postalCode: "94103",
      latitude: 37.77502,
      longitude: -122.41934
    });
  • getStoreHoursReturns a store's opening hours for each day of a date range (default the next 7 days).

    Arguments

    NameTypeRequired
    shopIdstring
    A store's shop id, from listStores or getStore.
    Yes
    startDatestring
    First day, YYYY-MM-DD.
    No
    daysnumber
    Number of days from startDate, 1-14.
    No

    Returns InstacartStoreHoursDay[]

    interface InstacartStoreHoursDay {
      /** YYYY-MM-DD. */
      date: string;
      /** The site's own line, e.g. "Open 10am - 8:30pm". */
      hours: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/getStoreHours

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.getStoreHours({ shopId: "12" });
  • getWeeklyAdReturns the flyers (weekly ad / circular) a store is running now: name, the dates it runs, and each page as an image.

    Arguments

    NameTypeRequired
    shopIdstring
    A store's shop id, from listStores or getStore.
    Yes

    Returns InstacartWeeklyAd[]

    interface InstacartWeeklyAdPage {
      pageNumber: number;
      imageUrl: string;
      width: number | null;
      height: number | null;
    }
    
    interface InstacartWeeklyAd {
      id: string;
      /** The flyer's own name, e.g. "Warehouse Savings". */
      name: string;
      /** The flyer's tag, e.g. "monthly" or "weekly". */
      tag: string | null;
      /** ISO instant the flyer starts. */
      startsAt: string | null;
      /** ISO instant the flyer ends. */
      endsAt: string | null;
      /** The site's own date line, e.g. "Oct 19 - Nov 14". */
      dates: string | null;
      pages: InstacartWeeklyAdPage[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/getWeeklyAd

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.getWeeklyAd({ shopId: "12" });
  • listCartsLists the signed-in customer's open carts, one per store, with item count and subtotal.

    Arguments

    None.

    Returns InstacartCartSummary[]

    interface InstacartCartSummary {
      id: string;                  // pass to getCart as { cartId }
      retailer: string | null;     // the store this cart is at
      shopId: string | null;
      itemCount: number | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/listCarts

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.listCarts();
  • listDealsLists what is on sale at a store right now.

    Arguments

    NameTypeRequired
    shopIdstringYes
    postalCodestringYes
    latitudenumberYes
    longitudenumberYes
    maxDealsnumber
    Default 20, max 50.
    No

    Returns InstacartDeal[]

    interface InstacartItem {
      itemId: string;
      productId: string;
      name: string;
      size: string | null;
      brand: string | null;
      price: string | null;
      fullPrice: string | null;
      pricePerUnit: string | null;
      available: boolean | null;
      stockLevel: string | null;
      imageUrl: string | null;
    }
    
    interface InstacartDeal extends InstacartItem {
      saleLabel: string | null;
      offerLabel: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/listDeals

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.listDeals({
      shopId: "12",
      postalCode: "94103",
      latitude: 37.77502,
      longitude: -122.41934
    });
  • listDepartmentProductsLists the products in one store department or aisle by its slug, each with price and stock.

    Arguments

    NameTypeRequired
    shopIdstringYes
    slugstringYes
    postalCodestringYes
    latitudenumberYes
    longitudenumberYes
    maxProductsnumber
    Default 20, max 50.
    No

    Returns InstacartDepartmentProducts

    interface InstacartItem {
      itemId: string;
      productId: string;
      name: string;
      size: string | null;
      brand: string | null;
      price: string | null;
      fullPrice: string | null;
      pricePerUnit: string | null;
      available: boolean | null;
      stockLevel: string | null;
      imageUrl: string | null;
    }
    
    interface InstacartDepartmentProducts {
      departmentId: string;
      departmentName: string;
      slug: string;
      products: InstacartItem[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/listDepartmentProducts

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.listDepartmentProducts({
      shopId: "12",
      slug: "produce",
      postalCode: "94103",
      latitude: 37.77502,
      longitude: -122.41934
    });
  • listDepartmentsLists a store's top-level departments and aisles (Produce, Dairy & Eggs, Sales…) with the slug listDepartmentProducts and listDeals take.

    Arguments

    NameTypeRequired
    shopIdstringYes
    postalCodestringYes

    Returns InstacartDepartment[]

    interface InstacartDepartment {
      id: string;
      slug: string;
      name: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/listDepartments

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.listDepartments({ shopId: "12", postalCode: "94103" });
  • listMyAddressesLists the signed-in customer's saved delivery addresses with their ids, which cart, delivery-window and checkout calls take.

    Arguments

    None.

    Returns InstacartAddress[]

    interface InstacartAddress {
      id: string;                  // pass to updateAddress / deleteAddress
      streetAddress: string | null;
      apartment: string | null;
      city: string | null;
      state: string | null;
      postalCode: string | null;
      latitude: number | null;
      longitude: number | null;
      instructions: string | null; // the courier note saved on the address
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/listMyAddresses

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.listMyAddresses();
  • listOrdersThe signed-in customer's own Instacart orders, newest first.

    Arguments

    NameTypeRequired
    args{ limit?: number; cursor?: string }No

    Returns SignedInOrderPage

    interface SignedInOrder {
      id: string;               // the shop's own order id
      placedAt: string | null;  // ISO 8601 (YYYY-MM-DD when the shop gives only a date)
      status: string;           // the shop's own words; a cancelled or refunded order keeps them, the site's own labels, read the values off a result, never guess one from prose
      total: number | null;     // major units (dollars)
      currency: string | null;  // ISO 4217, e.g. "USD"
      merchant: string | null;  // the store or restaurant
      itemCount: number | null;
      url: string;              // the order's own page
    }
    
    interface SignedInOrderPage {
      orders: SignedInOrder[];   // newest first
      nextCursor: string | null; // pass back as { cursor } for older orders
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/listOrders

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.listOrders();
  • listStoresLists the stores Instacart serves at a location.

    Arguments

    NameTypeRequired
    postalCodestringYes
    latitudenumberYes
    longitudenumberYes

    Returns InstacartStore[]

    interface InstacartStore {
      shopId: string;
      retailerId: string;
      slug: string;
      name: string;
      retailerType: string;
      serviceType: string;
      logoUrl: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/listStores

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.listStores({
      postalCode: "94103",
      latitude: 37.77502,
      longitude: -122.41934
    });
  • suggestSearchesReturns Instacart's search-as-you-type suggestions for a partial query at one store ("chee" → "cheez its").

    Arguments

    NameTypeRequired
    querystring
    What the shopper has typed so far, e.g. "chee".
    Yes
    shopIdstring
    A store's shop id, from listStores or getStore.
    Yes

    Returns InstacartSearchSuggestion[]

    interface InstacartSearchSuggestion {
      term: string;
      retailerSlug: string | null;
      url: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/instacart/suggestSearches

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.instacart.suggestSearches({ query: "chee", shopId: "12" });

Use it from code