> ## Documentation Index
> Fetch the complete documentation index at: https://cal.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect AI clients to Cal.com scheduling through the Model Context Protocol using the hosted server at mcp.cal.com or a local instance.

The Cal.com MCP server wraps the [Cal.com API v2](https://cal.com/docs/api-reference/v2/introduction.md) in the [Model Context Protocol](https://modelcontextprotocol.io/introduction), letting you manage bookings, event types, schedules, and more through natural language in any MCP-compatible client.

## Hosted server (mcp.cal.com)

The fastest way to get started is to connect your MCP client directly to `mcp.cal.com`. The hosted server uses Streamable HTTP transport with OAuth 2.1 authentication — your client handles the authorization flow automatically.

### Connect your client

Point your MCP client to the hosted server URL:

```
https://mcp.cal.com/mcp
```

When you first connect, your client walks you through an OAuth authorization flow where you grant the server access to your Cal.com account. No API key is needed. Any MCP client can connect: clients register dynamically via `POST /oauth/register` or identify themselves with a Client ID Metadata Document (an `https` client\_id URL). Before the Cal.com sign-in, you see a consent page naming the client and the host you'll be sent back to.

> [!NOTE]
>
> The consent screen also asks for [team scopes](https://cal.com/docs/api-reference/v2/oauth.md#team-scopes) to create, edit and delete team event types and to view and manage team memberships, so your AI client can set up team event types and add people to teams. It also asks for the [organization profile scopes](https://cal.com/docs/api-reference/v2/oauth.md#organization-scopes), so an organization admin's AI client can list, create, edit and delete the organization's teams. Cal.com still checks your role and permissions in the team on every call. It also asks to view, add, rename and remove your personal contacts (`CONTACT_READ`, `CONTACT_WRITE`). If you connected before these scopes were added, disconnect and reconnect the server to grant them.

> [tab] Claude Desktop
>
> Add the following to your `claude_desktop_config.json`:
>
> * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
> * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "calcom": {
>       "url": "https://mcp.cal.com/mcp"
>     }
>   }
> }
> ```

> [tab] Cursor
>
> Open **Settings → MCP** and add a new server with the URL `https://mcp.cal.com/mcp`, or add it to your `.cursor/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "calcom": {
>       "url": "https://mcp.cal.com/mcp"
>     }
>   }
> }
> ```

> [tab] VS Code
>
> Add the server to your VS Code MCP settings:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "calcom": {
>       "url": "https://mcp.cal.com/mcp"
>     }
>   }
> }
> ```

> [tab] fx
>
> Add the following to your `~/.fx/mcp.json`:
>
> ```json theme={null}
> {
>   "mcp": {
>     "calcom": {
>       "type": "http",
>       "url": "https://mcp.cal.com/mcp"
>     }
>   }
> }
> ```
>
> Then run `/mcp auth calcom --open` in fx to authorize. See the
> [fx MCP docs](https://fx.sh/docs/capabilities/mcp) for transports,
> authentication options, and tool discovery.

> [tab] Grok
>
> Grok connects through the Cal.com bot instead of a JSON configuration. In [Settings → Developer → MCP](https://app.cal.com/settings/developer/mcp), select **Grok Bot** under **Client setup**, then scan the QR code or click **Add Bot** to open the [Cal.com bot](https://x.ai/bot/8xUXbFMraN0ysh2F624gJ) in Grok.
>
> ![The MCP page in Cal.com developer settings with Grok Bot selected under Client setup, showing a QR code and an Add Bot button](https://mintcdn.com/calcom/7S2zJ6852Lk_3hdb/images/mcp-server/grok-bot-client-setup.png?fit=max\&auto=format\&n=7S2zJ6852Lk_3hdb\&q=85\&s=94a07fa0150409121be511a1358a5a0f)

## Self-hosted server (stdio)

If you prefer to run the server locally, you can use stdio transport with an API key. This is useful for development or when you want full control over the server.

### Prerequisites

* Node.js >= 18
* A Cal.com API key — generate one in [Settings → Developer → API Keys](https://app.cal.com/settings/developer/api-keys)

### Connect your client

Add the following to your MCP client's configuration:

```json theme={null}
{
  "mcpServers": {
    "calcom": {
      "command": "npx",
      "args": ["@calcom/cal-mcp@latest"],
      "env": {
        "CAL_API_KEY": "cal_live_xxxx"
      }
    }
  }
}
```

Replace `cal_live_xxxx` with your actual API key.

> [!WARNING]
>
> Never share or commit your API key. If exposed, rotate it immediately in your [Cal.com settings](https://app.cal.com/settings/developer/api-keys).

## Toolsets

You can restrict which tools the server registers for a session by appending a `toolsets` query parameter to the server URL:

```
https://mcp.cal.com/mcp?toolsets=bookings,availability
```

Valid toolsets: `profile`, `event-types`, `events`, `bookings`, `availability`, `schedules`, `calendars`, `contacts`, `teams`, `organizations`, `routing-forms`, `catalog` (the `find_api_operation` / `describe_api_operation` / `call_api_operation` meta-tools). Unknown names are rejected with `400 invalid_request`. Omitting the parameter registers every tool; the local tools `get_app_link` and `search_docs` are always registered regardless of the selection. For a self-hosted stdio server, set `MCP_TOOLSETS` instead.

## Interactive views (MCP Apps)

In clients that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview), `get_availability` and `get_bookings` also show an interactive view in the chat, so you can pick times and manage bookings by clicking instead of typing:

* **Slot picker** (`get_availability`): open times grouped by day. Use the arrows to move to earlier or later dates, click a time, enter the attendee's name and email, and click **Book**. When the assistant is finding a new time for an existing booking, clicking a time offers **Move booking here** instead.
* **Bookings** (`get_bookings`): one card per booking with its time and attendees. Upcoming bookings have **Join** (when the booking has a meeting link), **Reschedule**, which shows open times for the next week to pick from, and **Cancel**, which asks you to confirm in the card first.

Times are shown in the timezone your client reports, and the views follow its light or dark theme. Actions run through the same `create_booking`, `reschedule_booking` and `cancel_booking` tools on your existing connection, and the assistant is told what you did.

> [!NOTE]
>
> The views are available only when both the `bookings` and `availability` toolsets are enabled, which is the default when you don't pass `toolsets`. Clients without MCP Apps support get the same text results as before.

## Available tools

The MCP server exposes 76 tools organized by category:

### App links

| Tool | Description |
| - | - |
| `get_app_link` | Build a URL that opens a booking, event type, schedule, team, routing form or settings page in the Cal.com web app |

### Documentation

| Tool | Description |
| - | - |
| `search_docs` | Search the Cal.com product documentation; returns ranked pages with an excerpt of the top result |

### User profile

| Tool | Description |
| - | - |
| `get_me` | Get your authenticated user profile |
| `update_me` | Update your user profile |

### Event types

| Tool | Description |
| - | - |
| `get_event_types` | List all event types |
| `get_event_type` | Get a specific event type by ID |
| `create_event_type` | Create a new event type |
| `update_event_type` | Update an event type |
| `delete_event_type` | Delete an event type |
| `duplicate_event_type` | Duplicate an organization team event type into the same team or another team of the organization |
| `get_event_type_settings` | Get the settings of an event type |
| `get_event_type_history` | Get the change history of an event type |
| `get_scheduling_config` | Get the scheduling configuration of an event type |
| `get_crm_sync_errors` | Get CRM sync errors for an event type |

### Events

Cal Events are fixed-date RSVP pages served at `cal.com/{slug}` — not event types and not calendar events. Both tools need the `EVENT_READ` OAuth scope.

| Tool | Description |
| - | - |
| `get_events` | List the Events you own or co-host, newest first; supports `limit` (max 250) and `cursor` pagination and a `slug` filter |
| `get_event` | Get one Event by uuid |

### Bookings

| Tool | Description |
| - | - |
| `get_bookings` | List bookings with optional filters |
| `get_booking` | Get a specific booking by UID |
| `create_booking` | Create a new booking |
| `reschedule_booking` | Reschedule a booking |
| `cancel_booking` | Cancel a booking |
| `confirm_booking` | Confirm a pending booking |
| `mark_booking_absent` | Mark a booking absence |
| `get_booking_attendees` | Get all attendees for a booking |
| `add_booking_attendee` | Add an attendee to a booking |
| `get_booking_attendee` | Get a specific attendee |
| `get_booking_routing_trace` | Get the routing trace for a booking |
| `get_org_team_bookings` | Get bookings for an organization team |
| `get_org_user_bookings` | Get bookings for an organization user |

### Schedules

| Tool | Description |
| - | - |
| `get_schedules` | List all schedules |
| `get_schedule` | Get a specific schedule by ID |
| `create_schedule` | Create a new schedule |
| `update_schedule` | Update a schedule |
| `delete_schedule` | Delete a schedule |
| `get_default_schedule` | Get your default schedule |

### Availability & calendars

| Tool | Description |
| - | - |
| `get_availability` | Get available time slots |
| `get_busy_times` | Get busy times from calendars |
| `get_connected_calendars` | List connected calendars |
| `get_conferencing_apps` | List conferencing applications |

### Contacts

Your personal contacts from your Contacts page — never team or organization members. The list needs the `CONTACT_READ` OAuth scope and the writes `CONTACT_WRITE`.

| Tool | Description |
| - | - |
| `list_contacts` | List your contacts, 50 per page, with whether each is on Cal and can join a group meeting |
| `add_contact` | Add a contact by email, with an optional name |
| `update_contact` | Update a contact's name; a contact on Cal can't have its name changed |
| `remove_contact` | Remove a contact and its tags |

### Teams & memberships

| Tool | Description |
| - | - |
| `get_my_teams` | Get the teams you belong to |
| `get_org_teams` | Get organization teams |
| `create_team_invite` | Invite someone to a team |
| `create_team_membership` | Create a team membership |
| `get_team_memberships` | Get all team memberships |
| `get_team_membership` | Get a team membership |
| `update_team_membership` | Update a team membership |
| `delete_team_membership` | Delete a team membership |

### Organizations

| Tool | Description |
| - | - |
| `get_org_memberships` | Get all organization memberships |
| `create_org_membership` | Create an organization membership |
| `get_org_membership` | Get an organization membership |
| `update_org_membership` | Update an organization membership |
| `delete_org_membership` | Delete an organization membership |
| `get_org_attributes` | Get organization attributes |
| `get_org_attribute` | Get an organization attribute |
| `get_attribute_options` | Get options for an attribute |
| `get_user_attributes` | Get attributes assigned to a user |
| `assign_attribute_to_user` | Assign an attribute to a user |
| `update_user_attribute` | Update an attribute assigned to a user |
| `unassign_attribute_from_user` | Unassign an attribute from a user |
| `get_user_attribute_history` | Get the attribute assignment history of a user |

### Routing forms

| Tool | Description |
| - | - |
| `calculate_routing_form_slots` | Calculate slots based on routing form response |
| `get_org_routing_forms` | Get organization routing forms |
| `get_org_routing_form_responses` | Get routing form responses |
| `get_team_routing_forms` | Get team routing forms |
| `create_routing_form` | Create a team routing form that starts with a fallback route |
| `get_routing_form` | Get a team routing form's questions and routes |
| `get_routing_form_history` | Get a team routing form's change history, newest first: who changed what and when; supports `limit` (max 50) and `cursor` pagination |
| `edit_routing_form_routes` | Preview and apply edits to a team routing form's routes |
| `edit_routing_form_fields` | Preview and apply edits to a team routing form's questions |

### API catalog

| Tool | Description |
| - | - |
| `find_api_operation` | Search the full API v2 operation catalog |
| `describe_api_operation` | Get the input schema for an API operation |
| `call_api_operation` | Execute any API v2 operation from the catalog |

## Example prompts

Once connected, you can interact with Cal.com using natural language:

* "What bookings do I have this week?"
* "Create a 30-minute event type called 'Quick Chat'"
* "Cancel my meeting with John tomorrow"
* "Show me my available slots for next Monday"
* "Reschedule my 2pm meeting to Thursday at 3pm"
* "What event types do I have?"

## Related resources

* [AI agents guide](https://cal.com/docs/agents.md) — build AI agents using the Cal.com API directly
* [API v2 reference](https://cal.com/docs/api-reference/v2/introduction.md) — full API endpoint documentation
* [GitHub repository](https://github.com/calcom/companion/tree/main/apps/mcp-server) — source code


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.