BookingKoala by Cotlet

dev.cotletPublished by cotlet.devOfficial publisherv1.0.2Updated Oct 31, 2026

Bookings, providers and customers in your BookingKoala store.

The publisher's own server: Cotlet

VerifiedStreamable HTTPWeb executableProductivity & WorkflowFinanceBusiness & Commerce

Overview

AI-generated overview

Unofficial BookingKoala tools that let an assistant read and change bookings, customers, providers, quotes, invoices and store totals in your own store.

What you can do
  • List, read and create bookings, assign providers or teams, postpone recurring visits and cancel bookings
  • List drafts and quotes, and email a saved quote to the customer with a booking link
  • Search and read customers, add a new customer, and read providers and teams with their reviews and payment logs
  • List charges and invoices, resend an invoice by email or text, and pull store dashboard totals for a date range
  • Page through lists with a cursor and chain ids from the list tools into the detail and write tools
When to use it
Useful for cleaning and home service businesses that run on BookingKoala and want an assistant to triage unassigned jobs, follow up on overdue invoices, reschedule a closed day or report revenue and provider pay. Also handy for scripting exports of bookings and customers to CSV.
Requirements
Either the hosted Cotlet endpoint with an OAuth sign-in and an Authorization bearer API key from cotlet.dev, or the local Python package (Python 3.11+) run with uvx. The local version needs Google Chrome signed in to your store admin, or a pasted session cookie via BOOKINGKOALA_AUTH_TOKEN and BOOKINGKOALA_STORE. A store admin account is required; tools are limited by your BookingKoala role.
Before you install
Write tools reach real people: assigning notifies the provider, quotes and invoices are emailed or texted to customers, a new customer gets an invitation email, and cancelling or rescheduling can notify both sides. The local session file lets anyone who has it act as you in the admin, so keep it out of git and shared folders. The hosted version is paid after a 7-day trial and uses credits per call. Refunds are deliberately not included.

Installation

In SourceWeft

  1. Open BookingKoala by Cotlet in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/dev.cotlet%2Fbookingkoala/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "bookingkoala-by-cotlet": {
      "type": "http",
      "url": "https://cotlet.dev/mcp/v1/bookingkoala/connect"
    }
  }
}

README

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?

Two ways to get it

Ready to use, at CotletRun it yourself, this repo
Forcleaning and home service business ownersdevelopers
Setupsign in to BookingKoala once, about 5 minutes, nothing to installPython and a terminal
Works inChatGPT and Claude apps, on your phone too, Cursor, Codex, OpenClaw, any MCP client, n8n, Make, Zapier, REST APIClaude Code, Claude Desktop, Cursor, Codex on your computer
Runs24/7, your computer can be offwhile your computer is on
Price7 days free, no cardfree

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.

Start free at cotlet.dev →

Run it yourself

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).

[BookingKoala MCP server] [Python 3.11+] [License: Elastic 2.0] [MCP Badge]

bash
uv tool install bookingkoala-api-mcp                  # or: pip install bookingkoala-api-mcpbookingkoala-mcp connect                           # reads your BookingKoala session from Chromebookingkoala-mcp call list_bookings status=upcomingclaude mcp add bookingkoala -- uvx bookingkoala-api-mcp mcp

Contents

Questions from BookingKoala users

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 [email protected] 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)
  1. You sign in to your BookingKoala store admin in your own Chrome, the way you always do.
  2. 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.
  3. 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.

Install

From PyPI:

bash
uv tool install bookingkoala-api-mcp       # or: pipx install bookingkoala-api-mcp, or: pip install bookingkoala-api-mcpbookingkoala-mcp --version

MCP clients can also run it with no install: uvx bookingkoala-api-mcp mcp.

From source:

bash
git clone https://github.com/cotletdev/bookingkoala-api-mcp-server.gitcd bookingkoala-api-mcp-serverpython3 -m venv .venv. .venv/bin/activate              # Windows: .venv\Scripts\activatepip install -e .bookingkoala-mcp --version

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)

  1. 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.

  2. Make sure you are signed in to your store admin at https://yourstore.bookingkoala.com/admin.

  3. Run:

    bash
    bookingkoala-mcp connect

  4. Chrome asks whether to allow the connection. Click Allow.

text
Saved 15 BookingKoala cookies to /Users/you/.config/bookingkoala-api-mcp/session.jsonSigned in to BookingKoala as Dana Whitfield ([email protected]), 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:

bash
# macOS"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-bookingkoala"# Linuxgoogle-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-bookingkoala"# Windows"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.chrome-bookingkoala"
bookingkoala-mcp connect --cdp http://127.0.0.1:9222

--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):

json
{  "mcpServers": {    "bookingkoala": {      "command": "uvx",      "args": ["bookingkoala-api-mcp", "mcp"]    }  }}

Cursor

~/.cursor/mcp.json, the same block as Claude Desktop. A ready copy is in mcp.json.

Codex

~/.codex/config.toml:

toml
[mcp_servers.bookingkoala]command = "uvx"args = ["bookingkoala-api-mcp", "mcp"]

Over HTTP

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 serveclaude 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.

bash
curl 'http://127.0.0.1:8787/api/v1/bookingkoala/bookings?status=unassigned&start_date=2026-11-16&end_date=2026-11-20'curl 'http://127.0.0.1:8787/api/v1/bookingkoala/bookings/212'curl -X POST http://127.0.0.1:8787/api/v1/bookingkoala/bookings/212/assign \  -H 'Content-Type: application/json' \  -d '{"provider_id": 3}'

Any tool by name, body as its arguments:

bash
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>:

bash
BOOKINGKOALA_MCP_TOKEN=$(openssl rand -hex 24) bookingkoala-mcp serve --host 0.0.0.0

Python and the example scripts

Straight from Python, no server needed:

python
from bookingkoala_api_mcp import callfrom bookingkoala_api_mcp.scripting import paginate, write_rows
totals = call("dashboard", start_date="2026-11-01", end_date="2026-11-15")bookings = list(paginate("list_bookings", {"status": "completed", "start_date": "2026-11-01"}, "bookings"))write_rows(bookings, "completed.csv")call("assign_provider", booking_id=212, provider_id=3)

Or one tool from the shell: bookingkoala-mcp call list_customers search=whitfield, or with a JSON object.

Ready scripts in examples/. Each prints JSON, takes --out file.csv or --out file.json where it makes sense, and --help:

ScriptWhat it does
list_bookings.pyBookings by status and date range: date, arrival time, customer, address, providers, total.
export_customers.pyCustomers to CSV or JSON: name, email, phone, tags, note.
store_dashboard.pyStore totals for a date range: revenue, provider pay, bookings, ratings, referrals.
assign_unassigned.pyGives each unassigned job to the provider with the fewest jobs that day. Shows the plan unless you pass --assign.
assign_provider.pyAssigns one booking, or its whole recurring schedule, to a provider or team.
reschedule_day.pyMoves a closed day's recurring visits to their next visit date. Plan first, --move to do it.
cancel_booking.pyCancels one booking or the rest of its schedule, with no fee, after you confirm.
rebook_customer.pyCopies a repeat customer's last visit into a draft. --send-quote emails their saved quote.
send_quote.pyLists saved drafts and quotes, or emails one quote with a link to book it.
add_customer.pyAdds a customer after checking the email is not in the store yet.
provider_pay_report.pyProvider pay totals for a pay period, then each provider's payment logs.
overdue_invoices.pyUnpaid invoices past due. --remind sends each one to its customer again.
bash
python examples/assign_unassigned.py --from 2026-11-16 --to 2026-11-20python examples/overdue_invoices.py --days 7 --out overdue.csv

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

ToolAccessREST routeWhat it does
list_bookingsreadGET /bookingsBookings of the store: upcoming, unassigned, completed, charge pending or declined.
get_bookingreadGET /bookings/{booking_id}One booking with its price breakdown, provider pay, notes and service.
create_bookingwritePOST /bookingsStart a new booking as a copy of an existing one: same customer, service and price.
assign_providerwritePOST /bookings/{booking_id}/assignAssign a provider or team to a booking, or to its whole recurring schedule.
reschedule_bookingwritePOST /bookings/{booking_id}/reschedulePostpone a visit of a recurring booking to the date of a later visit in its schedule.
cancel_bookingwritePOST /bookings/{booking_id}/cancelCancel one booking or its whole recurring schedule, without a cancellation fee.

Drafts and quotes

ToolAccessREST routeWhat it does
list_draftsreadGET /draftsDraft bookings and quotes saved in the store, not yet booked.
send_quotewritePOST /quotes/{draft_id}/sendEmail a saved quote to the customer with a link to book it.

Customers

ToolAccessREST routeWhat it does
list_customersreadGET /customersCustomers of the store, with email and phone; search by name, email or phone.
get_customerreadGET /customers/{customer_id}One customer: contact details, addresses, booking counts and bookings not charged yet.
create_customerwritePOST /customersNew customer in the store. BookingKoala emails them an invitation to set a password.

Providers and teams

ToolAccessREST routeWhat it does
list_providersreadGET /providersProviders (cleaners, technicians) and teams of the store, in priority order.
get_providerreadGET /providers/{provider_id}One provider or team: contact, category, team members, reviews and payment logs.

Charges, invoices and reports

ToolAccessREST routeWhat it does
list_chargesreadGET /chargesCharged bookings with their payments and refunds, as the Charges page lists them.
list_invoicesreadGET /invoicesInvoices of the store or of one customer, with payment status, total and amount due.
resend_invoicewritePOST /invoices/{invoice_id}/resendSend an invoice to its customer again by email, text or both.
dashboardreadGET /dashboardStore 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

ToolWhy
refund_chargeIt 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

VariableDefaultWhat it does
BOOKINGKOALA_MCP_HOME~/.config/bookingkoala-api-mcpFolder of session.json.
BOOKINGKOALA_AUTH_TOKENValue of the IRON_GATEWAY_CTX cookie, instead of bookingkoala-mcp connect. Needs BOOKINGKOALA_STORE.
BOOKINGKOALA_STOREYour store name, yourstore for yourstore.bookingkoala.com.
BOOKINGKOALA_PROXYProxy for every request to BookingKoala, e.g. http://user:pass@host:port.
BOOKINGKOALA_MCP_READ_ONLY1 hides and refuses every tool that changes BookingKoala (same as --read-only).
BOOKINGKOALA_MCP_TOKENBearer token required by serve; needed to listen beyond 127.0.0.1.
BOOKINGKOALA_MCP_HOST, BOOKINGKOALA_MCP_PORT127.0.0.1, 8787Address 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.

StatusCodeWhat to do
401auth_required, auth_expiredNo session, or BookingKoala signed you out. Sign in to your store admin in Chrome and run bookingkoala-mcp connect.
403app_permission_deniedYour BookingKoala role cannot do this.
403scope_deniedThe server runs read-only, or the request would touch your sign-in or billing.
403target_blockedBookingKoala refused the request or showed a bot check. Open your store admin in Chrome once, then retry.
409captcha_requiredBookingKoala asks for a CAPTCHA. Solve it in Chrome.
422invalid_inputAn argument is missing or wrong; the message names it.
429rate_limitedBookingKoala is limiting the account. Wait a few minutes.
502target_errorBookingKoala 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.

Self-hosted or hosted

This repoCotlet, hosted
Tools1718, with refund_charge
Runson your computer, while it is onin the cloud, 24/7
BookingKoala sessionyour Chrome, cookies in a local fileyour own Cloud Browser in the EU, profile encrypted with AES-256-GCM
When BookingKoala changes its appgit pull once we have fixed itfixed for you, every tool tested daily
Approvalsyour MCP client asks per callassignments, quotes, invoices and refunds wait for your OK, switchable per tool
Works withMCP clients on your machine, local scriptsClaude.ai and ChatGPT connectors, n8n, Make, Zapier, any HTTP client
Who may use ityou and your own businessyou, teams, businesses, agencies
Pricefreefree 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 [email protected].

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.

License

Elastic License 2.0. In short:

  • 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.

[Cotlet]

Maintained by Cotlet (@cotletdev). BookingKoala is a trademark of its owner. This project is unofficial and not affiliated with, endorsed or sponsored by BookingKoala.

Source: README.md at commit 810c5b9

Tools

17

assign_provider

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.

Parametersbooking_idrequiredprovider_idrequiredwhole_scheduleeven_if_unavailable

cancel_booking

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.

Parametersnotifyreasonbooking_idrequiredwhole_schedule

create_booking

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.

Parametersfrom_booking_idrequired

create_customer

Create customer

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.

Parametersaptcityemailrequiredphonestategenderaddresscountryzipcodelast_namerequiredfirst_namerequiredsms_notifications

dashboard

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.

Parametersend_datestart_date

get_booking

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.

Parametersbooking_idrequired

get_customer

Get customer

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.

Parameterscustomer_idrequired

get_provider

Get provider

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.

Parametersprovider_idrequiredpayment_logs_limit

list_bookings

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.

Parameterslimitcursorsearchstatusend_datestart_datecustomer_idprovider_id

list_charges

List charges

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.

Parameterslimitcursorsearchend_datestart_date

list_customers

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.

Parameterslimitcursorsearchstatus

list_drafts

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.

Parameterslimitcursorsearch

list_invoices

List invoices

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.

Parameterslimitcursorsearchend_datepay_statusstart_datecustomer_id

list_providers

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.

Parameterstypelimitcursorsearchstatus

reschedule_booking

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.

Parametersdaterequirednotifybooking_idrequired

resend_invoice

Resend an 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.

Parameterssmsemailattach_pdfinvoice_idrequired

send_quote

Send a 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.

Parametersemailmessagesubjectdraft_idrequiredexpires_on

Version history

2
  1. v1.0.2LatestOct 24, 2026
  2. v1.0.0Oct 23, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.

Other Cotlet integrations

Cotlet

dev.cotletOfficial publisher

Cotlet is a hosted MCP server that lets an AI assistant act in apps with no usable API through a cloud Chrome browser you signed in to yourself.

Streamable HTTPWeb executableAuth
Productivity & WorkflowCredential requiredOct 24, 2026

Tradify by Cotlet

dev.cotletOfficial publisher

Connects an assistant to a Tradify trade-business account to list and create jobs, quotes, invoices, customers and Scheduler appointments.

Streamable HTTPWeb executableAuth
Productivity & Workflow15 toolsNov 1, 2026

Substack by Cotlet

dev.cotletOfficial publisher

Lets an assistant work inside your own Substack account: drafts, publishing, Notes, comments, subscribers, messages and stats.

Streamable HTTPWeb executableAuth
Communication & Collaboration50 toolsNov 7, 2026

Skool by Cotlet

dev.cotletOfficial publisher

Lets an assistant read and manage a Skool community — posts, members, membership requests, Classroom, Calendar, chat and stats — in the user's own account.

Streamable HTTPWeb executableAuth
Productivity & Workflow69 toolsNov 7, 2026

Pirate Ship by Cotlet

dev.cotletOfficial publisher

Unofficial Pirate Ship server for quoting USPS/UPS rates, drafting labels and batches, and reading shipping reports from your own account.

Streamable HTTPWeb executableAuth
Productivity & Workflow51 toolsNov 1, 2026