# Booksy by Cotlet

A self-hosted MCP server and REST API for the Booksy Biz panel: calendar, clients, services, reviews and reports, driven from your agent.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 2
- Author: cotletdev
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cotletdev/booksy-api-mcp-server
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/booksy-by-cotlet

## What it does

You run this on your own machine. Python does the work, and it borrows the Booksy session already open in your Google Chrome. Booksy offers business owners no self-serve API, so `booksy-mcp connect` talks to the browser over the Chrome DevTools Protocol, pulls the session out of the `web-gateway.booksy.com` frame's localStorage along with cookies and the panel's country, and writes it to `~/.config/booksy-api-mcp/session.json`. Your password stays out of it.

Tool calls then hit the same endpoint the web panel uses: `<country>.booksy.com/core/v2`. Requests go out through `curl_cffi`, which mimics Chrome's TLS fingerprint, so no headless browser is involved. There are 28 tools in total — calendar, open slots, time off, clients, services and staff, reviews, Message Blasts, Stats & Reports. A REST API also listens on `http://127.0.0.1:8787/api/v1/booksy` with OpenAPI docs at `/docs`, and Python calls look like `call("list_appointments", ...)`.

Python 3.11 or newer is required, plus Chrome 144 or newer with a signed-in Booksy Biz session. Some reports, Staff Members among them, need Booksy Biz Pro, and one-time Message Blasts only go out on a paid plan — the free trial won't send them. The PolyForm Noncommercial license covers noncommercial use only; teams and always-on setups should look at the hosted version on cotlet.dev.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Remote server: `https://cotlet.dev/mcp/v1/booksy/connect`

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http booksy https://cotlet.dev/mcp/v1/booksy/connect
```

2. **Platform CLI**
```bash
claude mcp add booksy-by-cotlet -- uvx booksy-api-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from booksy-api-mcp <command>

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add booksy-by-cotlet --url https://cotlet.dev/mcp/v1/booksy/connect
```

2. **Platform CLI**
```bash
codex mcp add booksy-by-cotlet -- uvx booksy-api-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from booksy-api-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "booksy-by-cotlet": {
            "url": "https://cotlet.dev/mcp/v1/booksy/connect"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "booksy-by-cotlet": {
            "command": "uvx",
            "args": [
                "booksy-api-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from booksy-api-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "booksy-by-cotlet": {
            "type": "http",
            "url": "https://cotlet.dev/mcp/v1/booksy/connect"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "booksy-by-cotlet": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "booksy-api-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from booksy-api-mcp <command>

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http booksy-by-cotlet https://cotlet.dev/mcp/v1/booksy/connect
```

2. **Platform CLI**
```bash
gemini mcp add booksy-by-cotlet uvx booksy-api-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from booksy-api-mcp <command>

## When to use it
- pull a day's appointment schedule out of the Booksy Biz panel
- check open slots and staff time off
- list clients and services from the account
- read reviews and salon statistics
- send a one-time Message Blast to clients

## Example prompts
- Show me all appointments for 2026-10-27 from Booksy
- List the services in my Booksy Biz panel
- What open slots do my staff have tomorrow?

## Similar
- [Substack by Cotlet](https://affpapa.org/en/nevibecode/mcp/substack-by-cotlet.md) — MCP server · ★ 3
- [extension-http-outcalls](https://affpapa.org/en/nevibecode/skills/extension-http-outcalls.md) — skill · 28100 installs
- [agentmemory-rest-api](https://affpapa.org/en/nevibecode/skills/agentmemory-rest-api.md) — skill · 10800 installs
- [agentmemory-architecture](https://affpapa.org/en/nevibecode/skills/agentmemory-architecture.md) — skill · 10700 installs
- [api-integration-surface-strategy](https://affpapa.org/en/nevibecode/skills/api-integration-surface-strategy.md) — skill · 8000 installs
- [wp-rest-api](https://affpapa.org/en/nevibecode/skills/wp-rest-api.md) — skill · 5900 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md