Booksy API and MCP server

• POST

  list_appointments

  Appointments in a date range with client, service, staff, time and status.

  read

  Lists appointments from your Booksy calendar between two days, in start order. Limit it to one staff member to see a single calendar. Each item has the client, service, staff member, start, end and status, and get_appointment returns the rest.

  POST /api/v1/booksy/list_appointments

  Input

  Input: list_appointments

  Parameter	Type	Description
  from required	date	First day, inclusive.
  to required	date	Last day, inclusive.
  staff_id	string	Only one staff member, from list_staff.
  cursor	string	Next page cursor from the previous call.

  Example response

  {
    "appointments": [
      {
        "appointment_id": "apt_58213904",
        "client": "Anna Novak",
        "service": "Haircut",
        "staff": "Tom",
        "start": "2026-10-12T10:00:00-04:00",
        "end": "2026-10-12T10:45:00-04:00",
        "status": "confirmed"
      },
      {
        "appointment_id": "apt_58213977",
        "client": "Mark Ellis",
        "service": "Beard trim",
        "staff": "Tom",
        "start": "2026-10-12T11:30:00-04:00",
        "end": "2026-10-12T12:00:00-04:00",
        "status": "confirmed"
      }
    ],
    "next_cursor": null
  }

• POST

  get_appointment

  One appointment: services, staff, price, client and notes.

  read

  Returns one appointment with its services, staff member, price, client and internal notes. Use it before changing an appointment.

  POST /api/v1/booksy/get_appointment

  Input

  Input: get_appointment

  Parameter	Type	Description
  appointment_id required	string	Appointment ID from list_appointments.

  Example response

  {
    "appointment_id": "apt_58213904",
    "client": {
      "client_id": "cl_1042",
      "name": "Anna Novak"
    },
    "services": [
      {
        "name": "Haircut",
        "price": 35
      }
    ],
    "staff": "Tom",
    "start": "2026-10-16T15:00:00-04:00",
    "end": "2026-10-16T15:45:00-04:00",
    "status": "confirmed",
    "note": "Prefers a scissor cut"
  }

• POST

  find_open_slots

  Free start times for a service on one day, based on working hours, breaks and time off.

  read

  Returns free start times for one service on one day, in time order. It follows working hours, breaks, time off and the duration and buffer set on the service. Limit it to one staff member or leave it open to anyone who offers the service.

  POST /api/v1/booksy/find_open_slots

  Input

  Input: find_open_slots

  Parameter	Type	Description
  service_id required	string	Service ID from list_services.
  date required	date	Day to check.
  staff_id	string	Only this staff member. Default: anyone who offers the service.

  Example response

  {
    "date": "2026-10-17",
    "service": "Haircut",
    "slots": [
      {
        "start": "2026-10-17T10:00:00-04:00",
        "staff_id": "stf_2291"
      },
      {
        "start": "2026-10-17T11:30:00-04:00",
        "staff_id": "stf_2291"
      }
    ]
  }

• POST

  list_clients

  Clients with contact details and last visit.

  read

  Lists clients from your client list with contact details and the date of the last visit. Search by name, email or phone, or keep only clients who have not visited for a number of days. Pages are cursor based.

  POST /api/v1/booksy/list_clients

  Input

  Input: list_clients

  Parameter	Type	Description
  query	string	Name, email or phone to search for.
  not_visited_days	integer	Only clients whose last visit is older than this many days.
  limit	integer	Page size. Default: 50.
  cursor	string	Next page cursor from the previous call.

  Example response

  {
    "clients": [
      {
        "client_id": "cl_1042",
        "name": "Anna Novak",
        "email": "anna@example.com",
        "last_visit": "2026-07-28"
      },
      {
        "client_id": "cl_1187",
        "name": "Mark Ellis",
        "email": "mark@example.com",
        "last_visit": "2026-07-30"
      }
    ],
    "next_cursor": null
  }

• POST

  get_client

  One client card: contact details, notes and appointment history.

  read

  Returns one client card with contact details, notes and past appointments, newest first. Look the client up by ID or by email.

  POST /api/v1/booksy/get_client

  Input

  Input: get_client

  Parameter	Type	Description
  client_id	string	Client ID from list_clients.
  email	string	Look up by email instead of ID.

  Example response

  {
    "client_id": "cl_1042",
    "name": "Anna Novak",
    "email": "anna@example.com",
    "notes": "Prefers a scissor cut",
    "appointments": [
      {
        "appointment_id": "apt_58213904",
        "service": "Haircut",
        "start": "2026-10-16T15:00:00-04:00"
      }
    ]
  }

• POST

  list_services

  Your service menu with duration, price and the staff who offer each.

  read

  Returns the services on your Booksy menu with duration, price and the staff members who offer each one. Use the service ID in find_open_slots and create_appointment.

  POST /api/v1/booksy/list_services

  Input

  No parameters.

  Example response

  {
    "services": [
      {
        "service_id": "svc_301",
        "name": "Haircut",
        "duration_minutes": 45,
        "price": 35,
        "staff_ids": [
          "stf_2291",
          "stf_2305"
        ]
      },
      {
        "service_id": "svc_302",
        "name": "Beard trim",
        "duration_minutes": 30,
        "price": 20,
        "staff_ids": [
          "stf_2291"
        ]
      }
    ]
  }

• POST

  list_staff

  Staff members with their working hours and the services they offer.

  read

  Returns your staff members with their weekly working hours and the services each one offers. Use the staff ID in other tools.

  POST /api/v1/booksy/list_staff

  Input

  No parameters.

  Example response

  {
    "staff": [
      {
        "staff_id": "stf_2291",
        "name": "Tom",
        "services": [
          "Haircut",
          "Beard trim"
        ],
        "hours": {
          "mon": "09:00-18:00",
          "tue": "09:00-18:00"
        }
      },
      {
        "staff_id": "stf_2305",
        "name": "Kate",
        "services": [
          "Haircut"
        ],
        "hours": {
          "mon": "10:00-19:00",
          "tue": "10:00-19:00"
        }
      }
    ]
  }

• POST

  get_report

  Numbers from Stats & Reports for a period, as JSON.

  read

  Returns the numbers of one Stats & Reports category for a date range. Booksy Biz Lite has Dashboard, Revenue, Appointments and Clients; Cash Flow, Inventory, Staff Members and Marketing need Booksy Biz Pro, and the call fails for other plans.

  POST /api/v1/booksy/get_report

  Input

  Input: get_report

  Parameter	Type	Description
  category required	enum	dashboard, revenue, appointments, clients, cash_flow, inventory, staff_members or marketing. The last four need Booksy Biz Pro.
  from required	date	First day, inclusive.
  to required	date	Last day, inclusive.

  Example response

  {
    "category": "staff_members",
    "from": "2026-10-05",
    "to": "2026-10-11",
    "total": {
      "revenue": 4820,
      "appointments": 96
    },
    "staff": [
      {
        "name": "Tom",
        "revenue": 2310,
        "appointments": 41
      },
      {
        "name": "Kate",
        "revenue": 1640,
        "appointments": 33
      },
      {
        "name": "Sam",
        "revenue": 870,
        "appointments": 22
      }
    ]
  }

• POST

  create_appointment

  Book a client into your calendar.

  asks first write

  Books one client for one service at a start time. Pick a start from find_open_slots. Booksy applies its automatic confirmation and the client is part of the booking. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/booksy/create_appointment

  Input

  Input: create_appointment

  Parameter	Type	Description
  client_id required	string	Client ID from list_clients or add_client.
  service_id required	string	Service ID from list_services.
  start required	datetime	ISO 8601 with time zone.
  staff_id	string	Staff member. Default: first one free.
  note	string	Internal note on the appointment.

  Example response

  {
    "appointment_id": "apt_58214120",
    "status": "confirmed",
    "client": "Mark Ellis",
    "service": "Beard trim",
    "staff": "Tom",
    "start": "2026-10-20T10:00:00-04:00",
    "end": "2026-10-20T10:30:00-04:00"
  }

• POST

  reschedule_appointment

  Move an appointment to a new time or staff member.

  asks first write

  Moves one appointment to a new start time and optionally to another staff member. Booksy booking rules that limit rescheduling still apply, so the call can be refused. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/booksy/reschedule_appointment

  Input

  Input: reschedule_appointment

  Parameter	Type	Description
  appointment_id required	string	Appointment ID from list_appointments.
  start required	datetime	New start, ISO 8601 with time zone.
  staff_id	string	New staff member. Default: unchanged.

  Example response

  {
    "appointment_id": "apt_58213904",
    "status": "confirmed",
    "service": "Haircut",
    "staff": "Tom",
    "start": "2026-10-17T11:30:00-04:00",
    "end": "2026-10-17T12:15:00-04:00"
  }

• POST

  add_client

  Add a client card to your client list.

  write

  Adds one client card with a name and optional phone, email and note. It reaches no one and you can edit the card in Booksy, so add_client runs without asking first.

  POST /api/v1/booksy/add_client

  Input

  Input: add_client

  Parameter	Type	Description
  name required	string	Full name.
  phone	string	Phone in international format.
  email	string	Email address.
  note	string	Internal note.

  Example response

  {
    "client_id": "cl_1310",
    "name": "Lena Fox",
    "email": "lena@example.com"
  }

• POST

  add_time_off

  Block time in a staff member's calendar so no one can book it.

  write

  Blocks a period in one staff member's calendar, like time off set in the app, so no one can book during it. It reaches no client and you can remove the block in Booksy, so add_time_off runs without asking first.

  POST /api/v1/booksy/add_time_off

  Input

  Input: add_time_off

  Parameter	Type	Description
  staff_id required	string	Staff ID from list_staff.
  start required	datetime	ISO 8601 with time zone.
  end required	datetime	ISO 8601 with time zone.
  reason	string	Internal label, e.g. vacation.

  Example response

  {
    "time_off_id": "to_7714",
    "staff_id": "stf_2291",
    "start": "2026-10-19T09:00:00-04:00",
    "end": "2026-10-19T18:00:00-04:00",
    "reason": "vacation"
  }

• POST

  send_message_blast

  Send one message to chosen clients by email, SMS or push notification.

  asks first write

  Sends one Message Blast to the clients you list, by email, SMS or a push notification to the Booksy Client App. SMS comes from an automated number, so clients cannot reply, and Booksy adds a link to your profile at the bottom. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/booksy/send_message_blast

  Input

  Input: send_message_blast

  Parameter	Type	Description
  channel required	enum	email, sms or push.
  message required	string	Message text.
  client_ids required	string[]	Recipients from list_clients.

  Example response

  {
    "blast_id": "mb_2208",
    "channel": "email",
    "recipients": 3,
    "status": "sent"
  }

Each successful call uses credits for the work it takes; failed calls and timeouts cost nothing. A hard spend cap is on by default. Authenticate with the Authorization: Bearer header.