BookingKoala by Cotlet

BookingKoala API 和 MCP 服务，可自托管

一个 BookingKoala API 和一个 BookingKoala MCP 服务，使用 Python 在你自己的电脑上运行，基于你自己的 Google Chrome 会话。这里提供我们在 Cotlet 生产环境中使用的 18 个 BookingKoala 工具中的 17 个：预订、草稿和报价、客户、服务提供者和团队、收费、发票以及商店仪表板。

BookingKoala 没有公开 API，也没有官方 MCP 服务。它的 API 密钥只能连接 Zapier 和 Make，用于响应新事件，并且只能回写一项内容：潜在客户。这个仓库同时提供这两种接口：

• 面向 Claude Code、Claude Desktop、Cursor、Codex 和任何 MCP 客户端的 MCP 服务，通过 stdio 或 HTTP 通信。设置
• 位于 http://127.0.0.1:8787/api/v1/bookingkoala 的 REST API，OpenAPI 文档位于 /docs。设置
• Python：call("list_bookings", status="unassigned")，以及 examples/ 中 12 个可直接使用的脚本。

该项目面向希望自行运行它的技术人员，仅限非商业用途（许可证）。如果你希望它 24/7 在服务上运行、在 BookingKoala 更改其应用时仍能正常工作，或供团队或企业使用，请使用 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

目录

• 工作原理
• 要求
• 安装
• 连接你的 Chrome
• MCP 服务
• REST API
• Python 和示例脚本
• 全部 17 个工具
• 配置
• 安全性和你的 BookingKoala 账户
• 错误
• 自托管或托管服务
• 常见问题
• 许可证

工作原理

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. 像往常一样，在自己的 Chrome 中登录 BookingKoala 商店管理后台。
2. bookingkoala-mcp connect 通过 Chrome DevTools Protocol 连接 Chrome，读取 bookingkoala.com Cookie 和你的时区，并将其保存到 ~/.config/bookingkoala-api-mcp/session.json，只有你的用户可以读取。它绝不会查看或存储你的密码。
3. 每次工具调用都会向商店自己的 Web 应用所调用的管理 API 发送请求，目标地址为 yourstore.bookingkoala.com。请求通过 curl_cffi 发送，该库会复制 Chrome 的 TLS 指纹。服务会按照应用的方式为每个请求签名：使用会话中的 bearer token，并添加一个新的请求级请求头。不会运行无头浏览器。

BookingKoala 会在商店主机的 IRON_GATEWAY_CTX Cookie 中将会话保留 30 天。你退出登录后，如果 Chrome 已打开并启用了远程调试，服务会再次从 Chrome 读取会话。

要求

• Python 3.11 或更高版本。
• Google Chrome 144 或更高版本，并已登录 BookingKoala 商店管理后台。任何 Chrome 或 Chromium 都可以配合调试端口使用。
• macOS、Linux 或 Windows。
• 商店管理员账户。这些工具可以执行你的 BookingKoala 角色在管理面板中有权执行的操作。权限较少的员工角色会收到拒绝响应，而管理面板也会拒绝相同操作。

安装

git clone https://github.com/cotletdev/bookingkoala-api-mcp-server.git
cd bookingkoala-api-mcp-server
python3 -m venv .venv
. .venv/bin/activate              # Windows: .venv\Scripts\activate
pip install -e .
bookingkoala-mcp --version

使用 uv：运行 uv venv && uv pip install -e .，然后运行 uv run bookingkoala-mcp ...。

要使用 AI Agent（Claude Code、Codex、Cursor）设置项目？在此文件夹中打开项目，并让它设置仓库：AGENTS.md 会告诉它每个步骤，而它只会要求你在 Chrome 中执行相关步骤。

更新：运行 git pull && pip install -e .。我们会将托管版 BookingKoala 工具的每项更改都同步到此仓库。

连接你的 Chrome

选项 A：日常使用的 Chrome（推荐）

1. 在 Chrome 中打开 chrome://inspect/#remote-debugging，并开启 remote debugging。这样一来，Chrome 会接受此电脑上程序发起的 DevTools 连接，并在每次连接前询问你。

2. 确保你已登录商家后台：https://yourstore.bookingkoala.com/admin。

3. 运行：

   bookingkoala-mcp connect
   

4. Chrome 会询问是否允许连接。点击 Allow。

Saved 15 BookingKoala cookies to /Users/you/.config/bookingkoala-api-mcp/session.json
Signed in to BookingKoala as Dana Whitfield ([email protected]), sparkleclean

之后你可以再次关闭远程调试。如果你希望 BookingKoala 将你登出后，服务自动接入新会话，请保持远程调试开启。

connect 会在 Chrome 默认配置文件夹中查找 DevToolsActivePort 文件。对于 Chrome Beta、Canary 或自定义配置文件夹，请传入 --profile-dir "<folder>"。

选项 B：使用带调试端口的 Chrome

Chrome 不会在默认配置文件上开放调试端口，因此请启动一个单独的 Chrome 实例，在其中登录 BookingKoala 一次，然后连接到该实例：

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-bookingkoala"
# Linux
google-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 也接受 ws:// DevTools URL，例如通过 SSH 隧道连接到另一台机器上的 Chrome。

选项 C：手动粘贴 Cookie

如果服务器上没有 Chrome：在 Chrome 中打开商家后台的 DevTools，依次选择 **Application > Cookies > https://yourstore.bookingkoala.com**，复制 IRON_GATEWAY_CTX 的值，然后：

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

手动粘贴的 Cookie 不会自动刷新。BookingKoala 将你登出时，或最迟 30 天后，请粘贴新的 Cookie。此时，标注“今天”的工具会使用这台电脑的时区。

随时检查会话：

bookingkoala-mcp status

MCP 服务

MCP 服务会列出每个工具的输入架构、面向 Agent 编写的说明和提示。读取工具会标记为只读。会向客户发送电子邮件、通知服务提供商或取消操作的工具也会标记出来，以便客户端在运行前征求你的确认。

Claude Code

claude mcp add bookingkoala -- /path/to/bookingkoala-api-mcp-server/.venv/bin/bookingkoala-mcp mcp
# read only:
claude mcp add bookingkoala -- /path/to/bookingkoala-api-mcp-server/.venv/bin/bookingkoala-mcp mcp --read-only

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "bookingkoala": {
      "command": "/path/to/bookingkoala-api-mcp-server/.venv/bin/bookingkoala-mcp",
      "args": ["mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json，使用与 Claude Desktop 相同的代码块。可直接使用的副本位于 mcp.json。

Codex

~/.codex/config.toml：

[mcp_servers.bookingkoala]
command = "/path/to/bookingkoala-api-mcp-server/.venv/bin/bookingkoala-mcp"
args = ["mcp"]

通过 HTTP 连接

bookingkoala-mcp serve 还会通过可流式传输的 HTTP，在 http://127.0.0.1:8787/mcp 提供 MCP 服务，供需要 URL 的客户端使用：

bookingkoala-mcp serve
claude mcp add --transport http bookingkoala http://127.0.0.1:8787/mcp

然后可以向 Agent 提出以下请求：

查看本周的未分配文件夹。将每项工作分配给当天预订数量最少的空闲服务提供商，并告诉我哪些工作无人能接。

星期四有暴风雨。将所有星期四的预订改到下一次上门，并给客户和服务提供商发送电子邮件。

哪些发票逾期超过 7 天？重新向每位客户发送发票。

11 月 1 日至 15 日，我们的收入和服务提供商报酬分别是多少？

REST API

bookingkoala-mcp serve             # http://127.0.0.1:8787, MCP at /mcp, docs at /docs

每个工具在 /api/v1/bookingkoala 下都有自己的路由，与 cotlet.dev 上托管的 API 使用相同路径，因此针对其中一个 API 编写的代码也适用于另一个。路径部分和查询字符串会作为参数，JSON 请求体则可提供其余参数。

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}'

按名称调用任意工具，并将请求体作为参数：

curl -X POST http://127.0.0.1:8787/api/v1/bookingkoala/tools/list_customers -d '{"search": "whitfield"}'

• GET /api/v1/bookingkoala/tools：列出每个工具的路由、输入架构和示例回答。
• GET /docs：交互式 OpenAPI 文档；GET /openapi.json：架构，可用于 n8n、Postman 或生成的客户端。
• 回答均为 JSON。列表会返回 next_cursor；将其作为 cursor 传回即可获取下一页。

服务仅监听 127.0.0.1。若要从你的其他设备访问，请设置令牌；之后每个请求都需要携带 Authorization: Bearer <token>：

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

Python 和示例脚本

直接使用 Python，无需服务端：

from bookingkoala_api_mcp import call
from 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)

也可以从命令行调用一个工具：bookingkoala-mcp call list_customers search=whitfield，或使用 JSON 对象。

examples/ 中提供了现成脚本。每个脚本都会输出 JSON，在适用时支持 --out file.csv 或 --out file.json，并提供 --help：

脚本	功能
list_bookings.py	按状态和日期范围列出预约：日期、到达时间、客户、地址、服务人员、总额。
export_customers.py	将客户信息导出为 CSV 或 JSON：姓名、邮箱、电话、标签、备注。
store_dashboard.py	汇总日期范围内的门店数据：收入、服务人员报酬、预约、评分、推荐。
assign_unassigned.py	将每个未分配的工作分配给当天工作量最少的服务人员。除非传入 --assign，否则只显示计划。
assign_provider.py	将一项预约或其整个周期性安排分配给服务人员或团队。
reschedule_day.py	将某个关闭日的周期性上门服务移至下一次上门日期。先查看计划，再传入 --move 执行。
cancel_booking.py	确认后取消一项预约或其剩余安排，不收取费用。
rebook_customer.py	将回头客上次上门服务复制为草稿。--send-quote 会通过邮件发送其已保存的报价。
send_quote.py	列出已保存的草稿和报价，或通过邮件发送一份报价并附上预约链接。
add_customer.py	添加客户前，先检查门店中是否已有该邮箱。
provider_pay_report.py	汇总一个工资周期的服务人员报酬，然后列出每位服务人员的付款记录。
overdue_invoices.py	列出已逾期的未付款发票。--remind 会再次向每位客户发送发票。

python examples/assign_unassigned.py --from 2026-11-16 --to 2026-11-20
python examples/overdue_invoices.py --days 7 --out overdue.csv

按计划运行时，只要自己的电脑处于开机状态，就可以使用 cron：0 7 * * 1-5 cd ~/bookingkoala-api-mcp-server && .venv/bin/python examples/list_bookings.py --status today。

全部 17 个工具

ID 来自工具列表：list_bookings 中的 booking_id、list_customers 中的 customer_id、list_providers 中的 provider_id、list_drafts 中的 draft_id、list_invoices 中的 invoice_id。运行 bookingkoala-mcp tools 可打印此列表，运行 bookingkoala-mcp tools --json 可附带输入架构。

预约

工具	访问权限	REST 路由	功能
list_bookings	读取	GET /bookings	列出门店的预约：即将开始、未分配、已完成、待扣款或扣款被拒。
get_booking	读取	GET /bookings/{booking_id}	获取单项预约及其价格明细、服务人员报酬、备注和服务。
create_booking	写入	POST /bookings	以现有预约为模板创建新预约：客户、服务和价格均相同。
assign_provider	写入	POST /bookings/{booking_id}/assign	将服务人员或团队分配给一项预约或其整个周期性安排。
reschedule_booking	写入	POST /bookings/{booking_id}/reschedule	将周期性预约的一次上门服务推迟到其安排中后续一次上门服务的日期。
cancel_booking	写入	POST /bookings/{booking_id}/cancel	取消一项预约或其整个周期性安排，不收取取消费。

草稿和报价

工具	访问权限	REST 路由	功能
list_drafts	读取	GET /drafts	列出门店中已保存但尚未预约的预约草稿和报价。
send_quote	写入	POST /quotes/{draft_id}/send	通过邮件向客户发送已保存的报价，并附上预约链接。

客户

工具	访问权限	REST 路由	功能
list_customers	读取	GET /customers	店铺的客户及其邮箱和电话；可按姓名、邮箱或电话搜索。
get_customer	读取	GET /customers/{customer_id}	单个客户的信息：联系方式、地址、预约数量以及尚未收费的预约。
create_customer	写入	POST /customers	在店铺中创建新客户。BookingKoala 会向其发送设置密码的邀请邮件。

服务提供者和团队

工具	访问权限	REST 路由	功能
list_providers	读取	GET /providers	按优先级列出店铺的服务提供者（清洁人员、技术人员）和团队。
get_provider	读取	GET /providers/{provider_id}	单个服务提供者或团队的信息：联系方式、类别、团队成员、评价和付款记录。

收费、发票和报告

工具	访问权限	REST 路由	功能
list_charges	读取	GET /charges	已收费的预约及其付款和退款信息，与 Charges 页面显示的内容一致。
list_invoices	读取	GET /invoices	店铺或某位客户的发票，包括付款状态、总额和应付金额。
resend_invoice	写入	POST /invoices/{invoice_id}/resend	通过邮件、短信或两者再次向客户发送发票。
dashboard	读取	GET /dashboard	指定日期范围内的店铺总数据：收入、服务提供者报酬、预约、评分和推荐。

以下功能特意未实现：BookingKoala 登录、密码和个人资料，你自己的 BookingKoala 套餐与账单，以及任何其他资金流转操作。每个请求都会经过一道防护检查，拒绝访问这些 BookingKoala 路径。

此版本未提供

工具	原因
refund_charge	此操作会将款项退回客户的银行卡。托管版本提供此功能，每次调用都需要你批准。在此版本中，请在 Charges 页面中退款。

配置

变量	默认值	功能
BOOKINGKOALA_MCP_HOME	~/.config/bookingkoala-api-mcp	存放 session.json 的文件夹。
BOOKINGKOALA_AUTH_TOKEN		IRON_GATEWAY_CTX Cookie 的值，用于替代 bookingkoala-mcp connect。需要设置 BOOKINGKOALA_STORE。
BOOKINGKOALA_STORE		你的店铺名称；对于 yourstore.bookingkoala.com，此值为 yourstore。
BOOKINGKOALA_PROXY		用于所有发往 BookingKoala 请求的代理，例如 http://user:pass@host:port。
BOOKINGKOALA_MCP_READ_ONLY		1 会隐藏并拒绝所有会更改 BookingKoala 的工具（与 --read-only 相同）。
BOOKINGKOALA_MCP_TOKEN		serve 所需的 Bearer token；要在 127.0.0.1 以外的地址监听时必须设置。
BOOKINGKOALA_MCP_HOST、BOOKINGKOALA_MCP_PORT	127.0.0.1、8787	serve 的地址。

安全与 BookingKoala 账户

• 你的密码不会传入此代码。 这里只会读取 Cookie，且仅限 bookingkoala.com 的 Cookie。
• 会话文件由你保管。 session.json 创建时的权限为 0600。任何拥有此文件的人都能以你的身份操作店铺管理后台，因此请勿将其放入 git 或共享文件夹。
• 默认仅在本地运行。 serve 会绑定到 127.0.0.1；如果未设置 BOOKINGKOALA_MCP_TOKEN，则会拒绝使用其他地址。
• 仅限 bookingkoala.com。 系统会拒绝发往 bookingkoala.com 以外的请求及重定向。
• 只读模式。 --read-only 或 BOOKINGKOALA_MCP_READ_ONLY=1 仅会公开 10 个读取工具。
• 操作会影响真实用户。 分配任务会通知服务提供者。报价和发票会发送给客户，新客户会收到邀请邮件；取消或改期时，notify 会给双方发送邮件。MCP 客户端会在执行前征求确认。脚本不会，因此请先在测试预约上试用。
• 你需要对店铺中的操作负责。 请按照你平时使用 BookingKoala 的方式操作。

错误

REST API 会返回 {"error": "<code>", "message": "..."}。MCP 服务会将相同的代码和消息作为工具错误返回。

状态	代码	处理方法
401	auth_required, auth_expired	没有会话，或 BookingKoala 已将你登出。请在 Chrome 中登录你的店铺管理后台，然后运行 bookingkoala-mcp connect。
403	app_permission_denied	你的 BookingKoala 角色无权执行此操作。
403	scope_denied	服务以只读模式运行，或请求会影响你的登录或账单。
403	target_blocked	BookingKoala 拒绝了请求或显示了机器人验证。请在 Chrome 中打开一次店铺管理后台，然后重试。
409	captcha_required	BookingKoala 要求完成 CAPTCHA。请在 Chrome 中通过验证。
422	invalid_input	参数缺失或错误；消息会指出具体参数。
429	rate_limited	BookingKoala 正在限制此账户。请等待几分钟。
502	target_error	BookingKoala 返回了错误，或更改了其应用。消息中包含 BookingKoala 自身给出的原因。运行 git pull 获取最新工具，或提交问题。

可自托管或托管版本

	此仓库	Cotlet，托管版本
工具	17	18 个，包含 refund_charge
运行位置	你的电脑上，电脑开机时运行	云端，全天候运行
BookingKoala 会话	你的 Chrome，会话 Cookie 保存在本地文件中	你自己的欧盟云浏览器，配置文件使用 AES-256-GCM 加密
BookingKoala 更改应用时	我们修复后运行一次 git pull	我们会为你修复，每天测试每个工具
审批	MCP 客户端会在每次调用时征求你的同意	分配、报价、发票和退款会等待你确认；可按工具切换
兼容对象	你电脑上的 MCP 客户端、本地脚本	Claude.ai 和 ChatGPT 连接器、n8n、Make、Zapier，以及任何 HTTP 客户端
适用对象	你，限非商业用途	团队、企业、代理机构
价格	免费	免费试用 7 天，含 2,000 个额度，无需信用卡；之后可购买一次性额度包，5,000 个额度起价 $29

在托管版本中，成功调用会消耗 20 到 30 个额度（大多数工具为 25 个），失败的调用免费；只要云浏览器启用了供 Agent 使用的应用，每天就会消耗 50 个额度。完整定价。

常见问题

BookingKoala 有官方 API 吗？ 没有公开 API。BookingKoala 未发布 REST API 文档。Settings > General > Apps & Integrations 下的 API 密钥仅用于连接 Zapier 和 Make：可触发新建或更新预订、客户、服务提供者、报价、评分和发票的事件，并提供一个操作：Create Lead。它无法查询历史预订、分配服务提供者、重新安排时间、取消预订或重新发送发票。详情：cotlet.dev/integrations/bookingkoala-api-mcp-server。

有适用于 Claude、ChatGPT 或 Cursor 的 BookingKoala MCP 服务吗？ 有，这个服务在你的计算机上运行：Claude Code、Claude Desktop、Cursor 和 Codex 可使用 bookingkoala-mcp mcp。ChatGPT 和 Claude.ai 连接器需要公开的 HTTPS URL，托管版 BookingKoala MCP 服务可提供该 URL。

我需要 Zapier 或 BookingKoala API 密钥吗？ 不需要。这些工具使用你已登录的管理员会话，也就是浏览器使用的同一会话。

我可以将 BookingKoala 的预订或客户导出为 CSV 吗？ 可以：使用 python examples/list_bookings.py --status all --out bookings.csv 和 python examples/export_customers.py --out customers.csv，即可导出所有分页中的数据。

它能自动分配服务提供者吗？ examples/assign_unassigned.py 会先显示计划，然后将每个未分配的工作分配给当天工作量最少的服务提供者。BookingKoala 仍会拒绝分配当时无法提供服务的服务提供者，脚本也会列出这些工作。

为什么需要我的 Chrome？ 为了读取你的 BookingKoala 会话，而无需使用你的密码。每次登录时会使用一次 Chrome，而不是每次调用都使用。

BookingKoala 将我登出后会怎样？ 调用会因 auth_expired 失败。启用 Chrome 远程调试后，服务会在下一次调用时读取新会话（Chrome 提示时点击 Allow）。否则，请再次运行 bookingkoala-mcp connect。

可以在 VPS 或 Docker 中运行吗？ 技术上可以，需要设置 BOOKINGKOALA_STORE 和 BOOKINGKOALA_AUTH_TOKEN。这样 BookingKoala 会看到来自数据中心 IP 的会话。若要始终在线运行，托管版本会将你的会话保存在你自己的 Cloud Browser 中，并使用固定 IP。

我可以将它用于自己的清洁业务吗？ 不可以。许可证仅允许非商业用途，而运营自己的店铺属于商业用途。对于你的公司，请使用 Cotlet 或发送邮件至 [email protected]。

它是开源的吗？ 源代码公开，但许可证并非开源许可证：仅限非商业用途，不得用于商业活动。

某个工具出故障了，或者我需要其他工具。 请提交问题，并注明工具名称和错误消息。

许可证

PolyForm Noncommercial License 1.0.0。简而言之：

• **允许：**非商业用途：你为个人目的使用自己的 BookingKoala 账户，或由慈善机构、学校、公共研究机构或政府机构使用。可以修改代码，并依据相同许可证分享。
• **不允许：**任何商业用途，包括运营自己的业务；客户项目；销售或提供该工具，或基于该工具构建的服务。

---

由 Cotlet（@cotletdev）维护。BookingKoala 是其所有者的商标。本项目为非官方项目，与 BookingKoala 无关联，也未获其认可或赞助。