Skip to main content
Glama

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 fetch API and AbortSignal.timeout)

  • No npm dependencies — run node server.mjs directly

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

  • Windows: %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.mjs

Other 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.mjs

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

  1. Press F12 (or right-click the page → Inspect).

  2. Open the Network tab. Filter by customer_api/me.

  3. Click a request to /core/v2/customer_api/me (reload the page if none appear).

  4. Under Request Headers, copy the value of x-access-token. That is the raw token.

Chrome or Edge (Cookies)

  1. Press F12 → Application → Cookies → https://booksy.com.

  2. Select the cookie named identity-br.

  3. 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 the accessToken field.

    • 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

  1. Open Developer Tools (F12) → Storage → Cookies → https://booksy.com.

  2. Select identity-br and extract the raw token with the same rules as above.

  3. Or use the Network tab, filter customer_api/me, and copy x-access-token from the request headers.

Safari

  1. Enable the Develop menu: Safari → Settings → Advanced → “Show features for web developers” (wording may be “Show Develop menu in menu bar” on older versions).

  2. Develop → Show Web Inspector → Storage → Cookies.

  3. Select identity-br on https://booksy.com and extract the raw token with the same rules as above.

  4. Or use the Network tab and copy x-access-token from a customer_api/me request.

Do not commit the token, and do not paste it into chats or issues.

3. Where to put it

The server checks, in order:

  1. BOOKSY_ACCESS_TOKEN in the environment (wins if set and non-empty)

  2. BOOKSY_TOKEN_FILE, if you want a custom path

  3. Otherwise ~/.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/token

Lifetime 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_FINGERPRINT if set

  • otherwise BOOKSY_FINGERPRINT_FILE, or ~/.config/booksy/fingerprint

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

BOOKSY_COUNTRY

br

API host {country}.booksy.com. Only br is tested.

BOOKSY_LOCALE

pt-BR

Accept-Language

BOOKSY_API_KEY

(scraped)

Override the public marketplace key

BOOKSY_CACHE_DIR

a temp dir

Where the scraped key cache is stored

BOOKSY_FETCH_KEY

(enabled)

Set to 0 to disable the JS scrape

BOOKSY_APP_VERSION

1.213.0

Sent as X-App-Version / meta.app_version (widget shape)

BOOKSY_UA

a Chrome desktop UA

HTTP User-Agent

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 keywords

  • location (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 from search_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) — from get_business

  • date (required) — YYYY-MM-DD

  • staffer_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) or inactive (finished). upcoming and finished / past are 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-DD

  • time (required) — HH:MM

  • dry_run (optional, default true)

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) — the appointment_uid from list_my_bookings

Limits

  • No email/password login (hCaptcha is required on that endpoint).

  • Slots from get_free_slots are live and can disappear before create_booking runs.

  • Be polite with request volume; this is a personal automation client, not a scraper.

  • Bookings created through this plugin are attributed with booking_source Other_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).

  1. search_businesses with query "Brabo Barbearia" and location "São Caetano do Sul"

  2. get_business with business_id 103441

  3. get_free_slots with that business_id, a service_variant_id from the shop (example: 1421878 for Combo), a date such as 2026-11-20, and optionally a staffer_id (example: 230915)

  4. create_booking with the same ids, date, and time (example: "14:00"), leaving dry_run true

  5. Only after the user approves the preview, call create_booking again with dry_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

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      10
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      2
      28
      102 PyPI
      6
      Elastic 2.0