@calcom/mcp-server

A Model Context Protocol (MCP) server that wraps the Cal.com Platform API v2. Connect it to Claude Desktop, Cursor, or any MCP-compatible client to manage bookings, event types, schedules, and more through natural language.

Features

• 54 tools covering Bookings, Event Types, Schedules, Availability, Calendars, Conferencing, Booking Routing Trace, Routing Forms, Organizations, Teams, and User Profile (each with MCP tool annotations: title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
• Dual transport — stdio for local dev tooling, StreamableHTTP for remote/production
• Dual auth — API key for stdio (local dev), OAuth 2.1 Authorization Code + PKCE for HTTP (production)
• Per-user token storage — encrypted at rest with AES-256-GCM in SQLite
• Structured error handling with clean MCP error responses
• Zod-validated inputs for every tool

Transport Modes

The server supports two transport modes selected via the MCP_TRANSPORT environment variable.

stdio (default) — Local Developer Tooling

Best for: Claude Desktop, Cursor, VS Code, and any MCP client that spawns the server as a subprocess.

# Start via stdio (default)
bun --filter @calcom/mcp-server start

# Or explicitly
MCP_TRANSPORT=stdio node apps/mcp-server/dist/index.js

The MCP client communicates over stdin/stdout. No HTTP server is started.

http — Remote / Production

Best for: Hosted deployments, shared services, remote MCP clients that connect over the network.

# Generate an encryption key
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Start HTTP server with OAuth 2.1
MCP_TRANSPORT=http \
  CAL_OAUTH_CLIENT_ID=your_client_id \
  CAL_OAUTH_CLIENT_SECRET=your_client_secret \
  TOKEN_ENCRYPTION_KEY=<64-hex-chars> \
  MCP_SERVER_URL=https://your-host.com \
  PORT=3100 \
  node apps/mcp-server/dist/index.js

This starts a StreamableHTTP server with OAuth 2.1 authentication:

MCP endpoints (require Authorization: Bearer <token>):

• POST /mcp — JSON-RPC over Streamable HTTP (creates a new session on first request)
• GET /mcp — SSE stream for server-initiated messages (requires mcp-session-id header)
• DELETE /mcp — Terminate a session (requires mcp-session-id header)

OAuth 2.1 endpoints:

• GET /.well-known/oauth-authorization-server — Authorization server metadata (RFC 8414)
• GET /.well-known/oauth-protected-resource — Protected resource metadata (RFC 9728)
• POST /oauth/register — Dynamic client registration (RFC 7591)
• GET /oauth/authorize — Start authorization flow (redirects to Cal.com)
• GET /oauth/callback — Cal.com OAuth callback (exchanges code for tokens)
• POST /oauth/token — Token exchange (authorization_code or refresh_token grant)
• POST /oauth/revoke — Token revocation (RFC 7009)

Other:

• GET /health — Health check (returns { "status": "ok", "sessions": <count> })
• GET /.well-known/openai-apps-challenge — OpenAI Apps domain verification token (plain text). Returns 404 unless OPENAI_APPS_CHALLENGE_TOKEN is set.

Each HTTP session gets its own McpServer instance with a unique session ID, so multiple clients can connect concurrently.

Connecting to MCP Clients

Claude Desktop (stdio)

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "calcom": {
      "command": "node",
      "args": ["<path-to-repo>/apps/mcp-server/dist/index.js"],
      "env": {
        "CAL_API_KEY": "cal_live_xxxx"
      }
    }
  }
}

Cursor / VS Code (stdio)

Point your MCP client to apps/mcp-server/dist/index.js with the required environment variables.

Remote MCP Clients (http)

Start the server with MCP_TRANSPORT=http and point your client to http://<host>:3100/mcp.

Authentication

stdio mode — API Key

Every request to Cal.com includes:

• Authorization: Bearer <CAL_API_KEY>
• cal-api-version: 2024-08-13

HTTP mode — OAuth 2.1 Authorization Code + PKCE

The HTTP server implements a full OAuth 2.1 Authorization Server. MCP clients connect through a standard OAuth flow:

1. Client registers → POST /oauth/register with redirect_uris → receives client_id
2. Client starts auth → GET /oauth/authorize with client_id, redirect_uri, code_challenge (S256), state
3. Server redirects to Cal.com → user authorizes on Cal.com
4. Cal.com redirects back → GET /oauth/callback with code + state
5. Server exchanges code → calls Cal.com token endpoint, stores encrypted Cal.com tokens in SQLite
6. Server redirects to client → with an authorization code + original state
7. Client exchanges code → POST /oauth/token with code, code_verifier, redirect_uri → receives access_token + refresh_token
8. Client uses token → POST /mcp with Authorization: Bearer <access_token>

The server acts as an intermediary: it issues its own access tokens to MCP clients, and each token maps to encrypted Cal.com credentials stored in SQLite. When Cal.com tokens expire, the server auto-refreshes them transparently.

Security:

• All Cal.com tokens are encrypted at rest with AES-256-GCM (via TOKEN_ENCRYPTION_KEY)
• PKCE (S256) is required on both legs (client→server and server→Cal.com)
• Auth codes are single-use
• Expired tokens are cleaned up automatically every 5 minutes
• In-process rate limiting on all OAuth endpoints (token bucket per IP, configurable via RATE_LIMIT_WINDOW_MS / RATE_LIMIT_MAX)
• Redirect URIs registered via dynamic client registration are constrained: loopback (localhost / 127.0.0.0/8 / ::1) is always allowed, cleartext http to non-loopback hosts is always rejected, and non-loopback https hosts can be restricted to a vetted allowlist via ALLOWED_REDIRECT_HOSTS (recommended in production to limit the open-DCR phishing surface)

Tools (54)

Each tool exposes MCP tool annotations — a human-readable title plus behaviour hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so MCP clients can render them appropriately and apply safety policies.

openWorldHint is true for every tool — they all call the external Cal.com API.

User Profile (2)

Event Types (6)

Bookings (10)

Schedules (6)

Availability / Slots (1)

Calendars (2)

Conferencing (1)

Booking Routing Trace (1)

Routing Forms (1)

Organizations: Attributes (7)

Organizations: Bookings (2)

Organizations: Memberships (5)

Organizations: Teams (2)

Organizations: Routing Forms (2)

Teams: Memberships (6)

API Version Notes

• Default API version: 2024-08-13
• /v2/slots endpoint uses: 2024-09-04 (automatically applied)

Setup

Prerequisites

• Node.js >= 22
• Bun (for workspace install)
• A Cal.com API key (get one here)

Install & Build

# From the repo root
bun install
bun --filter @calcom/mcp-server build

Configure

Copy the example env file and fill in your credentials:

cp apps/mcp-server/.env.example apps/mcp-server/.env

Common:

stdio mode (local dev):

HTTP mode (remote/production with OAuth 2.1):