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
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_appointmentsOne 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/mcpSet it up in your clientBoth 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.
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
Name Type Required widgetIdstringYes unitTokenstringYes variationIdstringYes options{ from?: string; to?: string; staffId?: string }No Returns
SquareAvailabilityinterface 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/checkAvailabilityCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.checkAvailability("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0", "IHCY2Q7PBBH4VVSIL2XU5GQ3");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.checkAvailability("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0", "IHCY2Q7PBBH4VVSIL2XU5GQ3"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/checkAvailability \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"7o7ufdywy6ks8m","unitToken":"L6SCQ3SAWHBV0","variationId":"IHCY2Q7PBBH4VVSIL2XU5GQ3"}'// The body of a run: the MCP run tool, or POST /v1/run return 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
Name Type Required querystringYes Returns
SquareBusinessSearchinterface 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/findBusinessCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.findBusiness("Matt The Barber");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.findBusiness("Matt The Barber"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/findBusiness \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"Matt The Barber"}'// The body of a run: the MCP run tool, or POST /v1/run return 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
Name Type Required reservationIdstringYes Returns
SquareReservationinterface 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/getBookingCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.getBooking("deadbeef-0000-0000-0000-000000000000");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.getBooking("deadbeef-0000-0000-0000-000000000000"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/getBooking \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"reservationId":"deadbeef-0000-0000-0000-000000000000"}'// The body of a run: the MCP run tool, or POST /v1/run return 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
Name Type Required widgetIdstringYes unitTokenstringYes Returns
SquareBusinessinterface 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/getBusinessCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.getBusiness("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.getBusiness("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/getBusiness \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"7o7ufdywy6ks8m","unitToken":"L6SCQ3SAWHBV0"}'// The body of a run: the MCP run tool, or POST /v1/run return 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
Name Type Required widgetIdstringYes unitTokenstringYes serviceIdstringYes Returns
SquareServiceDetailinterface 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/getServiceCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.getService("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0", "GNVMVUMRI34QIG4A5VAZSI6W");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.getService("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0", "GNVMVUMRI34QIG4A5VAZSI6W"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/getService \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"7o7ufdywy6ks8m","unitToken":"L6SCQ3SAWHBV0","serviceId":"GNVMVUMRI34QIG4A5VAZSI6W"}'// The body of a run: the MCP run tool, or POST /v1/run return 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
Name Type Required widgetIdstringYes unitTokenstringYes Returns
SquareCategoryListinterface 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/listCategoriesCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.listCategories("0hg1pywsjxip1e", "L39VM6FNQ10DZ");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.listCategories("0hg1pywsjxip1e", "L39VM6FNQ10DZ"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/listCategories \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"0hg1pywsjxip1e","unitToken":"L39VM6FNQ10DZ"}'// The body of a run: the MCP run tool, or POST /v1/run return 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
Name Type Required widgetIdstringYes unitTokenstringYes options{ from?: string; to?: string }No Returns
SquareClassListinterface 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/listClassesCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.listClasses("dbxnsnhz4o8sgo", "LNP1NS5RTEX5E");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.listClasses("dbxnsnhz4o8sgo", "LNP1NS5RTEX5E"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/listClasses \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"dbxnsnhz4o8sgo","unitToken":"LNP1NS5RTEX5E"}'// The body of a run: the MCP run tool, or POST /v1/run return await bowmark.providers.square_appointments.listClasses("dbxnsnhz4o8sgo", "LNP1NS5RTEX5E");listCreditPacksLists the class credit packs the signed-in caller holds at a business.Arguments
Name Type Required widgetIdstringYes unitTokenstringYes Returns
SquareCreditPackListinterface 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/listCreditPacksCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.listCreditPacks("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.listCreditPacks("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/listCreditPacks \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"7o7ufdywy6ks8m","unitToken":"L6SCQ3SAWHBV0"}'// The body of a run: the MCP run tool, or POST /v1/run return 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
Name Type Required widgetIdstringYes unitTokenstringYes Returns
SquareLocationListinterface 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/listLocationsCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.listLocations("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.listLocations("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/listLocations \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"7o7ufdywy6ks8m","unitToken":"L6SCQ3SAWHBV0"}'// The body of a run: the MCP run tool, or POST /v1/run return await bowmark.providers.square_appointments.listLocations("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");listMyBookingsLists the signed-in caller's upcoming or past appointments at a business.Arguments
Name Type Required widgetIdstringYes unitTokenstringYes options{ direction?: "upcoming" | "past"; offset?: number }No Returns
SquareReservationListinterface 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/listMyBookingsCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.listMyBookings("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.listMyBookings("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/listMyBookings \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"7o7ufdywy6ks8m","unitToken":"L6SCQ3SAWHBV0"}'// The body of a run: the MCP run tool, or POST /v1/run return await bowmark.providers.square_appointments.listMyBookings("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");listMyClassBookingsLists the signed-in caller's class bookings at a business.Arguments
Name Type Required widgetIdstringYes unitTokenstringYes options{ direction?: "upcoming" | "past" }No Returns
SquareClassBookingListinterface 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/listMyClassBookingsCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.listMyClassBookings("dbxnsnhz4o8sgo", "LNP1NS5RTEX5E");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.listMyClassBookings("dbxnsnhz4o8sgo", "LNP1NS5RTEX5E"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/listMyClassBookings \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"dbxnsnhz4o8sgo","unitToken":"LNP1NS5RTEX5E"}'// The body of a run: the MCP run tool, or POST /v1/run return 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
Name Type Required widgetIdstringYes unitTokenstringYes Returns
SquareServiceListinterface 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/listServicesCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.listServices("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.listServices("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/listServices \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"7o7ufdywy6ks8m","unitToken":"L6SCQ3SAWHBV0"}'// The body of a run: the MCP run tool, or POST /v1/run return 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
Name Type Required widgetIdstringYes unitTokenstringYes Returns
SquareStaffListinterface 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/listStaffCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.listStaff("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.listStaff("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/listStaff \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widgetId":"7o7ufdywy6ks8m","unitToken":"L6SCQ3SAWHBV0"}'// The body of a run: the MCP run tool, or POST /v1/run return await bowmark.providers.square_appointments.listStaff("7o7ufdywy6ks8m", "L6SCQ3SAWHBV0");
cancelBookingCancels one of the caller's appointments, where the business allows customers to cancel.Arguments
Name Type Required reservationIdstringYes occurrenceDateStartstringNo Returns
{ reservationId: string; cancelled: true }HTTP endpoint
POST https://api.bowmark.ai/v1/sites/square_appointments/cancelBookingCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.cancelBooking("<reservationId>");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.cancelBooking("<reservationId>"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/cancelBooking \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"reservationId":"<reservationId>"}'// The body of a run: the MCP run tool, or POST /v1/run return await bowmark.providers.square_appointments.cancelBooking("<reservationId>");cancelClassBookingCancels one of the signed-in caller's Square class bookings.Arguments
Name Type Required classBookingIdstringYes Returns
{ classBookingId: string; cancelled: true }HTTP endpoint
POST https://api.bowmark.ai/v1/sites/square_appointments/cancelClassBookingCall it
import { bowmark } from "@bowmark/web"; const result = await bowmark.providers.square_appointments.cancelClassBooking("<classBookingId>");import asyncio from bowmark_web import bowmark result = asyncio.run(bowmark.providers.square_appointments.cancelClassBooking("<classBookingId>"))curl -X POST https://api.bowmark.ai/v1/sites/square_appointments/cancelClassBooking \ -H "Authorization: Bearer $BOWMARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"classBookingId":"<classBookingId>"}'// The body of a run: the MCP run tool, or POST /v1/run return await bowmark.providers.square_appointments.cancelClassBooking("<classBookingId>");
Use it from code
- Node
npm i @bowmark/web - Python
pip install bowmark-web - HTTP
POST /v1/sites/square_appointments/<function> - OpenAPI
/v1/sites/square_appointments/openapi.json