MCP tools reference

Booksy MCP tools

13 tools for Booksy on the Cotlet MCP server. Your agent picks them from tools/list.

MCP server: https://cotlet.dev/mcp/v1
Connects with: Your own Booksy Biz account (owner or a staff account that can see the calendar; Pro-only reports need Booksy Biz Pro)
Integration page: Booksy

Booksy Endpoints
Endpoint	Access	Description
booksy_list_appointments	read	Appointments in a date range with client, service, staff, time and status.
booksy_get_appointment	read	One appointment: services, staff, price, client and notes.
booksy_find_open_slots	read	Free start times for a service on one day, based on working hours, breaks and time off.
booksy_list_clients	read	Clients with contact details and last visit.
booksy_get_client	read	One client card: contact details, notes and appointment history.
booksy_list_services	read	Your service menu with duration, price and the staff who offer each.
booksy_list_staff	read	Staff members with their working hours and the services they offer.
booksy_get_report	read	Numbers from Stats & Reports for a period, as JSON.
booksy_create_appointment	write	Book a client into your calendar.
booksy_reschedule_appointment	write	Move an appointment to a new time or staff member.
booksy_add_client	write	Add a client card to your client list.
booksy_add_time_off	write	Block time in a staff member's calendar so no one can book it.
booksy_send_message_blast	write	Send one message to chosen clients by email, SMS or push notification.

List appointments

read

MCP tool booksy_list_appointments

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.

Parameters

Parameters: list_appointments
Name	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.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_list_appointments",
    "arguments": {
      "from": "2026-10-01",
      "to": "2026-10-01"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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
  },
  "isError": false
}

Get appointment

read

MCP tool booksy_get_appointment

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

Parameters

Parameters: get_appointment
Name	Type	Description
appointment_id required	string	Appointment ID from list_appointments.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_get_appointment",
    "arguments": {
      "appointment_id": "appointment_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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"
  },
  "isError": false
}

Find open slots

read

MCP tool booksy_find_open_slots

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.

Parameters

Parameters: find_open_slots
Name	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.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_find_open_slots",
    "arguments": {
      "service_id": "service_8c41d2",
      "date": "2026-10-01"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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"
      }
    ]
  },
  "isError": false
}

List clients

read

MCP tool booksy_list_clients

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.

Parameters

Parameters: list_clients
Name	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.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_list_clients",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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
  },
  "isError": false
}

Get client

read

MCP tool booksy_get_client

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

Parameters

Parameters: get_client
Name	Type	Description
client_id	string	Client ID from list_clients.
email	string	Look up by email instead of ID.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_get_client",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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"
      }
    ]
  },
  "isError": false
}

List services

read

MCP tool booksy_list_services

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.

Parameters

No parameters.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_list_services",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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"
        ]
      }
    ]
  },
  "isError": false
}

List staff

read

MCP tool booksy_list_staff

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

Parameters

No parameters.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_list_staff",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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"
        }
      }
    ]
  },
  "isError": false
}

Get report

read

MCP tool booksy_get_report

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.

Parameters

Parameters: get_report
Name	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.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_get_report",
    "arguments": {
      "category": "staff_members",
      "from": "2026-10-06",
      "to": "2026-10-12"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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
      }
    ]
  },
  "isError": false
}

Create appointment

write Confirm

MCP tool booksy_create_appointment

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.

Parameters

Parameters: create_appointment
Name	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.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_create_appointment",
    "arguments": {
      "client_id": "client_8c41d2",
      "service_id": "service_8c41d2",
      "start": "2026-10-01T09:00:00Z"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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"
  },
  "isError": false
}

Reschedule appointment

write Confirm

MCP tool booksy_reschedule_appointment

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.

Parameters

Parameters: reschedule_appointment
Name	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.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_reschedule_appointment",
    "arguments": {
      "appointment_id": "apt_58213904",
      "start": "2026-10-17T11:30:00-04:00",
      "staff_id": "stf_2291"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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"
  },
  "isError": false
}

Add client

write

MCP tool booksy_add_client

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.

Parameters

Parameters: add_client
Name	Type	Description
name required	string	Full name.
phone	string	Phone in international format.
email	string	Email address.
note	string	Internal note.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_add_client",
    "arguments": {
      "name": "Jane Doe"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "client_id": "cl_1310",
    "name": "Lena Fox",
    "email": "lena@example.com"
  },
  "isError": false
}

Add time off

write

MCP tool booksy_add_time_off

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.

Parameters

Parameters: add_time_off
Name	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.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_add_time_off",
    "arguments": {
      "staff_id": "staff_8c41d2",
      "start": "2026-10-01T09:00:00Z",
      "end": "2026-10-01T09:00:00Z"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "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"
  },
  "isError": false
}

Send Message Blast

write Confirm

MCP tool booksy_send_message_blast

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.

Parameters

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

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "booksy_send_message_blast",
    "arguments": {
      "channel": "email",
      "message": "Thursday Happy Hour: 20% off any cut, 4 to 6 pm. Book in the app.",
      "client_ids": [
        "cl_1042",
        "cl_1187",
        "cl_1203"
      ]
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "blast_id": "mb_2208",
    "channel": "email",
    "recipients": 3,
    "status": "sent"
  },
  "isError": false
}

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Analytics cookies