Booksy MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Booksy MCP
Unofficial Model Context Protocol (MCP) server and Agent Plugin for Booksy's customer API in Brazil (br.booksy.com). Search shops, list services and staff, check free slots, and — with a customer access token you supply — list, preview, confirm, or cancel bookings.
Disclaimer
This is an unofficial, community-maintained project. It is not affiliated with, endorsed by, or supported by Booksy. It talks to Booksy's undocumented web customer API, which can break or change without notice. Use it at your own risk, and respect Booksy's Terms of Service.
Coverage is Brazil only. The BOOKSY_COUNTRY environment variable exists, but only br has been tested.
Related MCP server: Appointedd MCP Server
One-click setup for agents
Click the copy icon on the block below and paste it into your coding agent, such as Cursor, Claude Code, Codex, or OpenCode.
Set up Booksy Brazil MCP for my coding agent on this machine.
1. Clone https://github.com/p4cs-974/booksy-mcp into a suitable local directory, or reuse an existing clone without overwriting local changes. Read its README.md and skills/booksy/SKILL.md. Verify Node.js 18 or later is available. There are no npm dependencies to install. Run the server with node server.mjs.
2. Add a stdio MCP server named booksy to this agent's MCP configuration, preserving existing entries. Use command "node" and args ["/absolute/path/to/server.mjs"], replacing the path with the actual absolute path in the clone. For Cursor, .cursor/mcp.json is one option; use the equivalent configuration for other clients. The repository's mcp.json uses args ["./server.mjs"] and cwd "${PLUGIN_ROOT}" for clients implementing Agent Plugins 1.0.0. Do not assume that variable works in a normal MCP configuration.
3. If this agent supports skills, install skills/booksy/SKILL.md using its supported skill installation mechanism.
4. Ask me for a Booksy customer access token through a secure input mechanism, never ordinary chat. Prefer storing it outside the repo at ~/.config/booksy/token with mode 600. Alternatively, use BOOKSY_ACCESS_TOKEN in the server's environment. Never hardcode the token or write it into chat logs, issues, or the repo. If secure input is unavailable, ask me to create the token file locally. Token lookup order is non-empty BOOKSY_ACCESS_TOKEN, otherwise the file at BOOKSY_TOKEN_FILE if set, otherwise ~/.config/booksy/token. Email/password login is unsupported. If I need help, point me to "Getting a customer access token" in README.md to copy x-access-token from my existing browser session. Do not scrape the token.
5. Reload the MCP client if needed. Verify by calling search_businesses with {"query":"barbearia"}; query is required and location is optional. search_businesses, get_business, and get_free_slots work without a token, so run this check even if I skip token setup. Account tools require a token. Do not call create_booking or cancel_booking during setup.
Report the configuration and skill paths, verification result, and any remaining steps without revealing secrets.Requirements
Node.js 18 or later (the server uses the global
fetchAPI andAbortSignal.timeout)No npm dependencies — run
node server.mjsdirectly
Install
Clone or copy this directory somewhere on your machine. In the snippets below, replace /path/to/server.mjs with the absolute path to server.mjs in that copy.
Account tools also need a customer access token (see Getting a customer access token). Read-only search and availability tools work without one.
Cursor
Local plugin folder. Copy this directory to ~/.cursor/plugins/local/booksy (a real directory, not a symlink), then reload the window.
Or add a server in .cursor/mcp.json (project) or your Cursor user MCP config:
{
"mcpServers": {
"booksy": {
"command": "node",
"args": ["/path/to/server.mjs"]
}
}
}The plugin's own mcp.json uses a relative ./server.mjs and cwd: "${PLUGIN_ROOT}", as required by the Agent Plugins 1.0.0 schema. Clients that implement that schema set PLUGIN_ROOT for you. Cursor's plugin loader may use a different variable (${CURSOR_PLUGIN_ROOT}) and may not expand ${PLUGIN_ROOT}; if a Cursor-local plugin install does not start, launch node ./server.mjs yourself with the plugin directory as the working directory, or use the .cursor/mcp.json snippet above with a concrete path.
Claude Desktop
Add the server to claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"booksy": {
"command": "node",
"args": ["/path/to/server.mjs"]
}
}
}Restart Claude Desktop after saving.
Grok Bot
Add a custom MCP server with this command:
node /path/to/server.mjsOther stdio MCP clients
The server speaks JSON-RPC 2.0 over stdin/stdout (newline-delimited JSON, or Content-Length framing). Point the client at:
node /path/to/server.mjsIf the client supports an env map on the server entry, you may set BOOKSY_ACCESS_TOKEN there. Prefer the token file (below) so the token does not end up in a config file you might commit. Do not put tokens in this repository.
Read tools (no login)
search_businesses, get_business, and get_free_slots use Booksy's public marketplace x-api-key. You do not need an account.
If BOOKSY_API_KEY is unset, the server scrapes the production web-* key from booksy.com JavaScript assets at runtime and caches it in a temp file for 24 hours. You can set BOOKSY_API_KEY to skip that scrape. Never print, commit, or paste that key.
Getting a customer access token
Email/password login is not supported: Booksy requires an hCaptcha token on POST /core/v2/customer_api/account/login. Account tools therefore use a session token you copy from a browser session you already have.
The marketplace web app stores the token in a cookie named identity-br (that is identity- plus the country code) with max-age 31536000 seconds (365 days), path=/, Secure, and SameSite=Lax. On login, the app writes only the raw access-token string into that cookie — not the full { accessToken, profile } object it keeps in memory.
The cookie helper URL-encodes the value (encodeURIComponent). For a typical token (letters and digits, no punctuation), the encoded form is identical to the raw token. The helper only JSON-wraps the value first when it is not a plain string, or when the string itself parses as JSON that is not a string (for example an object). On read, the app runs decodeURIComponent and then tries JSON.parse.
The Network tab is the most reliable way to get the raw token, because x-access-token is the header the API actually uses.
1. Log in
Open booksy.com, sign in to your customer account, and stay on the site.
2. Copy the token
Chrome or Edge (recommended: Network)
Press F12 (or right-click the page → Inspect).
Open the Network tab. Filter by
customer_api/me.Click a request to
/core/v2/customer_api/me(reload the page if none appear).Under Request Headers, copy the value of
x-access-token. That is the raw token.
Chrome or Edge (Cookies)
Press F12 → Application → Cookies →
https://booksy.com.Select the cookie named
identity-br.Copy its value, then:
If it is a bare token (no
%sequences, no surrounding quotes or{...}), use it as-is. This is the usual case.If it looks URL-encoded (
%22,%7B, and so on), decode it first. In DevTools console:decodeURIComponent("paste-the-cookie-value").If the decoded value is JSON such as
{"accessToken":"..."}, use theaccessTokenfield.If the decoded value is a quoted JSON string (it starts and ends with
"), parse it:JSON.parse("paste-the-decoded-value"). The result is the raw token.
Firefox
Open Developer Tools (F12) → Storage → Cookies →
https://booksy.com.Select
identity-brand extract the raw token with the same rules as above.Or use the Network tab, filter
customer_api/me, and copyx-access-tokenfrom the request headers.
Safari
Enable the Develop menu: Safari → Settings → Advanced → “Show features for web developers” (wording may be “Show Develop menu in menu bar” on older versions).
Develop → Show Web Inspector → Storage → Cookies.
Select
identity-bronhttps://booksy.comand extract the raw token with the same rules as above.Or use the Network tab and copy
x-access-tokenfrom acustomer_api/merequest.
Do not commit the token, and do not paste it into chats or issues.
3. Where to put it
The server checks, in order:
BOOKSY_ACCESS_TOKENin the environment (wins if set and non-empty)BOOKSY_TOKEN_FILE, if you want a custom pathOtherwise
~/.config/booksy/token
The file is re-read on every call, so you can replace the token without restarting the server.
mkdir -p ~/.config/booksy
# paste only the raw token, no quotes or JSON wrapper, then:
chmod 600 ~/.config/booksy/tokenLifetime and rotation
The identity-br cookie is issued with a max-age of about 365 days. There is no refresh endpoint. Logging out of Booksy may revoke the token. When it stops working, sign in again and copy a new one; replace the env var or token file, and delete the old value.
Treat the token like a password. Anyone who has it can act as you on Booksy (list, book, cancel). Never commit it, never paste it into chats or GitHub issues, and do not check it into mcp.json or shell history if you can avoid it.
Optional fingerprint
The official booking widget always sends an X-Fingerprint header (a UUID, stored in the widget's _bf cookie). This server does the same:
BOOKSY_FINGERPRINTif setotherwise
BOOKSY_FINGERPRINT_FILE, or~/.config/booksy/fingerprintotherwise it generates a UUID and tries to save it at that path
You usually do not need to set this yourself.
Other environment variables
Variable | Default | Purpose |
|
| API host |
|
|
|
| (scraped) | Override the public marketplace key |
| a temp dir | Where the scraped key cache is stored |
| (enabled) | Set to |
|
| Sent as |
| a Chrome desktop UA | HTTP |
The Agent Plugins 1.0.0 manifest schema has no variables field, and mcp.json env will not expand arbitrary ${ENV} placeholders, so these are not declared in the manifests. Set them in the environment inherited by the process.
Tools
Write tools (create_booking, cancel_booking) must be confirmed with the user before they are called.
search_businesses
No auth. Search Booksy businesses in Brazil.
query(string, required) — shop name or keywordslocation(string, optional) — city or place hint (resolved to a location id first)
Returns compact BusinessSummary objects: id, name, address, city, rating, reviews_count, url.
get_business
No auth. Details for one shop.
business_id(required) — id fromsearch_businesses
Returns BusinessDetail: address, services (each with variants: variant_id, price, duration_min), and staff (staffer_id, name).
get_free_slots
No auth. Free start times for one service on one date.
business_id(required)service_variant_id(required) — fromget_businessdate(required) —YYYY-MM-DDstaffer_id(optional) — filtered client-side; the upstream query does not narrow the payload
Returns DaySlots with start times HH:MM. Availability can change before you book; treat this as a snapshot.
list_my_bookings
Requires a customer access token. Lists the logged-in customer's bookings.
state(optional) —active(upcoming) orinactive(finished).upcomingandfinished/pastare also accepted.page(optional, default 1)per_page(optional, default 20)
Returns compact appointment objects (appointment_uid, booked_from, status, business, service, staffer, total).
create_booking
WRITE. Confirm the shop, service, staff, date, and time with the user first.
business_id(required)service_variant_id(required)staffer_id(required)date(required) —YYYY-MM-DDtime(required) —HH:MMdry_run(optional, defaulttrue)
When dry_run is true (the default), the server creates a temporary draft, sets the service, staffer, and timeslot, and returns the confirmation preview (GET /drafts/{id}/confirmation). It does not call /schedule, so no appointment is confirmed. When dry_run is false, it goes on to POST /drafts/{id}/schedule and confirms a real appointment.
Keep dry_run=true until the user has seen the preview and explicitly asks you to book. Then call again with the same arguments and dry_run=false.
cancel_booking
WRITE, destructive. Confirm with the user first. This cancels a real appointment and cannot be undone from this plugin.
appointment_id(required) — theappointment_uidfromlist_my_bookings
Limits
No email/password login (hCaptcha is required on that endpoint).
Slots from
get_free_slotsare live and can disappear beforecreate_bookingruns.Be polite with request volume; this is a personal automation client, not a scraper.
Bookings created through this plugin are attributed with
booking_sourceOther_Integration.The API is undocumented and may change. Brazil (
br) is the only tested region.
Example (public shop ids)
The ids below are from a public Booksy shop listing and are shown only as an example. They are not a recommendation, and they may change. Always search and read the live shop before booking.
Example shop: Brabo Barbearia, business_id 103441 (São Caetano do Sul).
search_businesseswithquery"Brabo Barbearia"andlocation"São Caetano do Sul"get_businesswithbusiness_id103441get_free_slotswith thatbusiness_id, aservice_variant_idfrom the shop (example:1421878for Combo), a date such as2026-11-20, and optionally astaffer_id(example:230915)create_bookingwith the same ids, date, and time (example:"14:00"), leavingdry_runtrueOnly after the user approves the preview, call
create_bookingagain withdry_run=false
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Read AgendaPro bookings, slots, clients, services and sales; create, update and cancel bookings.
Read services, staff, bookings and clients; create and cancel bookings in BKG.
1Discover local services and availability, then create, track, reschedule, or cancel bookings.
Booksy MCP server for ChatGPT, Claude and any AI agent: list bookings, create booking, reschedule booking, reply to review and read reports in your own Booksy account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Booksy yourself; Cotlet does not store your password and you need no Booksy API key. About the official Booksy API: Booksy has no self-serve API for business owners (checked 11 Oct 2026). It runs a partner API whose docs at docs.booksy.com ask for a login, so you cannot get keys for your own account. Setup and FAQ: https://cotlet.dev/integrations/booksy-api-mcp-server
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables AI agents to manage spa/wellness operations via Zenoti API, including appointments, guests, services, and billing.2357 npmMIT
- AlicenseAqualityCmaintenanceEnables MCP clients to search availability, read services, resources, bookings and customers, and, when writes are enabled, reserve slots, create or cancel bookings, and add or update customers.10MIT
- AlicenseAqualityCmaintenanceEnables AI agents to look up businesses, find free appointment slots, book, list and cancel appointments at salons, barbershops, nail and brow studios and clinics. Works read-only without a customer login by returning a pre-filled booking link, and can also run against a built-in demo with sample businesses.5MIT
- AlicenseAqualityBmaintenanceEnables AI agents and scripts to run a Booksy Biz account through your own signed-in Chrome session, exposing 28 tools for appointments, open slots, time off, clients, services, staff, reviews, Message Blasts, and reports over MCP, REST, or Python. Read-only mode and confirmation-gated client-facing actions let you plan schedules, reschedules, and outreach with human approval.228102 PyPI6Elastic 2.0