BookingKoala home service booking MCP server: list bookings, assign provider, reschedule booking.
MCP Server: dev.cotlet/bookingkoala
This MCP server (“dev.cotlet/bookingkoala”) provides access to BookingKoala store data focused on bookings, providers, and customers. It is intended to expose information related to those entities through MCP integration, based on the server’s description.
🛠️ Key Features
Bookings data
Providers data
Customers data
🚀 Use Cases
Retrieve booking records from a BookingKoala store
View or manage the list of providers associated with bookings
Access customer information tied to store activity
⚡ Developer Benefits
Structured access to BookingKoala entities (bookings, providers, customers) via MCP
⚠️ Limitations
No additional capabilities, tool count, or configuration 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 BookingKoala Cloud Browser, a real Chrome hosted on Cotlet and signed in to BookingKoala as the user. Use it for what the BookingKoala 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 BookingKoala Cloud Browser and returns the URL and title it ended on. Only BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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 BookingKoala 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: BookingKoala.
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: BookingKoala."
},
"task": {
"type": "string",
"maxLength": 500,
"description": "What the user wants done in the app, in their words."
}
},
"additionalProperties": false
}
dashboard
Store totals for a date range: revenue, provider pay, bookings, ratings, referrals. Returns the figures of the admin Dashboard for the dates given (this month by default): revenue paid and pending, split into bookings, custom invoices and separate charges; what providers earned and what is still unpaid; booking counts, unassigned and cancelled included; ratings and referrals. Amounts are in the store's currency.
Parameters2
end_date
string
optional
YYYY-MM-DD, included. Default: last day of this month.
start_date
string
optional
YYYY-MM-DD. Default: first day of this month.
Raw schema
{
"type": "object",
"properties": {
"end_date": {
"type": "string",
"description": "YYYY-MM-DD, included. Default: last day of this month."
},
"start_date": {
"type": "string",
"description": "YYYY-MM-DD. Default: first day of this month."
}
},
"required": [],
"additionalProperties": false
}
get_booking
One booking with its price breakdown, provider pay, notes and service. Reads a booking by id: date and arrival window, customer, address, assigned providers, the service parameters and extras, notes, the price breakdown (service total, discounts, tax, tip, final amount) and what the providers are paid for it.
One customer: contact details, addresses, booking counts and bookings not charged yet. Returns the customer's profile as their page in the admin shows it: name, email, phone, saved addresses (address_id is what a booking or invoice for this customer uses), counts of upcoming and cash bookings, the bookings not charged yet (past ones included), gift cards received and the referral summary. Times of day are in the store's time zone.
One provider or team: contact, category, team members, reviews and payment logs. Returns the provider's profile as their page in the admin shows it: contact details, IC or W2 category, priority, scheduling permissions, the team's members and lead (for a team) or the teams it belongs to, customer reviews and the newest payment logs (what the store paid the provider). Payment logs come as BookingKoala records them.
Parameters2
provider_id
integer
required
provider_id from list_providers (a team too).
payment_logs_limit
integer
optional
Newest payment logs to include, 1 to 50. Default: 20.
Raw schema
{
"type": "object",
"properties": {
"provider_id": {
"type": "integer",
"description": "provider_id from list_providers (a team too)."
},
"payment_logs_limit": {
"type": "integer",
"description": "Newest payment logs to include, 1 to 50. Default: 20."
}
},
"required": [
"provider_id"
],
"additionalProperties": false
}
list_bookings
Bookings of the store: upcoming, unassigned, completed, charge pending or declined. Lists bookings as the Bookings page shows them, newest schedule dates first within the filter, with the customer, address, assigned providers, total and whether it is charged. Filter by status, date range, a search on the customer, or one customer or provider. Cancelled bookings are not listed. Page with next_cursor.
Parameters8
limit
integer
optional
Page size. Default: 20.
cursor
string
optional
next_cursor from the previous call.
search
string
optional
Customer name, email or phone.
status
string
optional
Which bookings: upcoming (default), today, unassigned, completed, pending (charge pending), declined (charge declined), paused or all.
Charged bookings with their payments and refunds, as the Charges page lists them. Returns bookings that were charged, newest first, each with its payments: the booking charge, extras, tips, fees and refunds, with amount, tax, refunded amount and card. Filter by booking day and search by customer. BookingKoala gives no total: next_cursor is set while a full page comes back. booking_id and payment_log_id go to refund_charge. Empty until the store charges through a connected payment processor or marks bookings paid in cash.
Parameters5
limit
integer
optional
1 to 100. Default: 20.
cursor
string
optional
next_cursor from the previous call.
search
string
optional
Customer name, email or phone, or a booking id.
end_date
string
optional
Last booking day, YYYY-MM-DD. Default: no upper bound.
start_date
string
optional
First booking day, YYYY-MM-DD. Default: no lower bound.
Raw schema
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "1 to 100. Default: 20."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous call."
},
"search": {
"type": "string",
"description": "Customer name, email or phone, or a booking id."
},
"end_date": {
"type": "string",
"description": "Last booking day, YYYY-MM-DD. Default: no upper bound."
},
"start_date": {
"type": "string",
"description": "First booking day, YYYY-MM-DD. Default: no lower bound."
}
},
"required": [],
"additionalProperties": false
}
list_customers
Customers of the store, with email and phone; search by name, email or phone. Returns the store's customers as the Customers page lists them, newest first, active or deactivated. BookingKoala gives no total: next_cursor is set while a full page comes back. Use customer_id in get_customer.
Parameters4
limit
integer
optional
1 to 100. Default: 20.
cursor
string
optional
next_cursor from the previous call.
search
string
optional
Part of a name, email or phone number.
status
string
optional
active or inactive (deactivated) customers. Default: active.
Raw schema
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "1 to 100. Default: 20."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous call."
},
"search": {
"type": "string",
"description": "Part of a name, email or phone number."
},
"status": {
"enum": [
"active",
"inactive"
],
"type": "string",
"description": "active or inactive (deactivated) customers. Default: active."
}
},
"required": [],
"additionalProperties": false
}
list_drafts
Draft bookings and quotes saved in the store, not yet booked. Lists the drafts and quotes on the Drafts page: customer, date when set, total and whether it is a quote. create_booking leaves a draft here. Page with next_cursor.
Invoices of the store or of one customer, with payment status, total and amount due. Returns invoices as the Invoices page lists them, newest first: number, customer, booking or custom type, payment status (paid, unpaid, partially_paid, void, uncollectible), total, paid, amount due, issue and due dates. Filter by customer, payment status and issue dates (default: two years back to a year ahead), or search by number, email, name or phone. BookingKoala gives no total: next_cursor is set while a full page comes back. invoice_id goes to resend_invoice.
Parameters7
limit
integer
optional
1 to 100. Default: 20.
cursor
string
optional
next_cursor from the previous call.
search
string
optional
Invoice number, customer email, name or phone.
end_date
string
optional
To this issue day, YYYY-MM-DD. Default: a year ahead.
pay_status
string
optional
Payment status filter.
start_date
string
optional
From this issue day, YYYY-MM-DD. Default: 2 years ago.
customer_id
integer
optional
Only this customer's invoices.
Raw schema
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "1 to 100. Default: 20."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous call."
},
"search": {
"type": "string",
"description": "Invoice number, customer email, name or phone."
},
"end_date": {
"type": "string",
"description": "To this issue day, YYYY-MM-DD. Default: a year ahead."
},
"pay_status": {
"enum": [
"paid",
"unpaid",
"partially_paid",
"void",
"uncollectible"
],
"type": "string",
"description": "Payment status filter."
},
"start_date": {
"type": "string",
"description": "From this issue day, YYYY-MM-DD. Default: 2 years ago."
},
"customer_id": {
"type": "integer",
"minimum": 1,
"description": "Only this customer's invoices."
}
},
"required": [],
"additionalProperties": false
}
list_providers
Providers (cleaners, technicians) and teams of the store, in priority order. Returns the store's service providers as the Providers page lists them, single providers and teams together; type team returns teams only. A team lists its members' provider ids, a provider the teams it belongs to and leads. BookingKoala gives no total: next_cursor is set while a full page comes back. Use provider_id in get_provider and when assigning a booking.
Parameters5
type
string
optional
all: providers and teams (default). team: teams only.
limit
integer
optional
1 to 100. Default: 20.
cursor
string
optional
next_cursor from the previous call.
search
string
optional
Part of a name, email or phone number.
status
string
optional
active or inactive (deactivated) providers. Default: active.
Raw schema
{
"type": "object",
"properties": {
"type": {
"enum": [
"all",
"team"
],
"type": "string",
"description": "all: providers and teams (default). team: teams only."
},
"limit": {
"type": "integer",
"description": "1 to 100. Default: 20."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous call."
},
"search": {
"type": "string",
"description": "Part of a name, email or phone number."
},
"status": {
"enum": [
"active",
"inactive"
],
"type": "string",
"description": "active or inactive (deactivated) providers. Default: active."
}
},
"required": [],
"additionalProperties": false
}
assign_provider
Assign a provider or team to a booking, or to its whole recurring schedule. Puts the provider on the booking, as Assign in the booking's sidebar does, and returns the booking as get_booking shows it. BookingKoala tells the provider about the job. A provider who is not available at that time is refused unless even_if_unavailable is true. Waits for the owner's approval.
Parameters4
booking_id
integer
required
Booking id from list_bookings.
provider_id
integer
required
Provider or team id from list_providers.
whole_schedule
boolean
optional
Assign every later booking of the recurring schedule too. Default: false.
even_if_unavailable
boolean
optional
Assign although the provider is not available then. Default: false.
Raw schema
{
"type": "object",
"properties": {
"booking_id": {
"type": "integer",
"minimum": 1,
"description": "Booking id from list_bookings."
},
"provider_id": {
"type": "integer",
"minimum": 1,
"description": "Provider or team id from list_providers."
},
"whole_schedule": {
"type": "boolean",
"description": "Assign every later booking of the recurring schedule too. Default: false."
},
"even_if_unavailable": {
"type": "boolean",
"description": "Assign although the provider is not available then. Default: false."
}
},
"required": [
"booking_id",
"provider_id"
],
"additionalProperties": false
}
cancel_booking
Cancel one booking or its whole recurring schedule, without a cancellation fee. Checks the store's cancellation rules first (a store that requires a reason gets the 'Other' reason with your text), then cancels as Cancel in the booking's sidebar does, with no fee. Nobody is told unless notify is true. Cancelled bookings leave list_bookings. Waits for the owner's approval.
Parameters4
notify
boolean
optional
Email the customer and providers about it. Default: false.
reason
string
optional
Why it is cancelled (kept on the booking).
booking_id
integer
required
Booking id from list_bookings.
whole_schedule
boolean
optional
Cancel the whole recurring schedule from this booking on. Default: false.
Raw schema
{
"type": "object",
"properties": {
"notify": {
"type": "boolean",
"description": "Email the customer and providers about it. Default: false."
},
"reason": {
"type": "string",
"description": "Why it is cancelled (kept on the booking)."
},
"booking_id": {
"type": "integer",
"minimum": 1,
"description": "Booking id from list_bookings."
},
"whole_schedule": {
"type": "boolean",
"description": "Cancel the whole recurring schedule from this booking on. Default: false."
}
},
"required": [
"booking_id"
],
"additionalProperties": false
}
create_booking
Start a new booking as a copy of an existing one: same customer, service and price. Copies the booking as Duplicate in its sidebar does. The copy is saved as a draft (list_drafts) with the same customer, address, service, extras and price; open form_url to pick the date and book it. Nobody is told until it is booked.
New customer in the store. BookingKoala emails them an invitation to set a password. Adds a customer as Add Customer in the admin does, with an optional address that becomes their default service address. BookingKoala emails the customer at once to set a password for the store's booking page, so use their real address. An email already in the store is refused. Returns the new customer as get_customer does. Waits for the owner's approval.
Parameters12
apt
string
optional
Apartment or suite.
city
string
optional
City.
email
string
required
Email address. BookingKoala sends the customer an invitation to set a password.
phone
string
optional
Phone number, digits only for US numbers, e.g. 2125550147.
state
string
optional
State, e.g. New York.
gender
string
optional
Gender, optional.
address
string
optional
Street address, e.g. 540 W 28th Street, New York, NY, USA.
country
string
optional
Country, e.g. United States.
zipcode
string
optional
ZIP or postal code.
last_name
string
required
Last name.
first_name
string
required
First name.
sms_notifications
boolean
optional
Text the customer booking updates. Default: false.
Raw schema
{
"type": "object",
"properties": {
"apt": {
"type": "string",
"description": "Apartment or suite."
},
"city": {
"type": "string",
"description": "City."
},
"email": {
"type": "string",
"description": "Email address. BookingKoala sends the customer an invitation to set a password."
},
"phone": {
"type": "string",
"description": "Phone number, digits only for US numbers, e.g. 2125550147."
},
"state": {
"type": "string",
"description": "State, e.g. New York."
},
"gender": {
"enum": [
"male",
"female",
"other"
],
"type": "string",
"description": "Gender, optional."
},
"address": {
"type": "string",
"description": "Street address, e.g. 540 W 28th Street, New York, NY, USA."
},
"country": {
"type": "string",
"description": "Country, e.g. United States."
},
"zipcode": {
"type": "string",
"description": "ZIP or postal code."
},
"last_name": {
"type": "string",
"description": "Last name."
},
"first_name": {
"type": "string",
"description": "First name."
},
"sms_notifications": {
"type": "boolean",
"description": "Text the customer booking updates. Default: false."
}
},
"required": [
"first_name",
"last_name",
"email"
],
"additionalProperties": false
}
refund_charge
Refund a paid booking charge, extra, tip or fee to the customer's card, in full or in part. Refunds one payment from list_charges (payment_log_id and its booking_id) through the store's payment processor, as the Refund popup of the Charges page does. amount includes tax and defaults to what is not refunded yet; less than that is a partial refund. Cancellation and reschedule fees are refunded only in full. The customer is not emailed unless notify_customer is true. Refused before you confirm when the store has no payment processor, the payment is not paid or the amount is too large. A booking paid partly with a gift card or referral credit is refunded in the panel. Money goes back to the customer and cannot be taken back. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.
Parameters5
amount
number
optional
Amount to refund, tax included. Default: everything not refunded yet.
reason
string
required
Refund reason.
booking_id
integer
required
Booking id from list_bookings.
payment_log_id
integer
required
payment_log_id of a paid payment, from list_charges.
notify_customer
boolean
optional
Email the customer about the refund. Default: false.
Raw schema
{
"type": "object",
"properties": {
"amount": {
"type": "number",
"description": "Amount to refund, tax included. Default: everything not refunded yet.",
"exclusiveMinimum": 0
},
"reason": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Refund reason."
},
"booking_id": {
"type": "integer",
"minimum": 1,
"description": "Booking id from list_bookings."
},
"payment_log_id": {
"type": "integer",
"minimum": 1,
"description": "payment_log_id of a paid payment, from list_charges."
},
"notify_customer": {
"type": "boolean",
"description": "Email the customer about the refund. Default: false."
}
},
"required": [
"payment_log_id",
"booking_id",
"reason"
],
"additionalProperties": false
}
reschedule_booking
Postpone a visit of a recurring booking to the date of a later visit in its schedule. Works like Postpone in the booking's sidebar: the visit moves to one of the schedule's later visit dates, keeping its arrival time and price, and the booking comes back as get_booking shows it. A date outside the schedule fails with the list of allowed dates. One-time bookings cannot be postponed. Nobody is told unless notify is true. A store that charges a reschedule fee refuses the move here: charge it in the panel. Waits for the owner's approval.
Parameters3
date
string
required
New date: one of the later visit dates of the booking's recurring schedule.
notify
boolean
optional
Email the customer and providers about the change. Default: false.
booking_id
integer
required
Booking id from list_bookings.
Raw schema
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "New date: one of the later visit dates of the booking's recurring schedule."
},
"notify": {
"type": "boolean",
"description": "Email the customer and providers about the change. Default: false."
},
"booking_id": {
"type": "integer",
"minimum": 1,
"description": "Booking id from list_bookings."
}
},
"required": [
"booking_id",
"date"
],
"additionalProperties": false
}
resend_invoice
Send an invoice to its customer again by email, text or both. Sends an existing invoice from list_invoices to its customer again, as the invoice's Resend button does: by email (default) and, with sms true, a text with the invoice link. The invoice's CC and billing addresses get the email too. attach_pdf defaults to the invoice's own setting. The invoice itself does not change. The customer gets it at once. BookingKoala refuses some resends with a warning, for example a void invoice; the error carries its message. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.
Parameters4
sms
boolean
optional
Text the invoice link to the customer. Default: false.
email
boolean
optional
Email the invoice to the customer. Default: true.
attach_pdf
boolean
optional
Attach the PDF to the email. Default: as the invoice.
invoice_id
string
required
invoice_id from list_invoices.
Raw schema
{
"type": "object",
"properties": {
"sms": {
"type": "boolean",
"description": "Text the invoice link to the customer. Default: false."
},
"email": {
"type": "boolean",
"description": "Email the invoice to the customer. Default: true."
},
"attach_pdf": {
"type": "boolean",
"description": "Attach the PDF to the email. Default: as the invoice."
},
"invoice_id": {
"type": "string",
"pattern": "^[0-9a-f]{24}$",
"description": "invoice_id from list_invoices."
}
},
"required": [
"invoice_id"
],
"additionalProperties": false
}
send_quote
Email a saved quote to the customer with a link to book it. Sends a quote from list_drafts as the Send quote popup does: saves the recipient and expiry date on the quote, then emails the store's Send quote template (or your subject and message) with the quote's booking link. email defaults to the quote's customer; expires_on to the saved date, else a month ahead. Only drafts saved as quotes can be sent; a plain draft is refused before you confirm. The customer gets the email at once. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.
Parameters5
email
string
optional
Send to this address. Default: the quote's customer.
message
string
optional
Email body (HTML allowed). Default: the store's Send quote template.
subject
string
optional
Email subject. Default: the store's.
draft_id
integer
required
Id of a quote from list_drafts.
expires_on
string
optional
Last day the customer can book it, YYYY-MM-DD. Default: as saved, else a month ahead.
Raw schema
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Send to this address. Default: the quote's customer."
},
"message": {
"type": "string",
"description": "Email body (HTML allowed). Default: the store's Send quote template."
},
"subject": {
"type": "string",
"maxLength": 200,
"description": "Email subject. Default: the store's."
},
"draft_id": {
"type": "integer",
"minimum": 1,
"description": "Id of a quote from list_drafts."
},
"expires_on": {
"type": "string",
"description": "Last day the customer can book it, YYYY-MM-DD. Default: as saved, else a month ahead."
}
},
"required": [
"draft_id"
],
"additionalProperties": false
}
BookingKoala API and MCP server: connect BookingKoala to ChatGPT and Claude
Yes, ChatGPT, Claude and other AI agents can work in your BookingKoala account. That includes Cursor, Codex, OpenClaw and any MCP client, plus automations in n8n, Make and Zapier. Ask in plain words, and the AI finds unassigned bookings, assigns providers, drafts quotes, follows up on unpaid invoices and reports on your store. 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: 17 BookingKoala tools for AI assistants and scripts.
What you can ask
Go through the unassigned folder for this week. Give each job to the free provider with the fewest bookings that day, and tell me which jobs nobody can take.
Thursday is a storm day. Move every Thursday booking to its next visit and email the customers and providers.
Which invoices are more than 7 days overdue? Send each customer the invoice again.
How much revenue and provider pay did we have from 1 to 15 November?
sign in to BookingKoala 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 cleaning and home service business owners who want ChatGPT, Claude or another AI agent to work in BookingKoala for them, with nothing to install.
A BookingKoala API and a BookingKoala MCP server you run on your own computer, in Python, on the session of your own Google Chrome. 17 of the 18 BookingKoala tools we run in production at Cotlet: bookings, drafts and quotes, customers, providers and teams, charges, invoices and the store dashboard.
BookingKoala has no public API and no official MCP server. Its API key only connects Zapier and Make, which react to new events and can write back one thing, a lead. 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/bookingkoala, with OpenAPI docs at /docs. Setup
Python: call("list_bookings", status="unassigned"), plus 12 ready scripts in examples/.
Free for your own use, your own business included (license).
Does BookingKoala have an API?
Not a public one. BookingKoala publishes no REST API docs. The API key under Settings > General > Apps & Integrations only connects Zapier and Make: triggers for new or updated bookings, customers, providers, quotes, ratings and invoices, and one action, Create Lead. It cannot look up past bookings, assign a provider, reschedule, cancel or resend an invoice. This repo and Cotlet give you 17 BookingKoala tools as a REST API and an MCP server.
Can I get a BookingKoala API key?
BookingKoala's own key only connects Zapier and Make. With Cotlet you get your own API key that works with your BookingKoala store, for scripts, n8n, Make, Zapier or any HTTP client. This repo needs no key: it runs on your computer, on your own BookingKoala session.
Is there an official ChatGPT integration for BookingKoala?
No. BookingKoala has no official ChatGPT or Claude connector. Cotlet is an unofficial one that works today, in the ChatGPT and Claude apps and in any AI agent that takes an MCP server.
How do I connect BookingKoala to ChatGPT?
Sign up at cotlet.dev, sign in to BookingKoala once in your Cloud Browser there, and add Cotlet to ChatGPT, following the steps in your account. Then ask ChatGPT about your BookingKoala 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 BookingKoala bookings?
Yes, with Cotlet. It lists today's and unassigned bookings, assigns providers, reschedules, drafts quotes and checks what is unpaid. It shows you every change first.
Can I automate BookingKoala with Zapier, Make or n8n?
BookingKoala's own key only connects Zapier and Make for new-event triggers and one action, Create Lead. With Cotlet, n8n, Make and Zapier can also read past bookings, assign providers and work with quotes and invoices.
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 BookingKoala for you.
Do I need to be technical?
For Cotlet, no: you sign in to BookingKoala 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 BookingKoala account safe?
Yes. Neither Cotlet nor this repo sees or stores your BookingKoala 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 BookingKoala for several accounts or clients. Does that work?
Yes, with Cotlet. Each BookingKoala 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) ──▶ bookingkoala-mcp on your computer ──your session──▶ yourstore.bookingkoala.com
▲
bookingkoala-mcp connect ─────┘ reads it once from your Chrome (DevTools Protocol)
You sign in to your BookingKoala store admin in your own Chrome, the way you always do.
bookingkoala-mcp connect attaches to that Chrome through the Chrome DevTools Protocol, reads the bookingkoala.com cookies and your time zone, and saves them to ~/.config/bookingkoala-api-mcp/session.json, readable by your user only. It never sees or stores your password.
Every tool call is a request to the admin API your store's own web app calls, on yourstore.bookingkoala.com, sent with curl_cffi, which copies Chrome's TLS fingerprint. The server signs each request the way the app does: a bearer token from your session and a new per-request header. No headless browser runs.
BookingKoala keeps the session for 30 days in the IRON_GATEWAY_CTX cookie of your store's host. When it 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 your BookingKoala store admin. Any Chrome or Chromium works with a debugging port.
macOS, Linux or Windows.
A store admin account. The tools can do what your BookingKoala role may do in the admin panel. A staff role with fewer permissions gets a refusal where the panel would show one.
With uv: uv venv && uv pip install -e ., then uv run bookingkoala-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 bookingkoala-api-mcp (or pip install -U bookingkoala-api-mcp), from source git pull && pip install -e .. We copy every change of the hosted BookingKoala 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 your store admin at https://yourstore.bookingkoala.com/admin.
Run:
bash
bookingkoala-mcp connect
Chrome asks whether to allow the connection. Click Allow.
text
Saved 15 BookingKoala cookies to /Users/you/.config/bookingkoala-api-mcp/session.json
Signed in to BookingKoala as Dana Whitfield (dana@sparkleclean.com), sparkleclean
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 BookingKoala 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 BookingKoala 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.
Option C: paste the cookie by hand
For a server with no Chrome: in Chrome open DevTools on your store admin, Application > Cookies > https://yourstore.bookingkoala.com, copy the value of IRON_GATEWAY_CTX, then:
bash
bookingkoala-mcp connect --token # asks for your store name, then the value (hidden)# or, without a session file:export BOOKINGKOALA_STORE=yourstore BOOKINGKOALA_AUTH_TOKEN=...
A pasted cookie is not refreshed on its own. Paste a new one when BookingKoala signs you out, at the latest after 30 days. Tools that say "today" then use this computer's time zone.
Check the session at any time:
bash
bookingkoala-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. Tools that email customers, notify providers or cancel are marked so your client asks before running them.
Claude Code
bash
claude mcp add bookingkoala -- uvx bookingkoala-api-mcp mcp
# read only:
claude mcp add bookingkoala -- uvx bookingkoala-api-mcp mcp --read-only
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
bookingkoala-mcp serve also serves MCP over streamable HTTP at http://127.0.0.1:8787/mcp, for clients that take a URL:
bash
bookingkoala-mcp serve
claude mcp add --transport http bookingkoala http://127.0.0.1:8787/mcp
Then ask your agent things like:
Go through the unassigned folder for this week. Give each job to the free provider with the fewest bookings that day, and tell me which jobs nobody can take.
Thursday is a storm day. Move every Thursday booking to its next visit and email the customers and providers.
Which invoices are more than 7 days overdue? Send each customer the invoice again.
How much revenue and provider pay did we have from 1 to 15 November?
REST API
bash
bookingkoala-mcp serve # http://127.0.0.1:8787, MCP at /mcp, docs at /docs
Each tool has its own route under /api/v1/bookingkoala, 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/bookingkoala/tools/list_customers -d '{"search": "whitfield"}'
GET /api/v1/bookingkoala/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. Lists return next_cursor; pass it back as cursor for the next 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>:
On a schedule, cron on your own computer works while it is on: 0 7 * * 1-5 cd ~/bookingkoala-api-mcp-server && .venv/bin/python examples/list_bookings.py --status today.
All 17 tools
Ids come from the list tools: booking_id from list_bookings, customer_id from list_customers, provider_id from list_providers, draft_id from list_drafts, invoice_id from list_invoices. bookingkoala-mcp tools prints this list, bookingkoala-mcp tools --json adds the input schemas.
Bookings
Tool
Access
REST route
What it does
list_bookings
read
GET /bookings
Bookings of the store: upcoming, unassigned, completed, charge pending or declined.
get_booking
read
GET /bookings/{booking_id}
One booking with its price breakdown, provider pay, notes and service.
create_booking
write
POST /bookings
Start a new booking as a copy of an existing one: same customer, service and price.
assign_provider
write
POST /bookings/{booking_id}/assign
Assign a provider or team to a booking, or to its whole recurring schedule.
reschedule_booking
write
POST /bookings/{booking_id}/reschedule
Postpone a visit of a recurring booking to the date of a later visit in its schedule.
cancel_booking
write
POST /bookings/{booking_id}/cancel
Cancel one booking or its whole recurring schedule, without a cancellation fee.
Drafts and quotes
Tool
Access
REST route
What it does
list_drafts
read
GET /drafts
Draft bookings and quotes saved in the store, not yet booked.
send_quote
write
POST /quotes/{draft_id}/send
Email a saved quote to the customer with a link to book it.
Customers
Tool
Access
REST route
What it does
list_customers
read
GET /customers
Customers of the store, with email and phone; search by name, email or phone.
get_customer
read
GET /customers/{customer_id}
One customer: contact details, addresses, booking counts and bookings not charged yet.
create_customer
write
POST /customers
New customer in the store. BookingKoala emails them an invitation to set a password.
Providers and teams
Tool
Access
REST route
What it does
list_providers
read
GET /providers
Providers (cleaners, technicians) and teams of the store, in priority order.
get_provider
read
GET /providers/{provider_id}
One provider or team: contact, category, team members, reviews and payment logs.
Charges, invoices and reports
Tool
Access
REST route
What it does
list_charges
read
GET /charges
Charged bookings with their payments and refunds, as the Charges page lists them.
list_invoices
read
GET /invoices
Invoices of the store or of one customer, with payment status, total and amount due.
resend_invoice
write
POST /invoices/{invoice_id}/resend
Send an invoice to its customer again by email, text or both.
dashboard
read
GET /dashboard
Store totals for a date range: revenue, provider pay, bookings, ratings, referrals.
Never built, on purpose: your BookingKoala sign-in, password and profile, your own BookingKoala plan and billing, and anything else that moves money. Every request passes a guard that refuses those BookingKoala paths.
Not in this version
Tool
Why
refund_charge
It sends money back to a customer's card. The hosted version has it, with your approval for each call. Here, refund in the panel under Charges.
Configuration
Variable
Default
What it does
BOOKINGKOALA_MCP_HOME
~/.config/bookingkoala-api-mcp
Folder of session.json.
BOOKINGKOALA_AUTH_TOKEN
Value of the IRON_GATEWAY_CTX cookie, instead of bookingkoala-mcp connect. Needs BOOKINGKOALA_STORE.
BOOKINGKOALA_STORE
Your store name, yourstore for yourstore.bookingkoala.com.
BOOKINGKOALA_PROXY
Proxy for every request to BookingKoala, e.g. http://user:pass@host:port.
BOOKINGKOALA_MCP_READ_ONLY
1 hides and refuses every tool that changes BookingKoala (same as --read-only).
BOOKINGKOALA_MCP_TOKEN
Bearer token required by serve; needed to listen beyond 127.0.0.1.
BOOKINGKOALA_MCP_HOST, BOOKINGKOALA_MCP_PORT
127.0.0.1, 8787
Address of serve.
Security and your BookingKoala account
Your password never reaches this code. Only cookies are read, and only those of bookingkoala.com.
The session file is yours.session.json is created with mode 0600. Anyone who has it can act as you in your store admin, so keep it out of git and shared folders.
Local by default.serve binds to 127.0.0.1 and refuses another address without BOOKINGKOALA_MCP_TOKEN.
bookingkoala.com only. Requests and redirects outside bookingkoala.com are refused.
Read-only mode.--read-only or BOOKINGKOALA_MCP_READ_ONLY=1 exposes the 10 read tools only.
Actions reach real people. Assigning tells the provider. Quotes and invoices go to customers, a new customer gets an invitation email, and notify on a cancel or reschedule emails both sides. MCP clients ask before running them. A script does not, so try it on a test booking first.
You answer for what runs in your store. Keep to your normal use of BookingKoala.
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 BookingKoala signed you out. Sign in to your store admin in Chrome and run bookingkoala-mcp connect.
403
app_permission_denied
Your BookingKoala role cannot do this.
403
scope_denied
The server runs read-only, or the request would touch your sign-in or billing.
403
target_blocked
BookingKoala refused the request or showed a bot check. Open your store admin in Chrome once, then retry.
409
captcha_required
BookingKoala asks for a CAPTCHA. Solve it in Chrome.
422
invalid_input
An argument is missing or wrong; the message names it.
429
rate_limited
BookingKoala is limiting the account. Wait a few minutes.
502
target_error
BookingKoala answered with an error, or changed its app. The message carries BookingKoala's own reason. git pull for the latest tools, or open an issue.
your own Cloud Browser in the EU, profile encrypted with AES-256-GCM
When BookingKoala changes its app
git pull once we have fixed it
fixed for you, every tool tested daily
Approvals
your MCP client asks per call
assignments, quotes, invoices and refunds 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 BookingKoala MCP server for Claude, ChatGPT or Cursor?
Yes, this one runs on your machine: bookingkoala-mcp mcp for Claude Code, Claude Desktop, Cursor and Codex. ChatGPT and Claude.ai connectors need a public HTTPS URL, which the hosted BookingKoala MCP server gives you.
Do I need Zapier or a BookingKoala API key?
No. The tools use your signed-in admin session, the same one your browser uses.
Can I export BookingKoala bookings or customers to CSV?
Yes: python examples/list_bookings.py --status all --out bookings.csv and python examples/export_customers.py --out customers.csv, across all pages.
Can it assign providers automatically?examples/assign_unassigned.py gives each unassigned job to the provider with the fewest jobs that day, after it shows you the plan. BookingKoala still refuses a provider who is not available at that time, and the script lists those jobs.
Why does it need my Chrome?
To read your BookingKoala session without your password. Chrome is used once per sign-in, not for each call.
What happens when BookingKoala 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 bookingkoala-mcp connect again.
Can it run on a VPS or in Docker?
Technically yes, with BOOKINGKOALA_STORE and BOOKINGKOALA_AUTH_TOKEN. BookingKoala then sees your session from a datacenter IP. For an always-on setup the hosted version keeps your session in your own Cloud Browser on a fixed IP.
Can I use it for my cleaning business?
For your own cleaning business, 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). BookingKoala is a trademark of its owner. This project is unofficial and not affiliated with, endorsed or sponsored by BookingKoala.