# YouCanBookMe MCP Server

[![CI](https://github.com/OfirOhan/youcanbookme-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/OfirOhan/youcanbookme-mcp/actions/workflows/ci.yml)
![MCP](https://img.shields.io/badge/MCP-compatible-blue)
![License: MIT](https://img.shields.io/badge/license-MIT-green)

A [Model Context Protocol](https://modelcontextprotocol.io) server for **[YouCanBookMe](https://youcanbook.me)**. It lets Claude, Cursor, ChatGPT and other AI agents find open times on your booking pages, book, reschedule and cancel bookings, and answer questions like "how many no-shows did we have last month?".

> **Unofficial.** This is a community project and is not affiliated with YouCanBookMe or Capacity. It was built from YouCanBookMe's public API docs.

## What you can ask your agent

- "What's on my **Demo** booking page for the next 3 days, and who are the bookers?"
- "Find two morning slots on **acme-demo** next week in New York time and draft an email offering them to Sam."
- "Book Dana Levi (dana@acme.com, London) into the first Tuesday slot."
- "Move booking ref QNBZAQPTAITT to Thursday at 2pm."
- "How many bookings, cancellations and no-shows did each booking page get in September?"
- "Find every booking made by someone at acme.com this quarter."

## Tools

| Tool | What it does | Writes? |
|---|---|---|
| `list_booking_pages` | All booking pages (profiles) with id, title and subdomain | No |
| `get_booking_page` | One page's settings (choose fields with dot notation) | No |
| `list_upcoming_bookings` | Upcoming bookings for the next N days, with booker name and email | No |
| `search_bookings` | Bookings in a time range by status, page, or text (name, email, ref) | No |
| `get_booking` | One booking with times, status and form answers | No |
| `booking_report` | Counts by status (finished, cancelled, noShow...) and by page for a period | No |
| `find_available_times` | Open slots, **grouped by day with local times**, returns an `intentId` | Starts an intent |
| `book_time` | Book a slot found above (creates a real booking) | Yes |
| `reschedule_booking` | Move a booking to a new start time | Yes |
| `cancel_booking` | Cancel as the calendar owner (removes the calendar event) | **Destructive** |
| `delete_booking` | Permanently delete a booking record | **Destructive** |

YouCanBookMe's booking API is built on *booking intents* (create intent, set selections, read availability, confirm). This server hides that flow behind two tools. `find_available_times` returns readable slots plus an `intentId`, and `book_time` fills in the form and confirms. Availability comes back as unix-millisecond timestamps, so the server converts it to ISO times and local clock times an LLM can reason about. Write tools carry MCP annotations, so clients can ask before running them.

## Setup

1. In YouCanBookMe, open **Account > Password & Security** ([link](https://app.youcanbook.me/#/account/security)) and copy your **Account ID** and **API key** (starts with `ak_`). On a Team plan, use the Organization Owner's key.
2. Build it:

```bash
git clone https://github.com/OfirOhan/youcanbookme-mcp.git
cd youcanbookme-mcp && npm install && npm run build
```

### Claude Desktop

Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "youcanbookme": {
      "command": "node",
      "args": ["/absolute/path/to/youcanbookme-mcp/dist/index.js"],
      "env": { "YCBM_ACCOUNT_ID": "your-account-id", "YCBM_API_KEY": "ak_..." }
    }
  }
}
```

### Claude Code / Cursor / other MCP clients

```bash
claude mcp add youcanbookme -e YCBM_ACCOUNT_ID=... -e YCBM_API_KEY=ak_... -- node /path/to/youcanbookme-mcp/dist/index.js
```

For Cursor and other clients, use the same command with the variables in the environment.

| Variable | Default | Notes |
|---|---|---|
| `YCBM_ACCOUNT_ID` | (required) | Your account ID (HTTP basic auth username) |
| `YCBM_API_KEY` | (required) | Your API key (HTTP basic auth password) |
| `YCBM_BASE_URL` | `https://api.youcanbook.me` | Override for testing |

## Development

```bash
npm install
npm test   # builds, runs unit tests and an end-to-end MCP stdio test against a fake YouCanBookMe API
```

The tests run on Node 20, 22 and 24 in CI.

## Author

Built by [Ofir Ohana](https://github.com/OfirOhan), an AI agents engineer. Issues and PRs are welcome.

## License

MIT