SpotHopper MCP server for AI agents

Let Claude, ChatGPT or your own agent read and act on SpotHopper: 14 typed functions through one MCP server. No SpotHopper API key needed.

Functions
14
Sign-in
Not needed
Works with
MCP, HTTP, Node, Python

Connect

Just SpotHopper

An MCP server for SpotHopper 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/spotapps
Every site

One MCP server for SpotHopper 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

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

Read 8
  • checkAvailabilityChecks whether a restaurant has a table for a party size at a date and time, and returns the alternative times it offers when it does not.

    Arguments

    NameTypeRequired
    spotIdstringYes
    partySizenumberYes
    datestring
    "YYYY-MM-DD".
    Yes
    timestring
    Exactly as the widget prints it, e.g. "7:00 PM".
    Yes

    Returns SpotappsAvailability

    interface SpotappsSlot {
      /** The widget's own time spelling, e.g. "7:00 PM". */
      time: string;
      nextDay: boolean;
    }
    
    interface SpotappsAvailability {
      spotId: string;
      date: string;
      time: string;
      partySize: number;
      available: boolean;
      alternativeTimes: SpotappsSlot[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/checkAvailability

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.checkAvailability({
      spotId: "61855",
      partySize: 2,
      date: "2026-12-15",
      time: "11:00 AM"
    });
  • findRestaurantFinds a SpotHopper restaurant's spot_id from its own website URL or name, by reading the tmt.spotapps.co/reservations?spot_id= link or the…

    Arguments

    NameTypeRequired
    urlstring
    The restaurant's own website, e.g. "barrelhousechicago.com".
    Yes

    Returns SpotappsRestaurant

    interface SpotappsRestaurant {
      spotId: string | null;
      name: string | null;
      /** Set when the site hands its reservations to OpenTable instead of the SpotHopper widget. */
      openTableRid: string | null;
      reservationsUrl: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/findRestaurant

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.findRestaurant({ url: "barrelhousechicago.com" });
  • getCateringOptionsReads a restaurant's catering inquiry form: whether it's open, party-size limits, fulfilment types (pick-up, delivery, fully staffed), occasions, and…

    Arguments

    NameTypeRequired
    spotIdstring
    The numeric id findRestaurant().spotId returns, e.g. "61855".
    Yes

    Returns SpotappsCateringOptions

    interface SpotappsSlot {
      /** The widget's own time spelling, e.g. "7:00 PM". */
      time: string;
      nextDay: boolean;
    }
    
    interface SpotappsInquirySettings {
      spotId: string;
      name: string | null;
      timeZone: string | null;
      active: boolean;
      minPartySize: number | null;
      maxPartySize: number | null;
      timeStepMinutes: number | null;
      instructions: string | null;
      contactPhone: string | null;
      occasions: string[];
      recommendedBudget: number | null;
      showBudget: boolean;
      textingPermissionsActive: boolean;
      textingPermissionLabel: string | null;
      /** Index 0 = Sunday .. 6 = Saturday, the site's own convention. */
      weekdaySlots: SpotappsSlot[][];
      dateSlots: { date: string; slots: SpotappsSlot[] }[];
      blockedDates: string[];
    }
    
    interface SpotappsCateringOptions extends SpotappsInquirySettings {
      /** The fulfilment modes the catering form offers, e.g. "Pick-up", "Delivery", "Fully Staffed". */
      cateringTypes: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/getCateringOptions

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.getCateringOptions({ spotId: "61855" });
  • getMenuReads a restaurant's menu as its contactless-menu page shows it: sections, items, descriptions and prices.

    Arguments

    NameTypeRequired
    spotIdstring
    The numeric id findRestaurant().spotId returns, e.g. "61855".
    Yes

    Returns SpotappsMenuResult

    interface SpotappsMenuItem {
      id: string;
      name: string;
      description: string | null;
      inStock: boolean;
      /** One per size; size is "" when the menu prints a single price column. */
      prices: { size: string; cents: number }[];
      labels: string[];
      imageUrls: string[];
    }
    
    interface SpotappsMenu<I = SpotappsMenuItem> {
      id: string;
      name: string;
      /** "food" | "drink". */
      menuType: string;
      description: string | null;
      sections: { id: string; name: string; description: string | null; items: I[] }[];
    }
    
    interface SpotappsMenuResult {
      spotId: string;
      name: string | null;
      timeZone: string | null;
      menus: SpotappsMenu[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/getMenu

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.getMenu({ spotId: "61855" });
  • getOnlineOrderMenuReads a restaurant's online-ordering menu: items, modifiers, prices, pickup/delivery options and hours.

    Arguments

    NameTypeRequired
    spotIdstring
    The numeric id findRestaurant().spotId returns, e.g. "61855".
    Yes

    Returns SpotappsOnlineOrderMenu

    interface SpotappsSlot {
      /** The widget's own time spelling, e.g. "7:00 PM". */
      time: string;
      nextDay: boolean;
    }
    
    interface SpotappsMenuItem {
      id: string;
      name: string;
      description: string | null;
      inStock: boolean;
      /** One per size; size is "" when the menu prints a single price column. */
      prices: { size: string; cents: number }[];
      labels: string[];
      imageUrls: string[];
    }
    
    interface SpotappsMenu<I = SpotappsMenuItem> {
      id: string;
      name: string;
      /** "food" | "drink". */
      menuType: string;
      description: string | null;
      sections: { id: string; name: string; description: string | null; items: I[] }[];
    }
    
    interface SpotappsOrderItem {
      id: string;
      /** Per-size id, e.g. "206510-189520", what a cart line names. */
      uniqueId: string;
      name: string;
      description: string | null;
      size: string;
      cents: number | null;
      inStock: boolean;
      availableForPickup: boolean;
      availableForDelivery: boolean;
      labels: string[];
      imageUrls: string[];
      /** The site's own modifier groups, passed through; null when none. */
      customizations: unknown;
    }
    
    interface SpotappsOnlineOrderMenu {
      spotId: string;
      name: string | null;
      timeZone: string | null;
      /** False when the widget takes no cart orders (the menu may still be listed). */
      cartActive: boolean;
      paymentActive: boolean;
      hasPickup: boolean;
      hasDelivery: boolean;
      openNowPickup: boolean;
      openNowDelivery: boolean;
      pickupFeeCents: number | null;
      deliveryFeeCents: number | null;
      minimumTurnaroundMinutes: { pickup: number | null; delivery: number | null };
      pickupTimeOptions: string[];
      deliveryTimeOptions: string[];
      /** Index 0 = Sunday .. 6 = Saturday. */
      pickupWeekdaySlots: SpotappsSlot[][];
      deliveryWeekdaySlots: SpotappsSlot[][];
      instructions: string | null;
      menus: SpotappsMenu<SpotappsOrderItem>[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/getOnlineOrderMenu

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.getOnlineOrderMenu({ spotId: "61855" });
  • getPrivatePartyOptionsReads a restaurant's private-party / event inquiry form: whether it's open, party-size limits, occasions, event spaces, and the bookable time slots…

    Arguments

    NameTypeRequired
    spotIdstring
    The numeric id findRestaurant().spotId returns, e.g. "61855".
    Yes

    Returns SpotappsPrivatePartyOptions

    interface SpotappsSlot {
      /** The widget's own time spelling, e.g. "7:00 PM". */
      time: string;
      nextDay: boolean;
    }
    
    interface SpotappsInquirySettings {
      spotId: string;
      name: string | null;
      timeZone: string | null;
      active: boolean;
      minPartySize: number | null;
      maxPartySize: number | null;
      timeStepMinutes: number | null;
      instructions: string | null;
      contactPhone: string | null;
      occasions: string[];
      recommendedBudget: number | null;
      showBudget: boolean;
      textingPermissionsActive: boolean;
      textingPermissionLabel: string | null;
      /** Index 0 = Sunday .. 6 = Saturday, the site's own convention. */
      weekdaySlots: SpotappsSlot[][];
      dateSlots: { date: string; slots: SpotappsSlot[] }[];
      blockedDates: string[];
    }
    
    interface SpotappsPrivatePartyOptions extends SpotappsInquirySettings {
      /** The site's own named event spaces, when it lists any; null when it does not. */
      eventSpaces: string[] | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/getPrivatePartyOptions

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.getPrivatePartyOptions({ spotId: "61855" });
  • getReservationSettingsReads one restaurant's reservation widget settings: whether online reservations are on, party-size limits, time step, auto-confirm, deposit or…

    Arguments

    NameTypeRequired
    spotIdstring
    The numeric id findRestaurant().spotId returns, e.g. "61855".
    Yes

    Returns SpotappsReservationSettings

    interface SpotappsSlot {
      /** The widget's own time spelling, e.g. "7:00 PM". */
      time: string;
      nextDay: boolean;
    }
    
    interface SpotappsReservationSettings {
      spotId: string;
      name: string | null;
      timeZone: string | null;
      active: boolean;
      minPartySize: number | null;
      maxPartySize: number | null;
      timeStepMinutes: number | null;
      autoConfirm: boolean;
      requiresDeposit: boolean;
      hasCancelationFee: boolean;
      instructions: string | null;
      /** Index 0 = Sunday .. 6 = Saturday, the site's own convention. */
      weekdaySlots: SpotappsSlot[][];
      dateSlots: { date: string; slots: SpotappsSlot[] }[];
      blockedDates: string[];
    
      checkout: SpotappsCheckout | null;
    }
    
    interface SpotappsCheckout {
      status: "ready_to_checkout" | "needs_login" | "unavailable";
      /** Always https, on the studio's own site. */
      url: string;
      /** ready_to_checkout only: carries_items opens this very slot, product_page opens the studio's schedule. */
      urlKind?: "carries_items" | "signed_in_cart" | "product_page";
      /** unavailable only: out_of_stock (class full, no waitlist) or not_available_for_dates (cancelled). */
      reason?: string;
      detail?: string;
      account: { site: string; hint: string; signedInAs?: string; signInUrl?: string };
      summary: {
        items: { title: string; variant: string | null; quantity: number; unitPrice: string | null; lineTotal: string | null; url?: string; id?: string }[];
        total: string | null;
        currency: string;
        /** ISO start/end of the class or slot, with the studio's UTC offset when the site gives one. */
        dates?: { start: string; end?: string };
      } | null;
      warnings: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/getReservationSettings

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.getReservationSettings({ spotId: "61855" });
  • listJobsReads a restaurant's job-application form: whether it's hiring, the position titles the form lets a candidate choose, and the application…

    Arguments

    NameTypeRequired
    spotIdstring
    The numeric id findRestaurant().spotId returns, e.g. "61855".
    Yes

    Returns SpotappsJobListing

    interface SpotappsJobListing {
      spotId: string;
      name: string | null;
      /** True when the restaurant is accepting job applications right now. */
      hiring: boolean;
      instructions: string | null;
      contactPhone: string | null;
      /** The position titles the application form lets a candidate choose, SpotHopper
       * publishes no per-posting description or open-count here, only this category list. */
      positions: string[];
      allowPhotoUpload: boolean;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/listJobs

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.listJobs({ spotId: "61855" });
Act 6
  • applyForJobSubmits a job application (name, email, phone, positions, cover letter, experience, resume link) through the restaurant's widget.

    Arguments

    NameTypeRequired
    spotIdstringYes
    namestringYes
    emailstringYes
    phonestringYes
    positionsstring[]
    One or more of listJobs().positions.
    Yes
    coverLetterstringNo
    experiencestringNo
    cvLinkstring
    A link to the applicant's resume; the widget's file upload is not wrapped.
    No

    Returns SpotappsJobApplication

    interface SpotappsJobApplication {
      spotId: string;
      positions: string[];
      /** The widget's own verdict on the submit, true means SpotHopper recorded the application. */
      accepted: boolean;
      applicationId: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/applyForJob

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.applyForJob({
      spotId: "<spotId>",
      name: "<name>",
      email: "<email>",
      phone: "<phone>",
      positions: []
    });
  • bookReservationSends a guest reservation request (name, email, phone, party size, date, time, notes) through the restaurant's widget; refuses to submit when a…

    Arguments

    NameTypeRequired
    spotIdstringYes
    datestring
    "YYYY-MM-DD".
    Yes
    timestring
    Exactly as the widget prints it.
    Yes
    partySizenumberYes
    firstNamestringYes
    lastNamestringYes
    emailstringYes
    phonestringYes
    instructionsstringNo
    spacestring
    Only meaningful when getReservationSettings().active spots offer space selection.
    No
    textingPermissionbooleanNo

    Returns SpotappsReservationRequest

    interface SpotappsReservationRequest {
      spotId: string;
      date: string;
      time: string;
      partySize: number;
      /** The widget's own verdict on the submit, true means the request was accepted. */
      accepted: boolean;
      inquiryId: string | null;
      /** From the spot's own settings: true means auto-confirmed, false means the restaurant still has to approve it. */
      autoConfirmed: boolean;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/bookReservation

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.bookReservation({
      spotId: "<spotId>",
      date: "<date>",
      time: "<time>",
      partySize: 1,
      firstName: "<firstName>",
      lastName: "<lastName>",
      email: "<email>",
      phone: "<phone>"
    });
  • joinMailingListSigns an email (and optionally a phone, for texts) up for a restaurant's mailing list through its widget.

    Arguments

    NameTypeRequired
    spotIdstringYes
    emailstringYes
    phonestringNo
    textingPermissionboolean
    Opt the phone into the spot's texting list; needs phone, refused where the spot runs none.
    No

    Returns SpotappsMailingListSignup

    interface SpotappsMailingListSignup {
      spotId: string;
      email: string;
      phone: string | null;
      textingPermission: boolean;
      /** True when SpotHopper answered the submit with a 2xx, the widget reads nothing more back. */
      accepted: boolean;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/joinMailingList

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.joinMailingList({ spotId: "<spotId>", email: "<email>" });
  • requestCateringSends a catering inquiry (date, time, guest count, fulfilment type, contact details) through the restaurant's widget.

    Arguments

    NameTypeRequired
    argsSpotappsCateringArgsYes
    interface SpotappsInquiryArgs {
      spotId: string;
      /** "YYYY-MM-DD". */
      date: string;
      /** Exactly as the widget prints it, read one off the matching get…Options() weekdaySlots or dateSlots. */
      time: string;
      partySize: number;
      firstName: string;
      email: string;
      phone: string;
      occasion?: string;
      budget?: number | string;
      instructions?: string;
      textingPermission?: boolean;
    }
    
    interface SpotappsCateringArgs extends SpotappsInquiryArgs {
      /** One of getCateringOptions().cateringTypes, e.g. "Pick-up". */
      cateringType?: string;
      address?: string;
    }

    Returns SpotappsInquiryRequest

    interface SpotappsInquiryRequest {
      spotId: string;
      date: string;
      time: string;
      partySize: number;
      /** The widget's own verdict on the submit, true means SpotHopper recorded the inquiry. */
      accepted: boolean;
      inquiryId: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/requestCatering

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.requestCatering("<args>");
  • requestPrivatePartySends a private-party / group-event inquiry (date, time, guest count, occasion, budget, contact details) through the restaurant's widget.

    Arguments

    NameTypeRequired
    argsSpotappsPrivatePartyArgsYes
    interface SpotappsInquiryArgs {
      spotId: string;
      /** "YYYY-MM-DD". */
      date: string;
      /** Exactly as the widget prints it, read one off the matching get…Options() weekdaySlots or dateSlots. */
      time: string;
      partySize: number;
      firstName: string;
      email: string;
      phone: string;
      occasion?: string;
      budget?: number | string;
      instructions?: string;
      textingPermission?: boolean;
    }
    
    interface SpotappsPrivatePartyArgs extends SpotappsInquiryArgs {
      /** One of getPrivatePartyOptions().eventSpaces, when the spot lists any. */
      space?: string;
    }

    Returns SpotappsInquiryRequest

    interface SpotappsInquiryRequest {
      spotId: string;
      date: string;
      time: string;
      partySize: number;
      /** The widget's own verdict on the submit, true means SpotHopper recorded the inquiry. */
      accepted: boolean;
      inquiryId: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/requestPrivateParty

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.requestPrivateParty("<args>");
  • startOnlineOrderStarts a scheduled pickup order on a restaurant's online-ordering widget and stops at the payment step; refuses spots that take payment at pickup…

    Arguments

    NameTypeRequired
    spotIdstringYes
    items{ uniqueId: string; quantity: number }[]
    UniqueId off getOnlineOrderMenu().menus[].sections[].items[]; items needing options are refused.
    Yes
    datestring
    YYYY-MM-DD; a scheduled pickup.
    Yes
    timestring
    One of getOnlineOrderMenu().pickupWeekdaySlots for that weekday, e.g. "12:00 PM".
    Yes
    firstNamestringYes
    lastNamestringYes
    emailstringYes
    phonestringYes
    instructionsstringNo

    Returns SpotappsOnlineOrderStart

    interface SpotappsOnlineOrderStart {
      spotId: string;
      /** The order code SpotHopper issued; the order waits on payment. */
      orderCode: string;
      /** Always true: stops before payment, nothing is charged or sent to the kitchen. */
      paymentRequired: true;
      subtotalCents: number;
      checkout: SpotappsCheckoutHandoff;  // a refusal listing the items to order again on the restaurant's ordering page (no link reopens the order); Bowmark never pays
    }
    
    // The checkout handoff: where the PERSON finishes. Bowmark never pays, books or orders.
    // Switch on `status`; a status you do not recognise means "show the person `url` and stop".
    interface SpotappsCheckoutHandoff {
      status: "ready_to_checkout" | "needs_login" | "unavailable";
      url: string;                       // the https page to open on the site
      urlKind?: "carries_items" | "signed_in_cart" | "product_page"; // ready_to_checkout only: does the link carry the items, or only open the item's page
      reason?: string;                   // unavailable only: out_of_stock | not_available_for_dates | not_sold_online | region_not_served | quantity_unavailable | empty_cart
      detail?: string;                   // unavailable only: one sentence saying why
      account: { site: string; hint: string; signedInAs?: string };
      summary: { items: { title: string; variant: string | null; quantity: number; unitPrice: string | null; lineTotal: string | null; url?: string; id?: string }[]; total: string | null; currency: string } | null;
      warnings: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotapps/startOnlineOrder

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotapps.startOnlineOrder({
      spotId: "<spotId>",
      items: {},
      date: "<date>",
      time: "<time>",
      firstName: "<firstName>",
      lastName: "<lastName>",
      email: "<email>",
      phone: "<phone>"
    });

Use it from code