booking_chest — Cal.com MCP Server

A Model Context Protocol server for 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

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

Or with uv (recommended):

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:

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

{
  "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