Booksy by Cotlet

Booksy API 和 MCP 服务，可自托管

一个 Booksy API 和 Booksy MCP 服务，使用 Python 在你自己的电脑上，通过你自己的 Google Chrome 会话运行。我们在 Cotlet 的生产环境中运行的全部 28 个 Booksy Biz 工具：日历、可预约时段、休假时间、客户、服务和员工、评价、Message Blasts 以及 Stats & Reports。

Booksy 没有面向商家的自助 API，也没有官方 MCP 服务。此代码仓库两者都提供：

• 面向 Claude Code、Claude Desktop、Cursor、Codex 及任何 MCP 客户端的 MCP 服务，支持 stdio 或 HTTP。设置
• REST API，地址为 http://127.0.0.1:8787/api/v1/booksy，OpenAPI 文档位于 /docs。设置
• Python：call("list_appointments", {"from": "2026-10-27", "to": "2026-10-27"})，以及 examples/ 中的 9 个即用脚本。

本项目面向想要自行运行它的技术人员，仅限非商业用途（许可证）。如果你希望它在服务上全天候运行，在 Booksy 更改其管理面板时仍能正常工作，或供团队或企业使用，请使用 cotlet.dev 上的托管版本。

git clone https://github.com/cotletdev/booksy-api-mcp-server.git && cd booksy-api-mcp-server
python3 -m venv .venv && . .venv/bin/activate && pip install -e .
booksy-mcp connect                                 # reads your Booksy Biz session from Chrome
booksy-mcp call list_services
claude mcp add booksy -- "$PWD/.venv/bin/booksy-mcp" mcp

目录

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

工作原理

AI agent (MCP) / script (REST, Python) ──▶ booksy-mcp on your computer ──your Booksy session──▶ <country>.booksy.com
                                                   ▲
                         booksy-mcp connect ───────┘ reads it once from your Chrome (DevTools Protocol)

1. 像往常一样，在你自己的 Chrome 中登录 Booksy Biz：booksy.com/pro。
2. booksy-mcp connect 通过 Chrome DevTools Protocol 连接到该 Chrome，并读取你的会话。Booksy 不会将会话保存在 Cookie 中。管理面板会将其存储在 web-gateway.booksy.com 框架的 localStorage 中，因此 connect 会读取该存储、booksy.com Cookie 以及管理面板的国家/地区信息，并保存到 ~/.config/booksy-api-mcp/session.json，只有你的用户可以读取。它绝不会查看或存储你的密码。
3. 每次工具调用都会向 Booksy Biz 网页管理面板所调用的 API 发起请求（<country>.booksy.com/core/v2，因此美国商家使用 us.booksy.com，波兰商家使用 pl.booksy.com），并通过 curl_cffi 发送请求，该工具会复制 Chrome 的 TLS 指纹。不会运行无头浏览器。

Booksy 将你登出后，只要 Chrome 已打开并启用了远程调试，服务就会再次从 Chrome 读取会话。

要求

• Python 3.11 或更高版本。
• Google Chrome 144 或更高版本，并已登录 Booksy Biz。任何启用了调试端口的 Chrome 或 Chromium 均可使用。
• macOS、Linux 或 Windows。
• Booksy Biz 所有者账户。部分报告（例如 Staff Members）需要 Booksy Biz Pro。Booksy 只会在付费套餐中发送一次性 Message Blasts，免费试用期间不会发送。

安装

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

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

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

更新方式：git pull && pip install -e .。我们会将托管版 Booksy 工具的每项更新都同步到此代码仓库。

连接你的 Chrome

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

1. 在 Chrome 中打开 chrome://inspect/#remote-debugging，然后开启远程调试。之后，Chrome 会接受这台电脑上程序发起的 DevTools 连接，并在每次连接前询问你。

2. 确保已登录 Booksy Biz：booksy.com/pro。保持面板所在的标签页打开，因为 connect 会读取其中的会话。如果没有打开 Booksy 标签页，它会在后台打开一个，随后再将其关闭。

3. 运行：

   booksy-mcp connect
   

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

Saved 41 Booksy cookies and 50 localStorage keys to /Users/you/.config/booksy-api-mcp/session.json
Signed in to Booksy as Maria Lopez (Studio Maria)

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

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

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

Chrome 不会在默认个人资料上开放调试端口，因此请启动一个单独的 Chrome，在其中登录 Booksy Biz 一次，然后连接到该实例：

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-booksy"
# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-booksy"
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.chrome-booksy"

booksy-mcp connect --cdp http://127.0.0.1:9222

--cdp 也接受 ws:// DevTools URL，例如通过 SSH 隧道连接到另一台机器上的 Chrome。

由于 Booksy 没有会话 Cookie，因此无法手动粘贴 Cookie。没有 Chrome 的服务可以使用从运行过 connect 的机器复制而来的 session.json。

随时检查会话：

booksy-mcp status

MCP 服务

MCP 服务会列出每个工具及其输入架构、面向 Agent 编写的描述和提示。读取工具会标记为只读；会联系客户端的工具（预订、改期、取消、回复评价、群发消息）会标记为需要客户端在运行前询问。

Claude Code

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

Claude Desktop

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

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

Cursor

~/.cursor/mcp.json，配置内容与 Claude Desktop 相同。可直接使用 mcp.json 中准备好的副本。

Codex

~/.codex/config.toml：

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

通过 HTTP

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

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

然后可以向 Agent 提出如下问题：

明天的安排如何？列出预约，以及所有超过一小时的空档。

Tom 周五休息。把他的预约安排给时间大致相同且有空的人，并先给我看看计划。

比较上周每位员工的营收与前一周的营收。

哪些客户已 60 天没来过，而且没有预约？

REST API

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

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

curl 'http://127.0.0.1:8787/api/v1/booksy/services'
curl 'http://127.0.0.1:8787/api/v1/booksy/appointments?from=2026-10-27&to=2026-10-31'
curl 'http://127.0.0.1:8787/api/v1/booksy/services/8307205/open-slots?date=2026-10-27'
curl -X POST http://127.0.0.1:8787/api/v1/booksy/staffs/882081/time-offs \
  -H 'Content-Type: application/json' \
  -d '{"start": "2026-11-02", "end": "2026-11-06", "reason": "vacation"}'

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

curl -X POST http://127.0.0.1:8787/api/v1/booksy/tools/find_client -d '{"query": "nowak"}'

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

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

BOOKSY_MCP_TOKEN=$(openssl rand -hex 24) booksy-mcp serve --host 0.0.0.0

Python 和示例脚本

直接使用 Python，无需服务：

from booksy_api_mcp import call
from booksy_api_mcp.scripting import paginate, write_rows

services = call("list_services")["services"]
day = call("list_appointments", {"from": "2026-10-27", "to": "2026-10-27"})["appointments"]
clients = list(paginate("list_clients", {"not_visited_days": 60, "limit": 100}, "clients"))
write_rows(clients, "slipping-away.csv")
call("add_time_off", staff_id="882081", start="2026-11-02T13:00", end="2026-11-02T14:00", reason="Lunch")

或者在命令行中调用一个工具：booksy-mcp call find_open_slots service_id=8307205 date=2026-10-27，也可以传入 JSON 对象。工具要求文本的 ID 会保持为文本。

时间均采用商家的当地时间。不带时区的日期时间会按商家的时区解析，返回结果会带有时区偏移量。

可直接使用的脚本位于 examples/。每个脚本都会输出 JSON 或简短列表；在适用时支持 --out file.csv 或 --out file.json，并提供 --help：

脚本	功能
tomorrows_appointments.py	明天的预约，每行一条，并列出某项服务的剩余可预约时段。支持 --date、--staff-id。
reschedule_day.py	将某位员工当天的预约改到其他员工名下，新时段与原时段相差不超过一小时。先输出计划；使用 --apply 后会逐项询问并执行改期。
block_time_off.py	添加全天休假或屏蔽某一天的若干小时，也可移除休假时段。
export_clients.py	将客户导出为 CSV 或 JSON：联系方式、备注、到访次数、未到次数、收入、最近一次到访时间。支持 --search、--not-visited-days。
lapsed_clients.py	查找 N 天未到访的客户，并排除未来 30 天内已有预约的客户。
win_back_blast.py	向这些长期未到访的客户发送一条 Message Blast；先显示覆盖人数和 SMS 费用并征求确认。
weekly_staff_report.py	按员工统计预约和收入，对比上周与前一周，并标记显著变化。
unanswered_reviews.py	按评分从低到高列出尚未回复的评价；--reply-to 用于发布回复。
add_client.py	添加不含邀请的客户档案，或为现有客户添加备注。

python examples/tomorrows_appointments.py --open-slots-for 8307205
python examples/reschedule_day.py --staff-id 882081 --date 2026-10-27
python examples/export_clients.py --not-visited-days 60 --out slipping-away.csv

要定时运行，可以使用自己电脑上的 cron；电脑开机时即可运行：0 19 * * * cd ~/booksy-api-mcp-server && .venv/bin/python examples/tomorrows_appointments.py。

全部 28 个工具

ID 来自工具列表：service_id 来自 list_services，staff_id 来自 list_staff，client_id 来自 list_clients 或 find_client，appointment_id 来自 list_appointments。运行 booksy-mcp tools 可打印此列表，运行 booksy-mcp tools --json 可同时显示输入架构。

日历

工具	访问权限	REST 路由	功能
list_appointments	读取	GET /appointments	列出日期范围内的预约，包括客户、服务、员工、时间和状态。
get_appointment	读取	GET /appointments/{appointment_id}	获取一条预约的详细信息：服务、员工、时间、价格、客户和备注。
find_open_slots	读取	GET /services/{service_id}/open-slots	查找某项服务在某一天的空闲开始时间，综合考虑工作时间、预约、屏蔽时段和休假。
create_appointment	写入	POST /clients/{client_id}/appointments	为客户预约一项服务并指定开始时间；Booksy 会先检查该时段。
reschedule_appointment	写入	POST /appointments/{appointment_id}/reschedule	将预约改到新的开始时间，也可选择改由另一位员工负责。
cancel_appointment	写入	POST /appointments/{appointment_id}/cancel	取消预约并释放日历中的时段。

休假

工具	访问权限	REST 路由	功能
list_time_off	读取	GET /time-offs	列出日期范围内员工的休假和屏蔽时段。
add_time_off	写入	POST /staffs/{staff_id}/time-offs	屏蔽员工的日历，使任何人都无法预约：可以设置全天休假或屏蔽若干小时。
remove_time_off	写入	DELETE /staffs/{staff_id}/time-offs/{time_off_id}	移除休假或屏蔽时段，以便重新预约该时段。

客户端

工具	访问权限	REST 路由	功能说明
list_clients	读取	GET /clients	客户列表，包含联系方式、到访次数和最近到访时间，以及 Booksy 的客户分组。
find_client	读取	GET /clients/search	查找姓名、电子邮箱或电话号码匹配的客户卡片。
get_client	读取	GET /clients/{client_id}	查看单张客户卡片：联系方式、私人备注、次数统计和到访记录。
add_client	写入	POST /clients	将客户卡片添加到客户列表。需要提供电话号码或电子邮箱。
update_client	写入	PATCH /clients/{client_id}	修改客户卡片上的姓名、电话、电子邮箱、生日或私人备注。
add_client_note	写入	POST /clients/{client_id}/notes	为客户的私人备注添加带日期的一行内容，并保留现有内容。
delete_client	写入	DELETE /clients/{client_id}	从客户列表中移除客户卡片。

商家设置

工具	访问权限	REST 路由	功能说明
list_services	读取	GET /services	服务菜单，包含类别、变体、时长、价格以及提供各项服务的员工。
list_staff	读取	GET /staff	员工列表，包含每周工作时间和提供的服务。
get_business_hours	读取	GET /business-hours	商家的每周营业时间、时区和预约提前时间。
get_business_profile	读取	GET /business	商家的名称、地址、联系方式、营业时间、预约政策、评分和套餐状态。
get_settings	读取	GET /settings	短信额度和使用情况、客户消息渠道及通知设置。
list_notifications	读取	GET /notifications	控制面板铃铛中的通知：新预约、变更、取消和评价。

评价

工具	访问权限	REST 路由	功能说明
list_reviews	读取	GET /reviews	客户对商家的评价，包含评分、文字内容、服务、员工和商家回复。
reply_to_review	写入	PUT /reviews/{review_id}/reply	发布或修改对客户评价的公开回复。

群发消息

工具	访问权限	REST 路由	功能说明
list_message_blasts	读取	GET /message-blasts	群发消息模板（自动和单次）以及计划发送的群发消息。
estimate_message_blast	读取	GET /message-blasts/estimate	统计群发消息的触达人数和短信费用，不会实际发送。
send_message_blast	写入	POST /message-blasts	通过电子邮件、短信或推送通知向选定客户发送一条消息。

统计与报告

工具	访问权限	REST 路由	功能说明
get_report	读取	GET /reports/{category}	以 JSON 格式获取统计与报告中的数据，时间范围可以是日、周、月或年。

写入操作会先运行 Booksy 自带的 dry run，除非传入 notify_client，否则不会通知客户。新客户不会收到邀请。send_message_blast 会拒绝空客户列表，因为 Booksy 会将空列表视为所有客户。

我们有意不实现：Booksy 登录、电子邮件、密码和账户删除，以及任何资金相关操作（订阅、付款、结算、账单）。每个请求都会经过一道防护检查，拒绝访问这些 Booksy 路径。

配置

变量	默认值	功能说明
BOOKSY_MCP_HOME	~/.config/booksy-api-mcp	存放 session.json 的文件夹。
BOOKSY_PROXY		所有 Booksy 请求使用的代理，例如 http://user:pass@host:port。
BOOKSY_MCP_READ_ONLY		1 会隐藏并拒绝所有会修改 Booksy 的工具（等同于 --read-only）。
BOOKSY_MCP_TOKEN		serve 所需的 Bearer 令牌；监听地址超出 127.0.0.1 时必须设置。
BOOKSY_MCP_HOST, BOOKSY_MCP_PORT	127.0.0.1, 8787	serve 的地址。

安全与您的 Booksy 账户

• 您的密码不会传到此代码中。 这里只会读取面板已保存的会话，而且仅限 booksy.com 的会话。
• 会话文件属于您。 session.json 创建时的权限为 0600，其中保存了您的 Booksy 访问令牌。任何拿到它的人都能以您的身份操作 Booksy Biz，因此请勿将其提交到 git 或放在共享文件夹中。
• 默认仅限本地。 serve 会绑定到 127.0.0.1，若未设置 BOOKSY_MCP_TOKEN，则拒绝使用其他地址。
• 仅限 booksy.com。 会拒绝发送到 booksy.com 以外的请求，以及跳转到该域名以外的请求。
• 只读模式。 --read-only 或 BOOKSY_MCP_READ_ONLY=1 仅开放 17 个只读工具。
• 操作会影响真实用户。 预约、使用 notify_client 的改期、取消、回复评价和群发都会触达您的客户。MCP 客户端会在执行前征求确认；脚本不会，因此请先在您自己的测试客户上试用。
• 请勿发送垃圾信息。 向未同意的人群发消息违反 Booksy 的规则，也违反许多国家的法律。您需要对账户中执行的操作负责。

错误

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

状态	代码	处理方法
401	auth_required, auth_expired	没有会话，或 Booksy 已将您登出。请在 Chrome 中登录 Booksy Biz，然后运行 booksy-mcp connect。
403	app_permission_denied	您的 Booksy 套餐或角色无权执行此操作，例如在 Booksy Biz Lite 中查看 Pro 报告。
403	scope_denied	服务处于只读模式，或请求会更改您的 Booksy 账户本身。
403	target_blocked	Booksy 拒绝了请求，或显示了机器人验证。请在 Chrome 中打开一次面板，然后重试。
409	captcha_required	Booksy 要求进行 CAPTCHA 验证。请在 Chrome 中完成验证。
422	invalid_input	缺少参数或参数有误；消息会指出具体参数。
429	rate_limited	Booksy 正在限制此账户。请等待几分钟。
502	target_error	Booksy 返回了错误，或更改了其面板。请在我们修复后运行 git pull 获取最新工具，或提交问题。

可自托管或托管版本

	此仓库	Cotlet，托管版
工具	相同的 28 个	相同的 28 个
运行位置	您的电脑上，电脑开机时运行	云端，全天候运行
Booksy 会话	您的 Chrome，会话保存在本地文件中	您在欧盟的专属 Cloud Browser，配置文件使用 AES-256-GCM 加密
Booksy 更改面板时	修复后运行一次 git pull	我们会为您修复，每天测试所有工具
确认	您的 MCP 客户端会逐次调用征求确认	预约、改期、回复和群发都会等待您的确认；可按工具切换
适用对象	您的电脑上的 MCP 客户端、本地脚本	Claude.ai 和 ChatGPT 连接器、n8n、Make、Zapier，以及任何 HTTP 客户端
使用者	您本人，仅限非商业用途	团队、企业、代理机构
价格	免费	免费试用 7 天，含 2,000 点数，无需银行卡；之后可购买一次性点数包，5,000 点数起价 $29

在托管版本中，成功调用会消耗 20 到 30 点数（大多数工具为 25 点数）；失败调用免费；启用了 Agent 应用的 Cloud Browser 每天消耗 50 点数。完整定价。

常见问题

Booksy 有官方 API 吗？ 没有供商家使用的 API。Booksy 运营着一个合作伙伴 API，其文档位于 docs.booksy.com，需要登录才能查看，因此你无法获取自己账户的 API 密钥（截至 2026 年 10 月 11 日已核实）。统计与报告和消息群发不属于其公开功能。详情：cotlet.dev/integrations/booksy-api-mcp-server。

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

有 Booksy Zapier 应用吗？ 我们无法确认是否有。想把预约同步到其他地方的商家，会将 Booksy 预约确认邮件转发给 Zapier 邮件解析器。这只能单向复制新预约，无法更改 Booksy 中的任何内容。

我能将 Booksy 客户导出为 CSV 吗？ 可以：python examples/export_clients.py --out clients.csv。可导出所有页面中的每张客户卡片，包括联系方式、备注、到访次数、未到场次数、收入和最近到访时间。

它能查找空闲时段并替我预约吗？ find_open_slots 会列出某项服务在某一天的空闲开始时间，并按员工分别列出；每个时段都会通过 Booksy 自带的试运行进行检查。create_appointment 会为客户预约其中一个时段，只有使用 notify_client 才会通知客户。

它能发送消息群发吗？ 可以，在付费 Booksy 套餐中使用 send_message_blast 发送电子邮件、短信或推送通知。先运行 estimate_message_blast，查看覆盖人数和短信费用。在欧盟，只有同意接收营销信息的客户才会收到消息。

它能在美国以外使用吗？ 可以。Booksy 按国家/地区使用不同的 API，服务会根据你的会话自动选择：us.booksy.com、pl.booksy.com、es.booksy.com 等。

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

Booksy 将我登出后会怎样？ 调用会因 auth_expired 失败。如果已启用 Chrome 远程调试，服务会在下次调用时读取新的会话（Chrome 提示时点击允许）。否则，请重新运行 booksy-mcp connect。

它能在 VPS 或 Docker 中运行吗？ 技术上可以，只需从你的电脑复制 session.json。但这样 Booksy 会看到你的会话来自数据中心 IP，看起来就不那么像是你本人。若要始终在线运行，托管版本会将你的会话保存在你自己的 Cloud Browser 中，并使用固定 IP。

我的 Booksy 账户会被封禁吗？ 请求会携带 Chrome 的指纹，并逐个发送，就像你亲自点击一样。没人能保证平台绝不会采取行动。请保持正常使用，不要向未同意接收消息的人群发信息。

我能将它用于自己的沙龙或客户吗？ 不能。此许可证仅允许非商业用途，而经营自己的业务也属于商业用途。若用于沙龙、团队或客户项目，请使用 Cotlet，或联系 [email protected]。

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

某个工具出故障了，或者我需要另一个工具。 请提交 Issue，注明工具名称和错误消息。

许可证

PolyForm Noncommercial License 1.0.0。简而言之：

• **允许：**非商业用途：你使用自己的 Booksy 账户满足个人需求，或慈善机构、学校、公共研究机构或政府机构使用。修改代码，并按照相同的许可证分享。
• **不允许：**任何商业用途，包括你自己的业务；客户项目；销售或提供本项目，或基于本项目构建的服务。

---

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