BookingKoala by Cotlet MCP server

BookingKoala API and MCP server, self-hosted

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

It is for technical people who want to run it themselves, for noncommercial use only (license). If you want it running 24/7 on a server, kept working when BookingKoala changes its app, for a team or a business, use the hosted version at cotlet.dev.

git clone https://github.com/cotletdev/bookingkoala-api-mcp-server.git && cd bookingkoala-api-mcp-server
python3 -m venv .venv && . .venv/bin/activate && pip install -e .
bookingkoala-mcp connect                           # reads your BookingKoala session from Chrome
bookingkoala-mcp call list_bookings status=upcoming
claude mcp add bookingkoala -- "$PWD/.venv/bin/bookingkoala-mcp" mcp

Contents

• How it works
• Requirements
• Install
• Connect your Chrome
• MCP server
• REST API
• Python and the example scripts
• All 17 tools
• Configuration
• Security and your BookingKoala account
• Errors
• Self-hosted or hosted

How it works

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 IRONGATEWAYCTX 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

Shortened. The full README is on GitHub.