# Booksy by Cotlet (pypi · booksy-api-mcp)

Bookings, clients, reviews and reports for beauty businesses.

- Trust score: 65/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-10-24

## Components

- remote · `cotlet.dev`: 69/100, [markdown](https://verifymcp.io/servers/dev-cotlet-booksy/mcp-v1-booksy.md), [page](https://verifymcp.io/servers/dev-cotlet-booksy/mcp-v1-booksy)
- remote · `cotlet.dev`: 40/100, [markdown](https://verifymcp.io/servers/dev-cotlet-booksy/mcp-v1-booksy-connect.md), [page](https://verifymcp.io/servers/dev-cotlet-booksy/mcp-v1-booksy-connect)
- pypi · `booksy-api-mcp`: 65/100 (this document), [markdown](https://verifymcp.io/servers/dev-cotlet-booksy/booksy-api-mcp.md), [page](https://verifymcp.io/servers/dev-cotlet-booksy/booksy-api-mcp)

## Channel facts

- Registry: `pypi`
- Package: `booksy-api-mcp`
- Version: `1.0.3`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-10-24.

- **Supply Chain Security**: 50/100
  - Malware scan not yet available for this package.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs hatchling.build at install time, a recognised build step with no custom scripting around it.
  - 0 of 35 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 84/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to cotletdev/booksy-api-mcp-server).
  - License check failed: the license (PolyForm-Noncommercial-1.0.0) isn't a recognized OSI-approved license.
  - Actively maintained (last published 0 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 82/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 3809 tokens (~126/item across 30 items; 28 tools + 2 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - All 3 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation.
  - An AI judge read all 30 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### How do I install the Booksy by Cotlet MCP server?

Booksy by Cotlet runs locally as a PyPI package, launched with uvx booksy-api-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add dev-cotlet-booksy -- uvx booksy-api-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "dev-cotlet-booksy": {
      "command": "uvx",
      "args": [
        "booksy-api-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "dev-cotlet-booksy": {
      "command": "uvx",
      "args": [
        "booksy-api-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add dev-cotlet-booksy -- uvx booksy-api-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dev-cotlet-booksy": {
      "type": "local",
      "command": [
        "uvx",
        "booksy-api-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add dev-cotlet-booksy --command uvx --arg booksy-api-mcp
```

### Hermes

```yaml
mcp_servers:
  dev-cotlet-booksy:
    command: "uvx"
    args: ["booksy-api-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "dev-cotlet-booksy": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "booksy-api-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add dev-cotlet-booksy -t stdio -c uvx -a booksy-api-mcp
```

### Other

```json
{
  "mcpServers": {
    "dev-cotlet-booksy": {
      "command": "uvx",
      "args": [
        "booksy-api-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-10-24 (score 65)

First indexed and scored.

## MCP tools (28)

### `add_client` (~183 tokens)

Add client

Add a client card to your client list. Needs a phone or an email.

Adds one client card with a name, a phone or an email (Booksy needs one of them), and optionally a private note and a birthday. The client is not invited to the Booksy app and gets no message, so add_client runs without asking first. delete_client removes the card again. A card deleted earlier with the same email or phone comes back with its old visits, note and birthday unless new ones are given.

Input parameters:

- `birthday` (string): YYYY-MM-DD.
- `email` (string): Email address.
- `name` (string, required): Full name; the last word is the last name.
- `note` (string): Private note, seen only by the business.
- `phone` (string): Mobile phone, best in international format (+48 600 100 200).

### `add_client_note` (~85 tokens)

Add client note

Add a dated line to a client's private note, keeping what is there.

Booksy keeps one private note per client card, seen only by the business. This adds a new line starting with today's date under the existing text. The client is not told.

Input parameters:

- `client_id` (integer, required): From list_clients or find_client.
- `text` (string, required): The line to add.

### `add_time_off` (~200 tokens)

Add time off

Block a staff member's calendar so no one can book it: whole days off or a few hours.

Two dates (YYYY-MM-DD) add whole days of time off, like Staff > Shifts. Two date-times on the same day block those hours in the calendar, like a time reservation. Booksy refuses a block over existing appointments. It reaches no client; remove_time_off takes it back.

Input parameters:

- `end` (string, required): Last day off, inclusive (YYYY-MM-DD), or the end of the blocked hours on the same day.
- `reason` (string): Whole days: vacation, sick_day, personal_day, training or other (other text is kept as a note). Hours: any label, e.g. Lunch.
- `staff_id` (string, required): Staff ID from list_staff.
- `start` (string, required): A day (YYYY-MM-DD) for whole days off, or an ISO 8601 date-time to block hours.

### `cancel_appointment` (~133 tokens)

Cancel appointment

Cancel an appointment and free its time in the calendar.

Cancels one appointment as the business. The client is told only with notify_client. A deposit, if any, follows the business's deposit settings. Booksy refuses appointments it no longer lets you cancel (can in get_appointment). There is no undo; book again with create_appointment.

Input parameters:

- `appointment_id` (string, required): Appointment ID from list_appointments.
- `notify_client` (boolean): Tell the client by email and SMS through Booksy. Default: false.
- `reason` (string): Why it is cancelled; saved as the appointment's note.

### `create_appointment` (~233 tokens)

Create appointment

Book a client for one service at a start time; Booksy checks the slot first.

Books one client card for one service. The end follows the service's duration. Booksy's dry run checks the staff member is free first; a busy slot is refused, never double-booked. The client gets Booksy's confirmation only with notify_client. dry_run returns the same answer with saved false and keeps nothing.

Input parameters:

- `client_id` (string, required): Client ID from list_clients or add_client.
- `dry_run` (boolean): Only check the time and price; nothing is saved. Default: false.
- `note` (string): Internal note, only staff see it.
- `notify_client` (boolean): Send Booksy's booking confirmation to the client. Default: false.
- `service_id` (string, required): service_id from list_services (its first variant), or a variant_id.
- `staff_id` (string): Staff ID from list_staff. Default: the first one who offers the service.
- `start` (string, required): ISO 8601. Without a time zone it is the business's local time.

### `delete_client` (~56 tokens)

Delete client

Remove a client card from your client list.

Deletes the card the way the panel's Delete button does. The client is not told. Past appointments stay in the calendar.

Input parameters:

- `client_id` (integer, required): From list_clients or find_client.

### `estimate_message_blast` (~146 tokens)

Estimate Message Blast

Count who a Message Blast would reach and its SMS cost, without sending it.

Asks Booksy what send_message_blast would do with the same clients, channel and text: how many clients it reaches, how many emails, texts or push notifications go out and what the texts cost beyond the plan's free allowance. Where the law asks for marketing consent (EU), consented counts only the clients who agreed; send_message_blast sends to those. Nothing is sent.

Input parameters:

- `channel` (string, required): email, sms or push.
- `client_ids` (array, required): Recipients from list_clients.
- `message` (string, required): Message text; its length sets the SMS parts.

### `find_client` (~106 tokens)

Find client

Client cards matching a name, email or phone.

Searches the client list the way the Clients page's search box does and returns the matching cards with contact details, note and visit counts. A card added a moment ago can take a few seconds to show up in search; get_client reads it by ID at once.

Input parameters:

- `limit` (integer): Most matches to return. Default: 10.
- `query` (string, required): Name, email or phone (or a part of one).

### `find_open_slots` (~172 tokens)

Find open slots

Free start times for a service on one day, from working hours, bookings, blocks and time off.

Returns free start times for one service on one day, earliest first, for each staff member who offers it (or only staff_id). Starts follow the service's time slot interval and leave room for its duration; past times are left out. Booksy's own booking check confirms every slot returned. Pass start and staff_id to create_appointment.

Input parameters:

- `date` (string, required): Day to check.
- `limit` (integer): 1 to 30 slots, earliest first. Default: 12.
- `service_id` (string, required): service_id from list_services (its first variant), or a variant_id.
- `staff_id` (string): Only this staff member. Default: anyone who offers the service.

### `get_appointment` (~99 tokens)

Get appointment

One appointment: services, staff, times, price, client and notes.

Returns one appointment with each service's staff member, times and price, the client, the total and the notes. note is the internal note only staff see; client_note is the note shown to the client. can lists what Booksy allows now (cancel, change, confirm, decline, no_show).

Input parameters:

- `appointment_id` (string, required): Appointment ID from list_appointments.

### `get_business_hours` (~72 tokens)

Get business hours

Weekly opening hours, time zone and booking lead times of the business.

Reads the opening hours set in Business details: open ranges for each day (an empty list is closed), the note shown with them, the business's time zone and address, and how early and how late clients may book or change a visit.

### `get_business_profile` (~92 tokens)

Get business profile

Your business's name, address, contact, opening hours, booking policy, rating and plan status.

Reads the business record behind your Booksy profile: name, address and time zone, phone, public email, website, description, weekly opening hours, how far ahead clients can book and change, review rating, whether the profile is visible in the Booksy marketplace, and the plan status with the trial end date.

### `get_client` (~132 tokens)

Get client

One client card: contact details, private note, counts and visit history.

Reads one client card of the business by ID: name, email, phone, birthday, private note, tags, whether the client is blocked or uses the Booksy app, visit, no-show and cancellation counts, revenue, and the visits (past and upcoming appointments) with times, services, staff, status and total. A visit's appointment_uid is the appointment_id of get_appointment.

Input parameters:

- `client_id` (integer, required): From list_clients or find_client.
- `visits_limit` (integer): Visits to return. Default: 20.

### `get_report` (~265 tokens)

Get report

Numbers from Stats & Reports for a day, week, month or year, as JSON.

Returns one Stats & Reports category for a period: dashboard gives the totals for appointments, revenue and clients with the change against the previous period; any other category gives its highlight tables and the list of its reports. Pass report with a key from that list for the full report. Booksy counts one day, one Monday-to-Sunday week, one calendar month or one calendar year, so from and to must be such a period. Amounts come formatted in the business's currency. Booksy Biz Lite has the dashboard, revenue, appointments and clients; cash_flow, inventory, staff_members and marketing need Booksy Biz Pro.

Input parameters:

- `category` (string, required): dashboard (totals), appointments, clients, revenue, cash_flow, staff_members, marketing, tips or inventory.
- `from` (string, required): First day, inclusive.
- `report` (string): Report key from `reports` of the category (e.g. appointments_summary) for its full tables.
- `staff_id` (integer): Staff member, only for the report performance_per_staffer.
- `to` (string, required): Last day, inclusive: the same day, a Monday-to-Sunday week, a calendar month or year.

### `get_settings` (~77 tokens)

Get settings

Text message allowance and usage, client message channels and your notification settings.

Reads the settings an agent needs before messaging clients: whether SMS and email to clients are on, the free and paid text allowance with this period's usage and price per text part, and which booking events notify you by email or push. Changes stay in the Booksy app.

### `list_appointments` (~130 tokens)

List appointments

Appointments in a date range with client, service, staff, time and status.

Lists the Booksy calendar between two days (31 at most), in start order, including unconfirmed requests. Times carry the business's time zone. A walk-in has an empty client. An appointment with several services is one row listing them all; get_appointment returns prices and notes.

Input parameters:

- `from` (string, required): First day, inclusive.
- `staff_id` (string): Only one staff member, from list_staff.
- `to` (string, required): Last day, inclusive. At most 31 days after from.

### `list_clients` (~186 tokens)

List clients

Clients with contact details, visit counts and last visit, plus Booksy's client groups.

Reads the Clients list of the business, A to Z: name, email, phone, private note, tags, visits, no-shows, cancellations, revenue and the last visit. Search by name, email or phone, or keep only clients who have not visited for a number of days (filtered on each page). `groups` gives Booksy's smart groups (new, most loyal, slipping away, prospects, upcoming birthdays ..) with their counts.

Input parameters:

- `cursor` (string): next_cursor from the previous call.
- `limit` (integer): Page size. Default: 50.
- `not_visited_days` (integer): Only clients whose last visit is older than this many days (or who never visited).
- `query` (string): Name, email or phone to search for.

### `list_message_blasts` (~81 tokens)

List Message Blasts

Message Blast templates (automated and one-time) and the blasts scheduled to go out.

Reads Promotion > Message Blasts: every automated template with its trigger and whether it is on, every one-time template, and the blasts scheduled for later. send_message_blast sends a one-time message; estimate_message_blast counts recipients and SMS cost first.

### `list_notifications` (~101 tokens)

List notifications

Notifications from the panel's bell: new bookings, changes, cancellations, reviews.

Reads the notifications Booksy shows under the bell in the panel, newest first. Client chat is not included. Reading does not mark them seen.

Input parameters:

- `page` (integer): Page, from 1. Default: 1.
- `per_page` (integer): Per page. Default: 20.
- `unread_only` (boolean): Only the new ones. Default: false.

### `list_reviews` (~129 tokens)

List reviews

Client reviews of your business with rating, text, services, staff and your reply.

Reads the reviews on your Booksy profile, newest first by default: star rating, text, the client's name as Booksy shows it, services, staff, visit date and your reply if you wrote one. Also returns the average rating and the count per star. Reply with reply_to_review.

Input parameters:

- `page` (integer): Page, from 1. Default: 1.
- `per_page` (integer): Reviews per page. Default: 20.
- `sort` (string): Order. Default: newest.

### `list_services` (~97 tokens)

List services

Your service menu with category, variants, duration, price and the staff who offer each.

Reads the services of the business: name, category, description, whether clients can book it online, and its variants with duration in minutes, price (number and as shown, with currency), price type and the staff IDs who perform it. create_appointment and find_open_slots take service_id (its first variant) or a variant_id for another variant.

### `list_staff` (~108 tokens)

List staff

Staff members with their working hours for a week and the services they offer.

Reads the staff of the business: name, position, email, phone, access level, whether clients see them, the services each one performs, and working hours for each day of one week (Monday to Sunday, from Shifts, time off included). Use staff_id in other tools.

Input parameters:

- `week_start_date` (string): Any day of the week to show hours for, YYYY-MM-DD. Default: this week.

### `list_time_off` (~120 tokens)

List time off

Staff time off and blocked hours in a date range.

Lists time off from Shifts (kind time_off: dates, hours only when it is part of a day) and blocked hours in the calendar (kind block: date-times) between two days, 31 at most. time_off_id goes to remove_time_off.

Input parameters:

- `from` (string, required): First day, inclusive.
- `staff_id` (string): Only one staff member, from list_staff.
- `to` (string, required): Last day, inclusive. At most 31 days after from.

### `remove_time_off` (~86 tokens)

Remove time off

Remove time off or a blocked period so the time can be booked again.

Deletes one time off (off-…) or one calendar block (block-…). It reaches no client.

Input parameters:

- `staff_id` (string, required): Staff ID the time off belongs to.
- `time_off_id` (string, required): ID from add_time_off or list_time_off (off-… or block-…).

### `reply_to_review` (~86 tokens)

Reply to review

Post or change your public reply to a client's review.

Writes your reply under one review on your Booksy profile, the way the Reviews page does. A second call replaces the reply. Everyone who sees your profile sees it and the reviewer is told.

Input parameters:

- `reply` (string, required): Reply text, public on your profile.
- `review_id` (integer, required): Review ID from list_reviews.

### `reschedule_appointment` (~169 tokens)

Reschedule appointment

Move an appointment to a new start time, and optionally to another staff member.

Moves every service of the appointment by the same amount, so the first one starts at start. Booksy's dry run checks the new slot first and a busy one is refused. The client hears about it only with notify_client. Booksy refuses appointments it no longer lets you change (can in get_appointment).

Input parameters:

- `appointment_id` (string, required): Appointment ID from list_appointments.
- `notify_client` (boolean): Tell the client about the new time through Booksy. Default: false.
- `staff_id` (string): New staff member from list_staff. Default: unchanged.
- `start` (string, required): New start, ISO 8601. Without a time zone it is the business's local time.

### `send_message_blast` (~194 tokens)

Send Message Blast

Send one message to chosen clients by email, SMS or push notification.

Sends one Message Blast now to the clients you list, by email, SMS or a push notification to the Booksy Client App, as Promotion > Message Blasts > Create your own message does. Where the law asks for marketing consent (EU), only the listed clients who agreed get it; the call fails when none can. SMS comes from an automated number, so clients cannot reply, and uses the plan's text allowance. Run estimate_message_blast first to see the count and cost. Needs a paid Booksy plan: on the free trial Booksy refuses one-time messages.

Input parameters:

- `channel` (string, required): email, sms or push.
- `client_ids` (array, required): Recipients from list_clients.
- `message` (string, required): Message text.
- `subject` (string): Email subject and push title. Default: the message's start.

### `update_client` (~152 tokens)

Update client

Change a client card's name, phone, email, birthday or private note.

Changes only the fields given and leaves the rest of the card as it is. The note replaces the card's private note; add_client_note adds a line instead. The client is not told.

Input parameters:

- `birthday` (string): YYYY-MM-DD.
- `client_id` (integer, required): From list_clients or find_client.
- `email` (string): Email address; empty string removes it.
- `name` (string): Full name; the last word is the last name.
- `note` (string): Private note, replaces the old one; add_client_note appends.
- `phone` (string): Mobile phone; empty string removes it.

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/dev-cotlet-booksy/booksy-api-mcp#diagnostics

## Score history

- 2026-10-24: 65

## Common questions

### What is the Booksy by Cotlet MCP server?

Booksy by Cotlet is an MCP server listed in the public MCP registry as dev.cotlet/booksy. Bookings, clients, reviews and reports for beauty businesses. This page covers its PyPI package (booksy-api-mcp).

### Is the Booksy by Cotlet MCP server safe to use?

Booksy by Cotlet scores 65 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 24 October 2026. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the Booksy by Cotlet MCP server expose?

Booksy by Cotlet exposes 28 tools: add_client, add_client_note, add_time_off, cancel_appointment, create_appointment, and 23 more. Their descriptions and schemas cost roughly 3,690 tokens of context every time the server is loaded.

### Is the Booksy by Cotlet MCP server still maintained?

Booksy by Cotlet is still listed as active in the MCP registry. We last reached this channel on 24 October 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the Booksy by Cotlet MCP server under?

Booksy by Cotlet declares the PolyForm-Noncommercial-1.0.0 licence, which is not on the OSI-approved list. Read the terms before using it at work, and note this covers the source only, not the cost of any service it calls.

## Links

- PyPI project: https://pypi.org/project/booksy-api-mcp/
- Socket report: https://socket.dev/pypi/package/booksy-api-mcp
- Repository: https://github.com/cotletdev/booksy-api-mcp-server
- Website: https://cotlet.dev/integrations/booksy-api-mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/dev-cotlet-booksy/booksy-api-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/dev-cotlet-booksy/booksy-api-mcp.json
- HTML version of this page: https://verifymcp.io/servers/dev-cotlet-booksy/booksy-api-mcp