Square Appointments MCP server for AI agents

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

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

Connect

Just Square Appointments

An MCP server for Square Appointments 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/square_appointments
Every site

One MCP server for Square Appointments 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 13
  • checkAvailabilityReturns the open appointment times for one or more services at a location between two dates, for a chosen staff member or anyone available.

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes
    variationIdstringYes
    options{ from?: string; to?: string; staffId?: string }No

    Returns SquareAvailability

    interface SquareOpenSlot {
      start: string;
      end: string;
      staffId: string | null;
    }
    
    interface SquareAvailability {
      unitToken: string;
      variationId: string;
      staffId: string | null;
      slots: SquareOpenSlot[];
    }

    HTTP endpoint

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

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.checkAvailability("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0", "IHCY2Q7PBBH4VVSIL2XU5GQ3");
  • findBusinessFinds Square Appointments businesses by name (a web search of Square's public booking pages), or resolves a booking link the caller holds, into the…

    Arguments

    NameTypeRequired
    querystringYes

    Returns SquareBusinessSearch

    interface SquareBusinessRef {
      widgetId: string;
      unitToken: string | null;
      name: string | null;
      url: string;
    }
    
    interface SquareBusinessSearch {
      query: string;
      businesses: SquareBusinessRef[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/findBusiness

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.findBusiness("Matt The Barber");
  • getBookingReturns one of the caller's appointments: services, staff, time, location, price and whether it can still be cancelled.

    Arguments

    NameTypeRequired
    reservationIdstringYes

    Returns SquareReservation

    interface SquareReservationSegment {
      variationId: string | null;
      employeeToken: string | null;
      anyAvailableTeamMember: boolean;
      serviceDurationSeconds: number | null;
    }
    
    interface SquareReservation {
      id: string;
      status: string;  // the site's own labels, read the values off a result, never guess one from prose
      dateStart: string;
      dateEnd: string | null;
      segments: SquareReservationSegment[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/getBooking

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.getBooking("deadbeef-0000-0000-0000-000000000000");
  • getBusinessReturns one business's profile and booking rules: name, locations and addresses, cancellation policy, whether customers may cancel, no-show…

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes

    Returns SquareBusiness

    interface SquareOpenHours {
      day: number;
      open: number;
      close: number;
    }
    
    interface SquareBusiness {
      widgetId: string;
      unitToken: string;
      name: string;
      phone: string | null;
      email: string | null;
      timezone: string;
      currency: string;
      address: { street: string | null; city: string | null; state: string | null; zip: string | null };
      hours: SquareOpenHours[];
      websiteUrl: string | null;
      bookingUrl: string;
      bookingMode: string;
      allowCustomerCancel: boolean;
      cancellationPolicy: string | null;
      bookingCutoffSeconds: number | null;
      futureBookingLimitSeconds: number | null;
      prepaymentMode: string;
      depositsEnabled: boolean;
      noShowProtection: boolean;
      waitlistEnabled: boolean;
      anyStaffBooking: boolean;
      giftCardUrl: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/getBusiness

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.getBusiness("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");
  • getServiceReturns one service with its variations, add-on modifiers, deposit and no-show fee, and the staff who perform it.

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes
    serviceIdstringYes

    Returns SquareServiceDetail

    interface SquareServiceModifier {
      id: string;
      name: string;
      priceCents: number | null;
    }
    
    interface SquareServiceModifierList {
      id: string;
      name: string;
      modifiers: SquareServiceModifier[];
    }
    
    interface SquareServiceVariationDetail {
      id: string;
      name: string;
      durationMinutes: number | null;
      priceCents: number | null;
      priceType: string;
      priceDescription: string | null;
      staffIds: string[];
      depositCents: number | null;
      depositPercentage: number | null;
      noShowFeeCents: number | null;
      noShowFeePercentage: number | null;
    }
    
    interface SquareServiceDetail {
      id: string;
      name: string;
      description: string | null;
      categoryId: string | null;
      currency: string;
      staffIds: string[];
      variations: SquareServiceVariationDetail[];
      modifierLists: SquareServiceModifierList[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/getService

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.getService("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0", "GNVMVUMRI34QIG4A5VAZSI6W");
  • listCategoriesLists the service categories a business groups its menu under, with how many services sit in each.

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes

    Returns SquareCategoryList

    interface SquareCategory {
      id: string;
      name: string;
      ordinal: number | null;
      parentId: string | null;
      serviceCount: number;
    }
    
    interface SquareCategoryList {
      widgetId: string;
      categories: SquareCategory[];
      uncategorizedServiceCount: number;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/listCategories

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.listCategories("0hg1pywsjxip1e", "L39VM6FNQ10DZ");
  • listClassesLists a business's scheduled classes (group sessions) by date, each joined with its name, length, price, instructor and open capacity.

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes
    options{ from?: string; to?: string }No

    Returns SquareClassList

    interface SquareClassSession {
      id: string;
      classScheduleId: string;
      name: string;
      description: string | null;
      startAt: string;
      durationMinutes: number | null;
      priceCents: number | null;
      currency: string | null;
      staffName: string | null;
      availableCapacity: number | null;
      cancelled: boolean;
    }
    
    interface SquareClassList {
      unitToken: string;
      classes: SquareClassSession[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/listClasses

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.listClasses("dbxnsnhz4o8sgo", "LNP1NS5RTEX5E");
  • listCreditPacksLists the class credit packs the signed-in caller holds at a business.

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes

    Returns SquareCreditPackList

    interface SquareCreditPack {
      id: string;
      creditPackageId: string;
      name: string | null;
      priceCents: number | null;
    }
    
    interface SquareCreditPackList {
      unitToken: string;
      creditPacks: SquareCreditPack[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/listCreditPacks

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.listCreditPacks("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");
  • listLocationsLists a business's active locations with address, map position and unit token, so a caller can pick the one to book at.

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes

    Returns SquareLocationList

    interface SquareLocation {
      unitToken: string;
      id: string;
      name: string;
      address: { street: string | null; city: string | null; state: string | null; zip: string | null };
      timezone: string;
      bookingUrl: string | null;
      websiteUrl: string | null;
      mapPosition: { lat: number; lng: number } | null;
    }
    
    interface SquareLocationList {
      widgetId: string;
      locations: SquareLocation[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/listLocations

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.listLocations("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");
  • listMyBookingsLists the signed-in caller's upcoming or past appointments at a business.

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes
    options{ direction?: "upcoming" | "past"; offset?: number }No

    Returns SquareReservationList

    interface SquareReservationSegment {
      variationId: string | null;
      employeeToken: string | null;
      anyAvailableTeamMember: boolean;
      serviceDurationSeconds: number | null;
    }
    
    interface SquareReservation {
      id: string;
      status: string;  // the site's own labels, read the values off a result, never guess one from prose
      dateStart: string;
      dateEnd: string | null;
      segments: SquareReservationSegment[];
    }
    
    interface SquareReservationList {
      unitToken: string;
      direction: "upcoming" | "past";
      reservations: SquareReservation[];
      hasMoreReservations: boolean;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/listMyBookings

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.listMyBookings("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");
  • listMyClassBookingsLists the signed-in caller's class bookings at a business.

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes
    options{ direction?: "upcoming" | "past" }No

    Returns SquareClassBookingList

    interface SquareClassBooking {
      id: string;
      classScheduleId: string;
      name: string;
      startAt: string;
      durationMinutes: number | null;
    }
    
    interface SquareClassBookingList {
      unitToken: string;
      direction: "upcoming" | "past";
      classBookings: SquareClassBooking[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/listMyClassBookings

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.listMyClassBookings("dbxnsnhz4o8sgo", "LNP1NS5RTEX5E");
  • listServicesLists a business's bookable services at a location: name, description, category, price, duration, and which staff perform each variation.

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes

    Returns SquareServiceList

    interface SquareServiceVariation {
      id: string;
      name: string;
      durationMinutes: number | null;
      priceCents: number | null;
      priceType: string;
      priceDescription: string | null;
      staffIds: string[];
      depositCents: number | null;
    }
    
    interface SquareService {
      id: string;
      name: string;
      description: string | null;
      categoryId: string | null;
      currency: string;
      staffIds: string[];
      variations: SquareServiceVariation[];
    }
    
    interface SquareServiceList {
      widgetId: string;
      unitToken: string;
      services: SquareService[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/listServices

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.listServices("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");
  • listStaffLists the staff a customer can book at a location, with name, short bio and the services each one performs.

    Arguments

    NameTypeRequired
    widgetIdstringYes
    unitTokenstringYes

    Returns SquareStaffList

    interface SquareStaffMember {
      id: string;
      name: string;
      firstName: string | null;
      lastName: string | null;
      bio: string | null;
      variationIds: string[];
    }
    
    interface SquareStaffList {
      widgetId: string;
      unitToken: string;
      staff: SquareStaffMember[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/listStaff

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.listStaff("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");
Act 2
  • cancelBookingCancels one of the caller's appointments, where the business allows customers to cancel.

    Arguments

    NameTypeRequired
    reservationIdstringYes
    occurrenceDateStartstringNo

    Returns { reservationId: string; cancelled: true }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/cancelBooking

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.cancelBooking("<reservationId>");
  • cancelClassBookingCancels one of the signed-in caller's Square class bookings.

    Arguments

    NameTypeRequired
    classBookingIdstringYes

    Returns { classBookingId: string; cancelled: true }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/square_appointments/cancelClassBooking

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.square_appointments.cancelClassBooking("<classBookingId>");

Use it from code