# booking_chest — Cal.com MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server for [Cal.com](https://cal.com) open-source scheduling. Exposes **~70 MCP tools** across 10 resource modules — create schedules, manage event types, book meetings, integrate calendars, configure webhooks, and manage teams — all controllable directly from Claude or any MCP-compatible client.

## Features

- **~70 tools** covering the Cal.com API v2
- Clean two-layer architecture: pure `calcom_client/` package + thin MCP wrapper
- Static Bearer token auth (no refresh needed)
- Typed exception hierarchy (`APIError`, `NotFoundError`, `ValidationError`, `AuthenticationError`)
- API quirks baked in (correct parameter names, required fields, response envelope unwrapping)

## Resource Modules (10)

| Module | Tools | Description |
|--------|-------|-------------|
| `me` | 2 | Profile get/update |
| `timezones` | 1 | List all 7,072 city/timezone entries |
| `api_keys` | 1 | Rotate API key (warning: invalidates immediately) |
| `schedules` | 5 | Availability schedule CRUD |
| `event_types` | 9 | Event type CRUD + per-type webhooks + private links (Enterprise) |
| `slots` | 3 | Available slots, reserve, delete reservation |
| `bookings` | 6 | List, get, create, cancel, reschedule, mark no-show |
| `calendars` | 9 | Connect, busy times, destination, selected, ICS feeds |
| `webhooks` | 5 | User-level webhook CRUD (21 trigger types) |
| `teams` | 19 | Team CRUD + memberships + event types + event-type webhooks + invite |

## Installation

```bash
git clone https://github.com/dsddet/booking_chest
cd booking_chest
pip install -e ".[mcp]"
```

Or with `uv` (recommended):

```bash
uv pip install -e ".[mcp]"
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CALCOM_API_KEY` | **Yes** | Cal.com API key (starts with `cal_`) |
| `CALCOM_BASE_URL` | No | Cal.com instance URL (default: `https://api.cal.com`) |

Create a `.env` file:

```bash
CALCOM_API_KEY=cal_your_api_key_here
CALCOM_BASE_URL=https://api.cal.com
```

For self-hosted Cal.com instances, set `CALCOM_BASE_URL` to your instance URL (e.g., `http://192.168.0.214`).

### Getting an API Key

1. Log into Cal.com Settings → Developer → API Keys
2. Click "Generate API Key"
3. Copy the key (starts with `cal_`) — it cannot be retrieved later

## Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "booking_chest": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/booking_chest",
        "run", "--extra", "mcp", "mcp_server.py"
      ],
      "env": {
        "CALCOM_API_KEY": "cal_your_api_key_here",
        "CALCOM_BASE_URL": "https://api.cal.com"
      }
    }
  }
}
```

Replace `/path/to/booking_chest` with the absolute path to your cloned directory.

## Usage Examples

Once connected, you can ask Claude:

- *"Create a 30-minute consultation event type"*
- *"What slots are available this week for event type 1?"*
- *"Book a meeting with john@example.com on March 5th at 2pm Eastern"*
- *"List all my upcoming bookings"*
- *"Cancel booking 42 — attendee has a conflict"*
- *"Connect my Google Calendar and set it as the destination"*
- *"Create a webhook to notify Zapier when bookings are created or cancelled"*
- *"List all team members and their roles"*

## Architecture

```
calcom_client/          # Pure API client (no MCP dependency)
├── http.py             # httpx + Bearer token auth + response envelope unwrap
├── exceptions.py       # APIError, NotFoundError, ValidationError, AuthenticationError
├── me.py               # Profile get/update
├── timezones.py        # List all timezones
├── api_keys.py         # API key rotation
├── schedules.py        # Availability schedule CRUD
├── event_types.py      # Event type CRUD + webhooks + private links
├── slots.py            # Available slots, reserve, delete
├── bookings.py         # Booking CRUD (cancel, reschedule, no-show)
├── calendars.py        # Calendar integrations (Google, Office 365, Apple)
├── webhooks.py         # User-level webhook CRUD
├── teams.py            # Team CRUD + memberships + event types + invite
└── __init__.py         # CalcomClient facade composing all modules
mcp_server.py           # ~70 @mcp.tool() functions
```

## Cal.com API Quirks (baked into client code)

- **API version**: Use `cal-api-version: 2024-06-14` (broadest support — `2024-08-13` misses some endpoints)
- **Response envelope**: All responses wrapped in `{"status": "success", "data": ...}` — unwrapped automatically
- **Slots params**: Use `start`/`end` (NOT `startTime`/`endTime` — those cause 400 errors)
- **Webhook triggers**: Use `triggers` field (NOT `eventTriggers` — old doc error)
- **Calendar connect**: Use `google`, `office365`, `apple` (NOT `google-calendar`, `office365calendar`)
- **`calendarsToLoad` is REQUIRED** for busy-times endpoint (400 error without it)
- **`isDefault` is REQUIRED** when creating schedules (400 error without it)
- **`slotId` is REQUIRED** when reserving slots
- **API key refresh**: Old key invalidated immediately — update env before next request
- **Team creation needs Stripe** — use existing teams or configure Stripe billing
- **metadata PATCH**: Returns null in response but IS saved (verify via team memberships)
- **No team-level webhooks** — webhooks are always scoped to specific event types

## License

MIT