Booksy salon and barber booking MCP server: list bookings, create booking, reschedule booking.
Model Context Protocol (MCP) Server: dev.cotlet/booksy
The MCP server dev.cotlet/booksy provides context access for “Bookings, clients, reviews and reports for beauty businesses.” It is described by the repository as a service focused on managing or exposing booking-related information, along with client, review, and reporting data for beauty operators.
🛠️ Key Features
Bookings for beauty businesses
Client information
Reviews
Reports
🚀 Use Cases
Retrieve booking and client details for beauty services
View or summarize customer reviews
Access reporting outputs related to bookings and business activity
⚡ Developer Benefits
Clear domain scope centered on beauty-business operations
Structured categories of data (bookings, clients, reviews, reports) aligned to common application needs
⚠️ Limitations
No additional capabilities, tool count, topics, or implementation details were provided in the available source data.
The Cotlet account this connection acts as: email, workspace, access status, the API key or OAuth client in use with its scope, the apps the workspace may call and its credit balance. Free. Needs the user's Cotlet API key or sign-in.
The apps of the user's workspace and whether each works now: access granted or requested, the app account in the user's Cloud Browser (connected, signed out, signed in but not connected), and the one step the user has to take, with the console link. Free. Needs the user's Cotlet API key or sign-in.
Parameters1
app
string
optional
Only this app, e.g. skool.
Raw schema
{
"type": "object",
"properties": {
"app": {
"type": "string",
"description": "Only this app, e.g. skool."
}
},
"additionalProperties": false
}
cotlet_request_apps
Requests access to apps for the user's workspace, as Request access in the console: every app is granted at once. An app with dedicated tools gets them after the user signs in to it in their Cloud Browser; any other works now in the user's Web browser with cotlet_app_guide, and the Cotlet team builds its dedicated tools on demand. Takes app slugs as listed at https://cotlet.dev/api/v1/apps. Free. Needs the user's Cotlet API key or sign-in.
Parameters2
apps
array
required
App slugs, e.g. ["skool", "substack"].
use_case
string
optional
What the user wants the agent to do in these apps, in their words.
Raw schema
{
"type": "object",
"properties": {
"apps": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 10,
"description": "App slugs, e.g. [\"skool\", \"substack\"]."
},
"use_case": {
"type": "string",
"maxLength": 1000,
"description": "What the user wants the agent to do in these apps, in their words."
}
},
"required": [
"apps"
],
"additionalProperties": false
}
cotlet_get_call
Status of an earlier Cotlet call, by its call_id: pending (waits for the owner's approval in the Cotlet console), approved, running, success, rejected, expired, blocked or failed. For a call that answered with status pending or running.
Returns a one-time upload_url and a file_id for a local file (an image for a post, an attachment). The file is sent to upload_url with an HTTP PUT; an argument that takes a file accepts {"file_id": "..."}. Up to 25 MB, the URL works once. Free. Needs the user's Cotlet API key or sign-in.
Sends a report straight to the Cotlet team: a tool that failed or returned wrong data, an error you could not get past, or a tool, field or app the task needed and Cotlet lacks. The report carries the error text and call_id when there is one, never passwords or tokens. Needs the user's Cotlet API key or sign-in.
Parameters7
kind
string
required
bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else.
title
string
required
One line, e.g. 'skool_list_members stops after 50 members'.
description
string
required
What the user asked for, what you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets.
app
any
optional
App slug the report is about, e.g. 'skool', or for a site in the web browser its host, e.g. 'app.example.com'.
tool
any
optional
Tool or endpoint name, e.g. 'skool_list_members'.
call_id
any
optional
call_id of the call that went wrong, if any.
client
any
optional
Agent or tool sending this, e.g. 'Claude Code'.
Raw schema
{
"type": "object",
"properties": {
"kind": {
"description": "bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else.",
"enum": [
"bug",
"error",
"feature_request",
"missing_feature",
"other"
],
"title": "Kind",
"type": "string"
},
"title": {
"description": "One line, e.g. 'skool_list_members stops after 50 members'.",
"maxLength": 200,
"minLength": 3,
"title": "Title",
"type": "string"
},
"description": {
"description": "What the user asked for, what you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets.",
"maxLength": 5000,
"minLength": 10,
"title": "Description",
"type": "string"
},
"app": {
"anyOf": [
{
"maxLength": 80,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "App slug the report is about, e.g. 'skool', or for a site in the web browser its host, e.g. 'app.example.com'.",
"title": "App"
},
"tool": {
"anyOf": [
{
"maxLength": 160,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Tool or endpoint name, e.g. 'skool_list_members'.",
"title": "Tool"
},
"call_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "call_id of the call that went wrong, if any.",
"title": "Call Id"
},
"client": {
"anyOf": [
{
"maxLength": 80,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Agent or tool sending this, e.g. 'Claude Code'.",
"title": "Client"
}
},
"required": [
"kind",
"title",
"description"
],
"additionalProperties": false,
"description": "Body of POST /api/v1/reports and the arguments of the MCP tool cotlet_report_issue.",
"title": "AgentReportCreate"
}
cotlet_browser_open
Wakes the user's Booksy Cloud Browser, a real Chrome hosted on Cotlet and signed in to Booksy as the user. Use it for what the Booksy tools do not cover. Opens `url` when given and returns the page's URL, title and tab. In the web browser `url` opens in the open tab of the same site, else in a new tab when the shown tab already has a site open (at the tab limit in the tab you opened and used longest ago), so the user's other apps stay as they are (the tabs tool lists them). The user watches every step live. Before the first step in an app, Cotlet's app guide says which browser to use and how to work in the app. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters1
url
string
optional
A public http or https address, e.g. https://example.com. In an app's browser, a page of that app.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public http or https address, e.g. https://example.com. In an app's browser, a page of that app."
}
},
"additionalProperties": false
}
cotlet_browser_navigate
Opens a public http or https address in the user's Booksy Cloud Browser and returns the URL and title it ended on. Only Booksy pages open. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters1
url
string
required
A public http or https address, e.g. https://example.com. In an app's browser, a page of that app.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public http or https address, e.g. https://example.com. In an app's browser, a page of that app."
}
},
"required": [
"url"
],
"additionalProperties": false
}
cotlet_browser_read
Returns the current page of the user's Booksy Cloud Browser: its readable text, up to 20,000 characters, and a numbered list of its links, buttons, fields, options and toggles, also inside frames. Open dialogs and cookie banners come first: they cover the page, so close or answer them first. Field values, cookies and storage are never returned. On a page longer than that, both start near where it is scrolled to; `element` reads only the part inside that element (a dialog, a form, a list). Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters1
element
integer
optional
Read only inside this element of the last read.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "Read only inside this element of the last read."
}
},
"additionalProperties": false
}
cotlet_browser_screenshot
Returns a JPEG image of the visible part of the current page in the user's Booksy Cloud Browser, with its URL and title: boards, canvases and layouts that the page text does not show. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Scrolls the current page in the user's Booksy Cloud Browser with the mouse wheel, as a person does: down or up by `screens` viewport heights (default 0.8), to the top or the bottom, or until element `element` is in view. Content that loads on scroll appears, and the next read lists it. Returns the URL, title and scroll position (at_top, at_bottom). Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters4
direction
string
optional
Where to scroll. Default: down.
screens
number
optional
How far, in viewport heights, for down and up. Default: 0.8.
element
integer
optional
Scroll until this element of the element list is in view.
inside
integer
optional
Scroll inside this element (a list in a dialog or a side panel), not the page.
Raw schema
{
"type": "object",
"properties": {
"direction": {
"type": "string",
"enum": [
"down",
"up",
"top",
"bottom"
],
"description": "Where to scroll. Default: down."
},
"screens": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 10,
"description": "How far, in viewport heights, for down and up. Default: 0.8."
},
"element": {
"type": "integer",
"minimum": 1,
"description": "Scroll until this element of the element list is in view."
},
"inside": {
"type": "integer",
"minimum": 1,
"description": "Scroll inside this element (a list in a dialog or a side panel), not the page."
}
},
"additionalProperties": false
}
cotlet_browser_click
Clicks a link, button, option or other element of the current page in the user's Booksy Cloud Browser, by its number in the page's element list, or a point of the screenshot (`x`, `y`) for boards, canvases and maps. Returns the URL and title after the click, and says when nothing on the page changed. It acts as the user on that site. Buttons that pay or buy and buttons on account or sign-in pages are refused. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters6
element
integer
optional
The element's number in the element list of the current page.
x
number
optional
Instead of `element`: pixels from the left of the screenshot (boards, canvases, maps).
y
number
optional
With `x`: pixels from the top of the screenshot.
double
boolean
optional
Double-click.
dialog
string
optional
How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog.
dialog_text
string
optional
Text for a prompt dialog this step opens; implies accept.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"x": {
"type": "number",
"minimum": 0,
"description": "Instead of `element`: pixels from the left of the screenshot (boards, canvases, maps)."
},
"y": {
"type": "number",
"minimum": 0,
"description": "With `x`: pixels from the top of the screenshot."
},
"double": {
"type": "boolean",
"description": "Double-click."
},
"dialog": {
"type": "string",
"enum": [
"accept",
"dismiss"
],
"description": "How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog."
},
"dialog_text": {
"type": "string",
"maxLength": 1000,
"description": "Text for a prompt dialog this step opens; implies accept."
}
},
"additionalProperties": false
}
cotlet_browser_type
Types text into a field of the current page in the user's Booksy Cloud Browser, by the field's number in the page's element list, and with `submit` presses Enter. Returns the URL and title after it. Password, card and one-time code fields and sign-in pages are refused: the user fills those in themselves. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters6
element
integer
required
The element's number in the element list of the current page.
text
string
required
The text to type.
submit
boolean
optional
Press Enter after typing, e.g. to search.
slowly
boolean
optional
Type key by key: for a search or address field whose suggestions do not appear. Read after it; the suggestions are listed as options to click.
dialog
string
optional
How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog.
dialog_text
string
optional
Text for a prompt dialog this step opens; implies accept.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"text": {
"type": "string",
"maxLength": 5000,
"description": "The text to type."
},
"submit": {
"type": "boolean",
"description": "Press Enter after typing, e.g. to search."
},
"slowly": {
"type": "boolean",
"description": "Type key by key: for a search or address field whose suggestions do not appear. Read after it; the suggestions are listed as options to click."
},
"dialog": {
"type": "string",
"enum": [
"accept",
"dismiss"
],
"description": "How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog."
},
"dialog_text": {
"type": "string",
"maxLength": 1000,
"description": "Text for a prompt dialog this step opens; implies accept."
}
},
"required": [
"element",
"text"
],
"additionalProperties": false
}
cotlet_browser_select
Chooses an option of a drop-down list on the current page in the user's Booksy Cloud Browser, by the list's number in the element list and the option's label as read lists it (or its value). Returns the URL and title after it. Card fields and account pages are refused. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters4
element
integer
required
The element's number in the element list of the current page.
option
string
required
The option.
dialog
string
optional
How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog.
dialog_text
string
optional
Text for a prompt dialog this step opens; implies accept.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"option": {
"type": "string",
"maxLength": 300,
"description": "The option."
},
"dialog": {
"type": "string",
"enum": [
"accept",
"dismiss"
],
"description": "How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog."
},
"dialog_text": {
"type": "string",
"maxLength": 1000,
"description": "Text for a prompt dialog this step opens; implies accept."
}
},
"required": [
"element",
"option"
],
"additionalProperties": false
}
cotlet_browser_press
Presses a key on the current page in the user's Booksy Cloud Browser, on the element that has focus: Tab to the next field, Enter to send, Escape to close a dialog or pop-up, arrows to move through a suggestion list or a slider, or one character (a site's shortcut). Returns the URL and title after it, and says when nothing changed. Enter on account pages and characters into password fields are refused. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters4
key
string
required
One of Enter, Tab, Shift+Tab, Escape, Backspace, Delete, Space, ArrowDown, ArrowUp, ArrowLeft, ArrowRight, PageDown, PageUp, Home, End, or a single character such as a or 5.
repeat
integer
optional
Press it this many times, e.g. ArrowDown 3 times. Default 1.
dialog
string
optional
How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog.
dialog_text
string
optional
Text for a prompt dialog this step opens; implies accept.
Raw schema
{
"type": "object",
"properties": {
"key": {
"type": "string",
"anyOf": [
{
"enum": [
"Enter",
"Tab",
"Shift+Tab",
"Escape",
"Backspace",
"Delete",
"Space",
"ArrowDown",
"ArrowUp",
"ArrowLeft",
"ArrowRight",
"PageDown",
"PageUp",
"Home",
"End"
]
},
{
"pattern": "^[ -~]$"
}
],
"description": "One of Enter, Tab, Shift+Tab, Escape, Backspace, Delete, Space, ArrowDown, ArrowUp, ArrowLeft, ArrowRight, PageDown, PageUp, Home, End, or a single character such as a or 5."
},
"repeat": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"description": "Press it this many times, e.g. ArrowDown 3 times. Default 1."
},
"dialog": {
"type": "string",
"enum": [
"accept",
"dismiss"
],
"description": "How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog."
},
"dialog_text": {
"type": "string",
"maxLength": 1000,
"description": "Text for a prompt dialog this step opens; implies accept."
}
},
"required": [
"key"
],
"additionalProperties": false
}
cotlet_browser_upload
Puts files into a file field of the current page in the user's Booksy Cloud Browser, or into the file picker that an upload button opens, by its number in the element list. A file is given as {"url": "https://..."} for a file online or {"file_id": "..."} for one uploaded to Cotlet first; up to 10 files, 20 MB each. Returns the URL and title after it. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters2
element
integer
required
The element's number in the element list of the current page.
files
array
required
The files.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public file URL."
},
"file_id": {
"type": "string",
"description": "A file uploaded to Cotlet."
}
},
"additionalProperties": false
},
"description": "The files."
}
},
"required": [
"element",
"files"
],
"additionalProperties": false
}
cotlet_browser_back
Goes back one page in the user's Booksy Cloud Browser, like the browser's Back button (with `forward`, forward again). Returns the URL and title. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters3
forward
boolean
optional
Go forward instead of back.
dialog
string
optional
How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog.
dialog_text
string
optional
Text for a prompt dialog this step opens; implies accept.
Raw schema
{
"type": "object",
"properties": {
"forward": {
"type": "boolean",
"description": "Go forward instead of back."
},
"dialog": {
"type": "string",
"enum": [
"accept",
"dismiss"
],
"description": "How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog."
},
"dialog_text": {
"type": "string",
"maxLength": 1000,
"description": "Text for a prompt dialog this step opens; implies accept."
}
},
"additionalProperties": false
}
cotlet_browser_hover
Rests the pointer on an element of the current page (or a point of the screenshot) in the user's Booksy Cloud Browser, as a person does to open a hover menu, a tooltip or a card's preview. Read after it for what opened. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters3
element
integer
optional
The element's number in the element list of the current page.
x
number
optional
Instead of `element`: pixels from the left of the screenshot (boards, canvases, maps).
y
number
optional
With `x`: pixels from the top of the screenshot.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"x": {
"type": "number",
"minimum": 0,
"description": "Instead of `element`: pixels from the left of the screenshot (boards, canvases, maps)."
},
"y": {
"type": "number",
"minimum": 0,
"description": "With `x`: pixels from the top of the screenshot."
}
},
"additionalProperties": false
}
cotlet_browser_drag
Drags from one element or point of the screenshot to another in the user's Booksy Cloud Browser: a piece on a board, a card between columns, a field into a form builder, a slider's handle. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Parameters4
from
object
required
An element number, or x and y of the screenshot.
to
object
required
An element number, or x and y of the screenshot.
dialog
string
optional
How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog.
dialog_text
string
optional
Text for a prompt dialog this step opens; implies accept.
Raw schema
{
"type": "object",
"properties": {
"from": {
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"x": {
"type": "number",
"minimum": 0,
"description": "Instead of `element`: pixels from the left of the screenshot (boards, canvases, maps)."
},
"y": {
"type": "number",
"minimum": 0,
"description": "With `x`: pixels from the top of the screenshot."
}
},
"additionalProperties": false,
"description": "An element number, or x and y of the screenshot."
},
"to": {
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"x": {
"type": "number",
"minimum": 0,
"description": "Instead of `element`: pixels from the left of the screenshot (boards, canvases, maps)."
},
"y": {
"type": "number",
"minimum": 0,
"description": "With `x`: pixels from the top of the screenshot."
}
},
"additionalProperties": false,
"description": "An element number, or x and y of the screenshot."
},
"dialog": {
"type": "string",
"enum": [
"accept",
"dismiss"
],
"description": "How to answer a native dialog (confirm, prompt, 'leave this page?') this step opens: accept presses OK, dismiss presses Cancel. Default: OK for an alert, Cancel for every other dialog."
},
"dialog_text": {
"type": "string",
"maxLength": 1000,
"description": "Text for a prompt dialog this step opens; implies accept."
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
}
cotlet_browser_wait
Waits until `text` shows on the current page in the user's Booksy Cloud Browser (at most `seconds`, default 5, up to 20), or just `seconds` without text: for results, prices or a page that load slowly. Says whether the text appeared. Run browser steps one at a time and wait for each answer; steps sent together run in no set order. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
Ends the session in the user's Booksy Cloud Browser: the browser keeps its cookies, goes to sleep and the per-minute charge stops. Returns the session's minutes and credits.
How to work in an app by clicking in the user's Cloud Browser with Cotlet's browser tools: which browser to use for this workspace and the sign-in link, the method step by step, the app's screens, menus and actions, notes, and the app's dedicated tools when Cotlet has them. Call it before the first browser step in an app. Works for any web app; one outside Cotlet's catalog gets the general method. Free, no browser session.
Parameters2
app
string
optional
The app's name or Cotlet slug. Default: Booksy.
task
string
optional
What the user wants done in the app, in their words.
Raw schema
{
"type": "object",
"properties": {
"app": {
"type": "string",
"maxLength": 120,
"description": "The app's name or Cotlet slug. Default: Booksy."
},
"task": {
"type": "string",
"maxLength": 500,
"description": "What the user wants done in the app, in their words."
}
},
"additionalProperties": false
}
estimate_message_blast
Count who a Message Blast would reach and its SMS cost, without sending it. Asks Booksy what send_message_blast would do with the same clients, channel and text: how many clients it reaches, how many emails, texts or push notifications go out and what the texts cost beyond the plan's free allowance. Where the law asks for marketing consent (EU), consented counts only the clients who agreed; send_message_blast sends to those. Nothing is sent.
Client cards matching a name, email or phone. Searches the client list the way the Clients page's search box does and returns the matching cards with contact details, note and visit counts. A card added a moment ago can take a few seconds to show up in search; get_client reads it by ID at once.
Parameters2
limit
integer
optional
Most matches to return. Default: 10.
query
string
required
Name, email or phone (or a part of one).
Raw schema
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Most matches to return. Default: 10."
},
"query": {
"type": "string",
"minLength": 2,
"description": "Name, email or phone (or a part of one)."
}
},
"required": [
"query"
],
"additionalProperties": false
}
find_open_slots
Free start times for a service on one day, from working hours, bookings, blocks and time off. Returns free start times for one service on one day, earliest first, for each staff member who offers it (or only staff_id). Starts follow the service's time slot interval and leave room for its duration; past times are left out. Booksy's own booking check confirms every slot returned. Pass start and staff_id to create_appointment.
Parameters4
date
string
required
Day to check.
limit
integer
optional
1 to 30 slots, earliest first. Default: 12.
staff_id
string
optional
Only this staff member. Default: anyone who offers the service.
service_id
string
required
service_id from list_services (its first variant), or a variant_id.
Raw schema
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "Day to check."
},
"limit": {
"type": "integer",
"description": "1 to 30 slots, earliest first. Default: 12."
},
"staff_id": {
"type": "string",
"description": "Only this staff member. Default: anyone who offers the service."
},
"service_id": {
"type": "string",
"description": "service_id from list_services (its first variant), or a variant_id."
}
},
"required": [
"service_id",
"date"
],
"additionalProperties": false
}
get_appointment
One appointment: services, staff, times, price, client and notes. Returns one appointment with each service's staff member, times and price, the client, the total and the notes. note is the internal note only staff see; client_note is the note shown to the client. can lists what Booksy allows now (cancel, change, confirm, decline, no_show).
Weekly opening hours, time zone and booking lead times of the business. Reads the opening hours set in Business details: open ranges for each day (an empty list is closed), the note shown with them, the business's time zone and address, and how early and how late clients may book or change a visit.
Your business's name, address, contact, opening hours, booking policy, rating and plan status. Reads the business record behind your Booksy profile: name, address and time zone, phone, public email, website, description, weekly opening hours, how far ahead clients can book and change, review rating, whether the profile is visible in the Booksy marketplace, and the plan status with the trial end date.
One client card: contact details, private note, counts and visit history. Reads one client card of the business by ID: name, email, phone, birthday, private note, tags, whether the client is blocked or uses the Booksy app, visit, no-show and cancellation counts, revenue, and the visits (past and upcoming appointments) with times, services, staff, status and total. A visit's appointment_uid is the appointment_id of get_appointment.
Numbers from Stats & Reports for a day, week, month or year, as JSON. Returns one Stats & Reports category for a period: dashboard gives the totals for appointments, revenue and clients with the change against the previous period; any other category gives its highlight tables and the list of its reports. Pass report with a key from that list for the full report. Booksy counts one day, one Monday-to-Sunday week, one calendar month or one calendar year, so from and to must be such a period. Amounts come formatted in the business's currency. Booksy Biz Lite has the dashboard, revenue, appointments and clients; cash_flow, inventory, staff_members and marketing need Booksy Biz Pro.
Parameters5
to
string
required
Last day, inclusive: the same day, a Monday-to-Sunday week, a calendar month or year.
from
string
required
First day, inclusive.
report
string
optional
Report key from `reports` of the category (e.g. appointments_summary) for its full tables.
Staff member, only for the report performance_per_staffer.
Raw schema
{
"type": "object",
"properties": {
"to": {
"type": "string",
"format": "date",
"description": "Last day, inclusive: the same day, a Monday-to-Sunday week, a calendar month or year."
},
"from": {
"type": "string",
"format": "date",
"description": "First day, inclusive."
},
"report": {
"type": "string",
"description": "Report key from `reports` of the category (e.g. appointments_summary) for its full tables."
},
"category": {
"enum": [
"dashboard",
"appointments",
"clients",
"revenue",
"cash_flow",
"staff_members",
"marketing",
"tips",
"inventory"
],
"type": "string",
"description": "dashboard (totals), appointments, clients, revenue, cash_flow, staff_members, marketing, tips or inventory."
},
"staff_id": {
"type": "integer",
"description": "Staff member, only for the report performance_per_staffer."
}
},
"required": [
"category",
"from",
"to"
],
"additionalProperties": false
}
get_settings
Text message allowance and usage, client message channels and your notification settings. Reads the settings an agent needs before messaging clients: whether SMS and email to clients are on, the free and paid text allowance with this period's usage and price per text part, and which booking events notify you by email or push. Changes stay in the Booksy app.
Appointments in a date range with client, service, staff, time and status. Lists the Booksy calendar between two days (31 at most), in start order, including unconfirmed requests. Times carry the business's time zone. A walk-in has an empty client. An appointment with several services is one row listing them all; get_appointment returns prices and notes.
Parameters3
to
string
required
Last day, inclusive. At most 31 days after from.
from
string
required
First day, inclusive.
staff_id
string
optional
Only one staff member, from list_staff.
Raw schema
{
"type": "object",
"properties": {
"to": {
"type": "string",
"format": "date",
"description": "Last day, inclusive. At most 31 days after from."
},
"from": {
"type": "string",
"format": "date",
"description": "First day, inclusive."
},
"staff_id": {
"type": "string",
"description": "Only one staff member, from list_staff."
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
}
list_clients
Clients with contact details, visit counts and last visit, plus Booksy's client groups. Reads the Clients list of the business, A to Z: name, email, phone, private note, tags, visits, no-shows, cancellations, revenue and the last visit. Search by name, email or phone, or keep only clients who have not visited for a number of days (filtered on each page). `groups` gives Booksy's smart groups (new, most loyal, slipping away, prospects, upcoming birthdays ...) with their counts.
Parameters4
limit
integer
optional
Page size. Default: 50.
query
string
optional
Name, email or phone to search for.
cursor
string
optional
next_cursor from the previous call.
not_visited_days
integer
optional
Only clients whose last visit is older than this many days (or who never visited).
Raw schema
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size. Default: 50."
},
"query": {
"type": "string",
"description": "Name, email or phone to search for."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous call."
},
"not_visited_days": {
"type": "integer",
"minimum": 1,
"description": "Only clients whose last visit is older than this many days (or who never visited)."
}
},
"required": [],
"additionalProperties": false
}
list_message_blasts
Message Blast templates (automated and one-time) and the blasts scheduled to go out. Reads Promotion > Message Blasts: every automated template with its trigger and whether it is on, every one-time template, and the blasts scheduled for later. send_message_blast sends a one-time message; estimate_message_blast counts recipients and SMS cost first.
Notifications from the panel's bell: new bookings, changes, cancellations, reviews. Reads the notifications Booksy shows under the bell in the panel, newest first. Client chat is not included. Reading does not mark them seen.
Client reviews of your business with rating, text, services, staff and your reply. Reads the reviews on your Booksy profile, newest first by default: star rating, text, the client's name as Booksy shows it, services, staff, visit date and your reply if you wrote one. Also returns the average rating and the count per star. Reply with reply_to_review.
Your service menu with category, variants, duration, price and the staff who offer each. Reads the services of the business: name, category, description, whether clients can book it online, and its variants with duration in minutes, price (number and as shown, with currency), price type and the staff IDs who perform it. create_appointment and find_open_slots take service_id (its first variant) or a variant_id for another variant.
Staff members with their working hours for a week and the services they offer. Reads the staff of the business: name, position, email, phone, access level, whether clients see them, the services each one performs, and working hours for each day of one week (Monday to Sunday, from Shifts, time off included). Use staff_id in other tools.
Parameters1
week_start_date
string
optional
Any day of the week to show hours for, YYYY-MM-DD. Default: this week.
Raw schema
{
"type": "object",
"properties": {
"week_start_date": {
"type": "string",
"format": "date",
"description": "Any day of the week to show hours for, YYYY-MM-DD. Default: this week."
}
},
"required": [],
"additionalProperties": false
}
list_time_off
Staff time off and blocked hours in a date range. Lists time off from Shifts (kind time_off: dates, hours only when it is part of a day) and blocked hours in the calendar (kind block: date-times) between two days, 31 at most. time_off_id goes to remove_time_off.
Parameters3
to
string
required
Last day, inclusive. At most 31 days after from.
from
string
required
First day, inclusive.
staff_id
string
optional
Only one staff member, from list_staff.
Raw schema
{
"type": "object",
"properties": {
"to": {
"type": "string",
"format": "date",
"description": "Last day, inclusive. At most 31 days after from."
},
"from": {
"type": "string",
"format": "date",
"description": "First day, inclusive."
},
"staff_id": {
"type": "string",
"description": "Only one staff member, from list_staff."
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
}
add_client
Add a client card to your client list. Needs a phone or an email. Adds one client card with a name, a phone or an email (Booksy needs one of them), and optionally a private note and a birthday. The client is not invited to the Booksy app and gets no message, so add_client runs without asking first. delete_client removes the card again. A card deleted earlier with the same email or phone comes back with its old visits, note and birthday unless new ones are given.
Parameters5
name
string
required
Full name; the last word is the last name.
note
string
optional
Private note, seen only by the business.
email
string
optional
Email address.
phone
string
optional
Mobile phone, best in international format (+48 600 100 200).
birthday
string
optional
YYYY-MM-DD.
Raw schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Full name; the last word is the last name."
},
"note": {
"type": "string",
"description": "Private note, seen only by the business."
},
"email": {
"type": "string",
"format": "email",
"description": "Email address."
},
"phone": {
"type": "string",
"description": "Mobile phone, best in international format (+48 600 100 200)."
},
"birthday": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD."
}
},
"required": [
"name"
],
"additionalProperties": false
}
add_client_note
Add a dated line to a client's private note, keeping what is there. Booksy keeps one private note per client card, seen only by the business. This adds a new line starting with today's date under the existing text. The client is not told.
Parameters2
text
string
required
The line to add.
client_id
integer
required
From list_clients or find_client.
Raw schema
{
"type": "object",
"properties": {
"text": {
"type": "string",
"maxLength": 1000,
"minLength": 1,
"description": "The line to add."
},
"client_id": {
"type": "integer",
"description": "From list_clients or find_client."
}
},
"required": [
"client_id",
"text"
],
"additionalProperties": false
}
add_time_off
Block a staff member's calendar so no one can book it: whole days off or a few hours. Two dates (YYYY-MM-DD) add whole days of time off, like Staff > Shifts. Two date-times on the same day block those hours in the calendar, like a time reservation. Booksy refuses a block over existing appointments. It reaches no client; remove_time_off takes it back.
Parameters4
end
string
required
Last day off, inclusive (YYYY-MM-DD), or the end of the blocked hours on the same day.
start
string
required
A day (YYYY-MM-DD) for whole days off, or an ISO 8601 date-time to block hours.
reason
string
optional
Whole days: vacation, sick_day, personal_day, training or other (other text is kept as a note). Hours: any label, e.g. Lunch.
staff_id
string
required
Staff ID from list_staff.
Raw schema
{
"type": "object",
"properties": {
"end": {
"type": "string",
"description": "Last day off, inclusive (YYYY-MM-DD), or the end of the blocked hours on the same day."
},
"start": {
"type": "string",
"description": "A day (YYYY-MM-DD) for whole days off, or an ISO 8601 date-time to block hours."
},
"reason": {
"type": "string",
"description": "Whole days: vacation, sick_day, personal_day, training or other (other text is kept as a note). Hours: any label, e.g. Lunch."
},
"staff_id": {
"type": "string",
"description": "Staff ID from list_staff."
}
},
"required": [
"staff_id",
"start",
"end"
],
"additionalProperties": false
}
cancel_appointment
Cancel an appointment and free its time in the calendar. Cancels one appointment as the business. The client is told only with notify_client. A deposit, if any, follows the business's deposit settings. Booksy refuses appointments it no longer lets you cancel (can in get_appointment). There is no undo; book again with create_appointment. Waits for the owner's approval.
Parameters3
reason
string
optional
Why it is cancelled; saved as the appointment's note.
notify_client
boolean
optional
Tell the client by email and SMS through Booksy. Default: false.
appointment_id
string
required
Appointment ID from list_appointments.
Raw schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Why it is cancelled; saved as the appointment's note."
},
"notify_client": {
"type": "boolean",
"description": "Tell the client by email and SMS through Booksy. Default: false."
},
"appointment_id": {
"type": "string",
"description": "Appointment ID from list_appointments."
}
},
"required": [
"appointment_id"
],
"additionalProperties": false
}
create_appointment
Book a client for one or more services at a start time; Booksy checks the slots first. Books one client card for service_id, or for several services in one appointment, each with its own staff member, back to back from start. Each end follows the service's duration. Booksy's dry run checks every staff member is free first; a busy slot is refused, never double-booked. The client gets Booksy's confirmation only with notify_client. dry_run returns the same answer with saved false and keeps nothing. Waits for the owner's approval.
Parameters8
note
string
optional
Internal note, only staff see it.
start
string
required
ISO 8601. Without a time zone it is the business's local time.
dry_run
boolean
optional
Only check the time and price; nothing is saved. Default: false.
services
array
optional
Services of the appointment in order, each starting when the one before ends.
staff_id
string
optional
Staff ID from list_staff, with service_id. Default: the first one who offers the service.
client_id
string
required
Client ID from list_clients or add_client.
service_id
string
optional
service_id from list_services (its first variant), or a variant_id. Or use services.
notify_client
boolean
optional
Send Booksy's booking confirmation to the client. Default: false.
Raw schema
{
"type": "object",
"properties": {
"note": {
"type": "string",
"description": "Internal note, only staff see it."
},
"start": {
"type": "string",
"format": "date-time",
"description": "ISO 8601. Without a time zone it is the business's local time."
},
"dry_run": {
"type": "boolean",
"description": "Only check the time and price; nothing is saved. Default: false."
},
"services": {
"type": "array",
"items": {
"type": "object",
"required": [
"service_id"
],
"properties": {
"staff_id": {
"type": "string",
"description": "Staff ID from list_staff. Default: the first one who offers the service."
},
"service_id": {
"type": "string",
"description": "service_id or variant_id from list_services."
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 1,
"description": "Services of the appointment in order, each starting when the one before ends."
},
"staff_id": {
"type": "string",
"description": "Staff ID from list_staff, with service_id. Default: the first one who offers the service."
},
"client_id": {
"type": "string",
"description": "Client ID from list_clients or add_client."
},
"service_id": {
"type": "string",
"description": "service_id from list_services (its first variant), or a variant_id. Or use services."
},
"notify_client": {
"type": "boolean",
"description": "Send Booksy's booking confirmation to the client. Default: false."
}
},
"required": [
"client_id",
"start"
],
"additionalProperties": false
}
delete_client
Remove a client card from your client list. Deletes the card the way the panel's Delete button does. The client is not told. Past appointments stay in the calendar.
Remove time off or a blocked period so the time can be booked again. Deletes one time off (off-…) or one calendar block (block-…). It reaches no client.
Parameters2
staff_id
string
required
Staff ID the time off belongs to.
time_off_id
string
required
ID from add_time_off or list_time_off (off-… or block-…).
Raw schema
{
"type": "object",
"properties": {
"staff_id": {
"type": "string",
"description": "Staff ID the time off belongs to."
},
"time_off_id": {
"type": "string",
"description": "ID from add_time_off or list_time_off (off-… or block-…)."
}
},
"required": [
"staff_id",
"time_off_id"
],
"additionalProperties": false
}
reply_to_review
Post or change your public reply to a client's review. Writes your reply under one review on your Booksy profile, the way the Reviews page does. A second call replaces the reply. Everyone who sees your profile sees it and the reviewer is told, so by default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.
Parameters2
reply
string
required
Reply text, public on your profile.
review_id
integer
required
Review ID from list_reviews.
Raw schema
{
"type": "object",
"properties": {
"reply": {
"type": "string",
"minLength": 1,
"description": "Reply text, public on your profile."
},
"review_id": {
"type": "integer",
"description": "Review ID from list_reviews."
}
},
"required": [
"review_id",
"reply"
],
"additionalProperties": false
}
reschedule_appointment
Change an appointment: a new start time, another staff member, or other services. Without services, moves every service of the appointment by the same amount, so the first one starts at start. With services, the list replaces the appointment's services, each with its own staff member, back to back from start (default: the current start). Booksy's dry run checks the new slots first and a busy one is refused. The client hears about it only with notify_client. Booksy refuses appointments it no longer lets you change (can in get_appointment). Waits for the owner's approval.
Parameters5
start
string
optional
New start, ISO 8601. Without a time zone it is the business's local time. Default: unchanged.
services
array
optional
Replaces the services: the full new list in order, back to back from start. Leave a service out to remove it, add one to add it. Default: unchanged.
staff_id
string
optional
New staff member for every service, from list_staff. Default: unchanged.
notify_client
boolean
optional
Tell the client about the new time through Booksy. Default: false.
appointment_id
string
required
Appointment ID from list_appointments.
Raw schema
{
"type": "object",
"properties": {
"start": {
"type": "string",
"format": "date-time",
"description": "New start, ISO 8601. Without a time zone it is the business's local time. Default: unchanged."
},
"services": {
"type": "array",
"items": {
"type": "object",
"required": [
"service_id"
],
"properties": {
"staff_id": {
"type": "string",
"description": "Staff ID from list_staff. Default: the first one who offers the service."
},
"service_id": {
"type": "string",
"description": "service_id or variant_id from list_services."
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 1,
"description": "Replaces the services: the full new list in order, back to back from start. Leave a service out to remove it, add one to add it. Default: unchanged."
},
"staff_id": {
"type": "string",
"description": "New staff member for every service, from list_staff. Default: unchanged."
},
"notify_client": {
"type": "boolean",
"description": "Tell the client about the new time through Booksy. Default: false."
},
"appointment_id": {
"type": "string",
"description": "Appointment ID from list_appointments."
}
},
"required": [
"appointment_id"
],
"additionalProperties": false
}
send_message_blast
Send one message to chosen clients by email, SMS or push notification. Sends one Message Blast now to the clients you list, by email, SMS or a push notification to the Booksy Client App, as Promotion > Message Blasts > Create your own message does. Where the law asks for marketing consent (EU), only the listed clients who agreed get it; the call fails when none can. SMS comes from an automated number, so clients cannot reply, and uses the plan's text allowance. Run estimate_message_blast first to see the count and cost. Needs a paid Booksy plan: on the free trial Booksy refuses one-time messages. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.
Parameters4
channel
string
required
email, sms or push.
message
string
required
Message text.
subject
string
optional
Email subject and push title. Default: the message's start.
Change a client card's name, phone, email, birthday or private note. Changes only the fields given and leaves the rest of the card as it is. The note replaces the card's private note; add_client_note adds a line instead. The client is not told.
Parameters6
name
string
optional
Full name; the last word is the last name.
note
string
optional
Private note, replaces the old one; add_client_note appends.
email
string
optional
Email address; empty string removes it.
phone
string
optional
Mobile phone; empty string removes it.
birthday
string
optional
YYYY-MM-DD.
client_id
integer
required
From list_clients or find_client.
Raw schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Full name; the last word is the last name."
},
"note": {
"type": "string",
"description": "Private note, replaces the old one; add_client_note appends."
},
"email": {
"type": "string",
"description": "Email address; empty string removes it."
},
"phone": {
"type": "string",
"description": "Mobile phone; empty string removes it."
},
"birthday": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD."
},
"client_id": {
"type": "integer",
"description": "From list_clients or find_client."
}
},
"required": [
"client_id"
],
"additionalProperties": false
}
Booksy API and MCP server: connect Booksy to ChatGPT and Claude
Yes, ChatGPT, Claude and other AI agents can work in your Booksy account. That includes Cursor, Codex, OpenClaw and any MCP client, plus automations in n8n, Make and Zapier. Ask in plain words, and the AI reads your calendar and open slots, finds clients who have not been back, moves bookings when someone is off, answers reviews and compares revenue per staff member. It shows you what it will do first and sends nothing to other people until you say so.
As of November 2026, this repo is the missing piece: 28 Booksy tools for AI assistants and scripts.
What you can ask
What does tomorrow look like? List the appointments and any gaps longer than an hour.
Tom is off on Friday. Move his bookings to whoever is free at about the same time, and show me the plan first.
Compare last week's revenue per staff member with the week before.
Which clients have not been in for 60 days and have nothing booked?
sign in to Booksy once, about 5 minutes, nothing to install
Python and a terminal
Works in
ChatGPT and Claude apps, on your phone too, Cursor, Codex, OpenClaw, any MCP client, n8n, Make, Zapier, REST API
Claude Code, Claude Desktop, Cursor, Codex on your computer
Runs
24/7, your computer can be off
while your computer is on
Price
7 days free, no card
free
Cotlet is best for salon, barber and beauty business owners who want ChatGPT, Claude or another AI agent to work in Booksy for them, with nothing to install.
A Booksy API and a Booksy MCP server you run on your own computer, in Python, on the session of your own Google Chrome. All 28 Booksy Biz tools we run in production at Cotlet: the calendar, open slots, time off, clients, services and staff, reviews, Message Blasts and Stats & Reports.
Booksy has no self-serve API for business owners and no official MCP server. This repo gives you both:
MCP server for Claude Code, Claude Desktop, Cursor, Codex and any MCP client, over stdio or HTTP. Setup
REST API on http://127.0.0.1:8787/api/v1/booksy, with OpenAPI docs at /docs. Setup
Python: call("list_appointments", {"from": "2026-10-27", "to": "2026-10-27"}), plus 9 ready scripts in examples/.
Free for your own use, your own business included (license).
Does Booksy have an API?
Not one a business owner can use. Booksy runs a partner API whose docs at docs.booksy.com ask for a login, so you cannot get keys for your own account (checked 11 Oct 2026). Stats & Reports and Message Blasts are not among its public areas. This repo and Cotlet give you 28 Booksy tools as a REST API and an MCP server.
Can I get a Booksy API key?
Not from Booksy for your own account. With Cotlet you get your own API key that works with your Booksy account, for scripts, n8n, Make, Zapier or any HTTP client. This repo needs no key: it runs on your computer, on your own Booksy session.
Is there an official ChatGPT integration for Booksy?
Booksy has a ChatGPT app for clients: it finds pros and books open slots. It does not run your business. Cotlet connects your Booksy Biz account to ChatGPT, Claude and other AI agents: your calendar, clients, staff, reviews, Message Blasts and stats.
How do I connect Booksy to ChatGPT?
Sign up at cotlet.dev, sign in to Booksy once in your Cloud Browser there, and add Cotlet to ChatGPT, following the steps in your account. Then ask ChatGPT about your Booksy like you would ask an assistant. ChatGPT needs a server on the internet, so this repo alone, running on your computer, does not connect to ChatGPT.
Can ChatGPT manage my Booksy calendar?
Yes, with Cotlet. It lists tomorrow's appointments and gaps, finds open slots, blocks time off and plans moves when a staff member is off. It shows you the plan before it changes anything.
Can AI bring back Booksy clients who stopped booking?
Yes, with Cotlet. It finds clients who have not been in for a while and have nothing booked, so you can send them a Message Blast or a personal note.
Can I automate Booksy with Zapier, Make or n8n?
We could not confirm a Booksy Zapier app. With Cotlet, n8n, Make and Zapier can read appointments and clients and send Message Blasts, for example to copy new bookings into a Google Sheet.
Can I use it from my phone?
Yes, with Cotlet: once it is set up, the ChatGPT and Claude apps on your phone can use Booksy for you.
Do I need to be technical?
For Cotlet, no: you sign in to Booksy and add Cotlet to ChatGPT or Claude, with step-by-step instructions in your account. This repo is for people who are fine with Python and a terminal.
Is my Booksy account safe?
Yes. Neither Cotlet nor this repo sees or stores your Booksy password. You sign in yourself, the way you always do, and the AI works on that signed-in session. Anything that reaches other people asks for your OK first: in Cotlet by default, here through your MCP client.
Is it free?
This repo is free, also in your own business. Cotlet is free for 7 days with no card, then one-time credit packs from $29, no subscription. Pricing.
I manage Booksy for several accounts or clients. Does that work?
Yes, with Cotlet. Each Booksy login gets its own connection. Write to contact@cotlet.dev and tell us how many accounts you manage.
How it works
text
AI agent (MCP) / script (REST, Python) ──▶ booksy-mcp on your computer ──your Booksy session──▶ <country>.booksy.com
▲
booksy-mcp connect ───────┘ reads it once from your Chrome (DevTools Protocol)
You sign in to Booksy Biz in your own Chrome at booksy.com/pro, the way you always do.
booksy-mcp connect attaches to that Chrome through the Chrome DevTools Protocol and reads your session. Booksy does not keep it in a cookie. The panel stores it in the localStorage of its web-gateway.booksy.com frame, so connect reads that storage, the booksy.com cookies and the panel's country, and saves them to ~/.config/booksy-api-mcp/session.json, readable by your user only. It never sees or stores your password.
Every tool call is a request to the API the Booksy Biz web panel calls (<country>.booksy.com/core/v2, so us.booksy.com for a US business and pl.booksy.com for a Polish one), sent with curl_cffi, which copies Chrome's TLS fingerprint. No headless browser runs.
When Booksy signs you out, the server reads the session from Chrome again, if Chrome is open with remote debugging on.
Requirements
Python 3.11 or newer.
Google Chrome 144 or newer, signed in to Booksy Biz. Any Chrome or Chromium works with a debugging port.
macOS, Linux or Windows.
A Booksy Biz owner account. Some reports, such as Staff Members, need Booksy Biz Pro. Booksy sends one-time Message Blasts on a paid plan only, not during the free trial.
With uv: uv venv && uv pip install -e ., then uv run booksy-mcp ....
Setting it up with an AI agent (Claude Code, Codex, Cursor)? Open it in this folder and ask it to set up the repo: AGENTS.md tells it every step, and it asks you only for the steps in Chrome.
To update: uv tool upgrade booksy-api-mcp (or pip install -U booksy-api-mcp), from source git pull && pip install -e .. We copy every change of the hosted Booksy tools into this repo.
Connect your Chrome
Option A: your everyday Chrome (recommended)
Open chrome://inspect/#remote-debugging in Chrome and switch remote debugging on. Chrome then accepts DevTools connections from programs on this computer, and asks you before each one.
Make sure you are signed in to Booksy Biz at booksy.com/pro. Keep a tab of the panel open, because connect reads the session in it. With no Booksy tab open, it opens one in the background and closes it again.
Run:
bash
booksy-mcp connect
Chrome asks whether to allow the connection. Click Allow.
text
Saved 41 Booksy cookies and 50 localStorage keys to /Users/you/.config/booksy-api-mcp/session.json
Signed in to Booksy as Maria Lopez (Studio Maria)
You can switch remote debugging off again afterwards. Leave it on if you want the server to pick up a new session by itself after Booksy signs you out.
connect looks for Chrome's DevToolsActivePort file in the default profile folder. For Chrome Beta, Canary or a custom profile folder, pass --profile-dir "<folder>".
Option B: a Chrome with a debugging port
Chrome does not open a debugging port on your default profile, so start a separate one, sign in to Booksy Biz there once, and connect to it:
--cdp also takes a ws:// DevTools URL, for example of a Chrome on another machine reached over an SSH tunnel.
There is no option to paste a cookie by hand, since Booksy has no session cookie. A server with no Chrome can use a session.json copied from a machine where connect ran.
Check the session at any time:
bash
booksy-mcp status
MCP server
The MCP server lists every tool with its input schema, a description written for agents, and hints. Read tools are marked read-only, and tools that reach clients (bookings, reschedules, cancellations, review replies, blasts) are marked so your client asks before running them.
Claude Code
bash
claude mcp add booksy -- uvx booksy-api-mcp mcp
# read only:
claude mcp add booksy -- uvx booksy-api-mcp mcp --read-only
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
booksy-mcp serve also serves MCP over streamable HTTP at http://127.0.0.1:8787/mcp, for clients that take a URL:
bash
booksy-mcp serve
claude mcp add --transport http booksy http://127.0.0.1:8787/mcp
Then ask your agent things like:
What does tomorrow look like? List the appointments and any gaps longer than an hour.
Tom is off on Friday. Move his bookings to whoever is free at about the same time, and show me the plan first.
Compare last week's revenue per staff member with the week before.
Which clients have not been in for 60 days and have nothing booked?
REST API
bash
booksy-mcp serve # http://127.0.0.1:8787, MCP at /mcp, docs at /docs
Each tool has its own route under /api/v1/booksy, the same paths as the hosted API at cotlet.dev, so code written against one works with the other. Path parts and the query string are arguments, and a JSON body adds the rest.
curl -X POST http://127.0.0.1:8787/api/v1/booksy/tools/find_client -d '{"query": "nowak"}'
GET /api/v1/booksy/tools: every tool with its route, input schema and an example answer.
GET /docs: interactive OpenAPI docs, GET /openapi.json the schema, for n8n, Postman or a generated client.
Answers are JSON. list_clients returns next_cursor; pass it back as cursor for the next page. Reviews and notifications take page.
The server listens on 127.0.0.1 only. To reach it from another device of yours, set a token, and every request then needs Authorization: Bearer <token>:
Or one tool from the shell: booksy-mcp call find_open_slots service_id=8307205 date=2026-10-27, or with a JSON object. An ID stays text where the tool takes text.
Times are local to the business. A date-time without a zone is read in the business's time zone, and answers carry its offset.
Ready scripts in examples/. Each prints JSON or a short list, takes --out file.csv or --out file.json where it makes sense, and --help:
Moves one staff member's appointments on a day to colleagues free within an hour of the original time. Prints the plan; --apply moves them, asking each time.
On a schedule, cron on your own computer works while it is on: 0 19 * * * cd ~/booksy-api-mcp-server && .venv/bin/python examples/tomorrows_appointments.py.
All 28 tools
IDs come from the list tools: service_id from list_services, staff_id from list_staff, client_id from list_clients or find_client, appointment_id from list_appointments. booksy-mcp tools prints this list, booksy-mcp tools --json adds the input schemas.
Calendar
Tool
Access
REST route
What it does
list_appointments
read
GET /appointments
Appointments in a date range with client, service, staff, time and status.
get_appointment
read
GET /appointments/{appointment_id}
One appointment: services, staff, times, price, client and notes.
find_open_slots
read
GET /services/{service_id}/open-slots
Free start times for a service on one day, from working hours, bookings, blocks and time off.
create_appointment
write
POST /clients/{client_id}/appointments
Book a client for one or more services at a start time; Booksy checks the slots first.
reschedule_appointment
write
POST /appointments/{appointment_id}/reschedule
Change an appointment: a new start time, another staff member, or other services.
cancel_appointment
write
POST /appointments/{appointment_id}/cancel
Cancel an appointment and free its time in the calendar.
Time off
Tool
Access
REST route
What it does
list_time_off
read
GET /time-offs
Staff time off and blocked hours in a date range.
add_time_off
write
POST /staffs/{staff_id}/time-offs
Block a staff member's calendar so no one can book it: whole days off or a few hours.
remove_time_off
write
DELETE /staffs/{staff_id}/time-offs/{time_off_id}
Remove time off or a blocked period so the time can be booked again.
Clients
Tool
Access
REST route
What it does
list_clients
read
GET /clients
Clients with contact details, visit counts and last visit, plus Booksy's client groups.
find_client
read
GET /clients/search
Client cards matching a name, email or phone.
get_client
read
GET /clients/{client_id}
One client card: contact details, private note, counts and visit history.
add_client
write
POST /clients
Add a client card to your client list. Needs a phone or an email.
update_client
write
PATCH /clients/{client_id}
Change a client card's name, phone, email, birthday or private note.
add_client_note
write
POST /clients/{client_id}/notes
Add a dated line to a client's private note, keeping what is there.
delete_client
write
DELETE /clients/{client_id}
Remove a client card from your client list.
Business setup
Tool
Access
REST route
What it does
list_services
read
GET /services
Your service menu with category, variants, duration, price and the staff who offer each.
list_staff
read
GET /staff
Staff members with their working hours for a week and the services they offer.
get_business_hours
read
GET /business-hours
Weekly opening hours, time zone and booking lead times of the business.
get_business_profile
read
GET /business
Your business's name, address, contact, opening hours, booking policy, rating and plan status.
get_settings
read
GET /settings
Text message allowance and usage, client message channels and your notification settings.
list_notifications
read
GET /notifications
Notifications from the panel's bell: new bookings, changes, cancellations, reviews.
Reviews
Tool
Access
REST route
What it does
list_reviews
read
GET /reviews
Client reviews of your business with rating, text, services, staff and your reply.
reply_to_review
write
PUT /reviews/{review_id}/reply
Post or change your public reply to a client's review.
Message Blasts
Tool
Access
REST route
What it does
list_message_blasts
read
GET /message-blasts
Message Blast templates (automated and one-time) and the blasts scheduled to go out.
estimate_message_blast
read
GET /message-blasts/estimate
Count who a Message Blast would reach and its SMS cost, without sending it.
send_message_blast
write
POST /message-blasts
Send one message to chosen clients by email, SMS or push notification.
Stats & Reports
Tool
Access
REST route
What it does
get_report
read
GET /reports/{category}
Numbers from Stats & Reports for a day, week, month or year, as JSON.
Writes run Booksy's own dry run first, and send the client no notice unless you pass notify_client. New clients get no invitation. send_message_blast refuses an empty client list, because Booksy reads an empty list as every client.
Never built, on purpose: your Booksy sign-in, email, password and account deletion, and anything that moves money (subscription, payments, payouts, billing). Every request passes a guard that refuses those Booksy paths.
Configuration
Variable
Default
What it does
BOOKSY_MCP_HOME
~/.config/booksy-api-mcp
Folder of session.json.
BOOKSY_PROXY
Proxy for every request to Booksy, e.g. http://user:pass@host:port.
BOOKSY_MCP_READ_ONLY
1 hides and refuses every tool that changes Booksy (same as --read-only).
BOOKSY_MCP_TOKEN
Bearer token required by serve; needed to listen beyond 127.0.0.1.
BOOKSY_MCP_HOST, BOOKSY_MCP_PORT
127.0.0.1, 8787
Address of serve.
Security and your Booksy account
Your password never reaches this code. Only the session the panel already keeps is read, and only that of booksy.com.
The session file is yours.session.json is created with mode 0600 and holds your Booksy access token. Anyone who has it can act as you in Booksy Biz, so keep it out of git and shared folders.
Local by default.serve binds to 127.0.0.1 and refuses another address without BOOKSY_MCP_TOKEN.
booksy.com only. Requests and redirects outside booksy.com are refused.
Read-only mode.--read-only or BOOKSY_MCP_READ_ONLY=1 exposes the 17 read tools only.
Actions reach real people. A booking, a move with notify_client, a cancellation, a review reply and a blast reach your clients. MCP clients ask before running them; a script does not, so try it on a test client of your own first.
Do not spam. Blasts to people who did not agree break Booksy's rules and the law in many countries. You are responsible for what runs in your account.
Errors
The REST API answers {"error": "<code>", "message": "..."}. The MCP server returns the same code and message as a tool error.
Status
Code
What to do
401
auth_required, auth_expired
No session, or Booksy signed you out. Sign in to Booksy Biz in Chrome and run booksy-mcp connect.
403
app_permission_denied
Your Booksy plan or role cannot do this, e.g. a Pro report on Booksy Biz Lite.
403
scope_denied
The server runs read-only, or the request would change your Booksy account itself.
403
target_blocked
Booksy refused the request or showed a bot check. Open the panel in Chrome once, then retry.
409
captcha_required
Booksy asks for a CAPTCHA. Solve it in Chrome.
422
invalid_input
An argument is missing or wrong; the message names it.
429
rate_limited
Booksy is limiting the account. Wait a few minutes.
502
target_error
Booksy answered with an error, or changed its panel. git pull for the latest tools, or open an issue.
your own Cloud Browser in the EU, profile encrypted with AES-256-GCM
When Booksy changes its panel
git pull once we have fixed it
fixed for you, every tool tested daily
Approvals
your MCP client asks per call
bookings, reschedules, replies and blasts wait for your OK, switchable per tool
Works with
MCP clients on your machine, local scripts
Claude.ai and ChatGPT connectors, n8n, Make, Zapier, any HTTP client
Who may use it
you and your own business
you, teams, businesses, agencies
Price
free
free 7-day trial with 2,000 credits, no card; then one-time packs from $29 for 5,000 credits
On the hosted version a successful call uses 10 credits for most tools, failed calls are free, and the Cloud Browser uses 50 credits a day while it has an app enabled for agents. Full pricing.
FAQ
Is there a Booksy MCP server for Claude, ChatGPT or Cursor?
Yes, this one runs on your machine: booksy-mcp mcp for Claude Code, Claude Desktop, Cursor and Codex. ChatGPT and Claude.ai connectors need a public HTTPS URL, which the hosted Booksy MCP server gives you.
Is there a Booksy Zapier app?
We could not confirm one. Owners who want bookings elsewhere forward Booksy confirmation emails to a Zapier email parser. That copies new bookings one way and cannot change anything in Booksy.
Can I export my Booksy clients to CSV?
Yes: python examples/export_clients.py --out clients.csv. Every client card with contact details, note, visits, no-shows, revenue and last visit, across all pages.
Can it find free slots and book for me?find_open_slots gives the free starts for a service on a day, per staff member, each checked with Booksy's own dry run. create_appointment books one of them for a client, and the client hears about it only with notify_client.
Can it send Message Blasts?
Yes, send_message_blast by email, SMS or push, on a paid Booksy plan. Run estimate_message_blast first for the reach and the SMS cost. In the EU only clients who gave marketing consent get it.
Does it work outside the US?
Yes. Booksy runs a separate API per country, and the server picks it from your session: us.booksy.com, pl.booksy.com, es.booksy.com and so on.
Why does it need my Chrome?
To read your Booksy session without your password. Chrome is used once per sign-in, not for each call.
What happens when Booksy signs me out?
Calls fail with auth_expired. With Chrome remote debugging on, the server reads the new session on the next call (click Allow when Chrome asks). Otherwise run booksy-mcp connect again.
Can it run on a VPS or in Docker?
Technically yes, with a session.json copied from your computer. Booksy then sees your session from a datacenter IP, which looks less like you. For an always-on setup the hosted version keeps your session in your own Cloud Browser on a fixed IP.
Will my Booksy account get banned?
Requests carry Chrome's fingerprint and go out one at a time, as you would click. Nobody can promise a platform never acts. Keep to your normal use and do not blast people who did not agree.
Can I use it for my salon or for my clients?
For your own salon, yes, free. You may not offer it to others as a hosted or managed service. For client work, use Cotlet or write to contact@cotlet.dev.
Is it open source?
The source is public under the Elastic License 2.0: free to use and change, also in your own business, but not to resell as a hosted service.
A tool broke or I need another one.Open an issue with the tool name and the error message.
Allowed: using it for yourself and in your own business, free. Changing the code and sharing it under the same license.
Not allowed: offering it to others as a hosted or managed service, removing the license notices, getting around its limits.
Maintained by Cotlet (@cotletdev). Booksy is a trademark of its owner. This project is unofficial and not affiliated with, endorsed or sponsored by Booksy.