Cal.com MCP

official

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

What can you do with Cal Com MCP?

  • Manage bookings — Ask your assistant to list, create, reschedule, cancel, or confirm bookings, and add attendees to them.
  • Check availability — Get open time slots, busy times from connected calendars, and your default schedule.
  • Set up event types — Create, update, duplicate, or delete event types, including team event types.
  • Handle schedules and contacts — Create and edit schedules, and add, update, or tag your personal contacts.
  • Manage teams and organizations — Invite team members, manage memberships, and list or edit organization teams and attributes.
  • Search docs and the API catalog — Search Cal.com documentation or find, describe, and call any API v2 operation.

Documentation

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 in the Model Context Protocol, 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 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, 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
{
  "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:

{
  "mcpServers": {
    "calcom": {
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

[tab] VS Code

Add the server to your VS Code MCP settings:

{
  "mcpServers": {
    "calcom": {
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

[tab] fx

Add the following to your ~/.fx/mcp.json:

{
  "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 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, select Grok Bot under Client setup, then scan the QR code or click Add Bot to open the Cal.com bot 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

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

Connect your client

Add the following to your MCP client's configuration:

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

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, discover, 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, 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.

Event subscriptions (MCP Events)

The hosted server supports MCP Events, so clients on protocol version 2026-07-28 can get notified when something happens in your Cal.com account instead of polling. The server advertises the events capability and handles three methods:

  • events/list: returns the events you can subscribe to, such as booking.created, booking.rescheduled, booking.cancelled, meeting.ended and recording.ready, each with an input schema and a payload schema.
  • events/subscribe: subscribes a callback URL to an event. The callback must be a public HTTPS URL, and delivery.secret must be a whsec_ secret. Before saving the subscription, the server sends a signed verification request with a challenge value that your endpoint must echo back in its JSON response. Subscribing again with the same URL, event and arguments refreshes the existing subscription.
  • events/unsubscribe: removes one of your subscriptions. Calling it for a subscription that no longer exists succeeds.

Deliveries are signed with Standard Webhooks using your whsec_ secret. Subscriptions expire after 7 days by default; set ttlMs to request a lifetime between 1 hour and 30 days.

Your first subscription creates a Cal.com webhook on your account that sends events to the server's POST /events/calcom/<ref> route, and removing your last subscription deletes it. You don't call this route yourself.

[!NOTE]

MCP Events are served over the Streamable HTTP transport only, not by the self-hosted stdio server. They are unrelated to the events toolset, which manages Cal Events RSVP pages.

Available tools

The MCP server exposes 85 tools organized by category:

App links

ToolDescription
get_app_linkBuild a URL that opens a booking, event type, schedule, team, routing form or settings page in the Cal.com web app

Documentation

ToolDescription
search_docsSearch the Cal.com product documentation; returns ranked pages with an excerpt of the top result

User profile

ToolDescription
get_meGet your authenticated user profile
update_meUpdate your user profile

Event types

ToolDescription
get_event_typesList all event types
get_event_typeGet a specific event type by ID
create_event_typeCreate a new event type
update_event_typeUpdate an event type
delete_event_typeDelete an event type
duplicate_event_typeDuplicate an organization team event type into the same team or another team of the organization
get_event_type_settingsGet the settings of an event type
get_event_type_historyGet the change history of an event type
get_scheduling_configGet the scheduling configuration of an event type
get_crm_sync_errorsGet 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. get_events and get_event need the EVENT_READ OAuth scope, and invite_cal_event_guests needs EVENT_WRITE.

ToolDescription
get_eventsList the Events you own or co-host, newest first; supports limit (max 250) and cursor pagination and a slug filter
get_eventGet one Event by uuid
invite_cal_event_guestsEmail an invitation to each address, to each of your contacts by id (contactIds), or to every contact with one of your contact tags (contactTagIds); contacts need the contacts feature; reports what happened to each address

Bookings

ToolDescription
get_bookingsList bookings with optional filters
get_bookingGet a specific booking by UID
create_bookingCreate a new booking
reschedule_bookingReschedule a booking
cancel_bookingCancel a booking
confirm_bookingConfirm a pending booking
mark_booking_absentMark a booking absence
get_booking_attendeesGet all attendees for a booking
add_booking_attendeeAdd an attendee to a booking
get_booking_attendeeGet a specific attendee
get_booking_routing_traceGet the routing trace for a booking
get_org_team_bookingsGet bookings for an organization team
get_org_user_bookingsGet bookings for an organization user

Schedules

ToolDescription
get_schedulesList all schedules
get_scheduleGet a specific schedule by ID
create_scheduleCreate a new schedule
update_scheduleUpdate a schedule
delete_scheduleDelete a schedule
get_default_scheduleGet your default schedule

Availability & calendars

ToolDescription
get_availabilityGet available time slots
get_busy_timesGet busy times from calendars
get_connected_calendarsList connected calendars
get_conferencing_appsList conferencing applications

Contacts

Your personal contacts and their tags from your Contacts page — never team or organization members. The lists need the CONTACT_READ OAuth scope and the writes CONTACT_WRITE. Tags are shared with your links.

ToolDescription
list_contactsList your contacts, 50 per page, optionally only those with certain tags, with whether each is on Cal and can join a group meeting
add_contactAdd a contact by email, with an optional name
update_contactUpdate a contact's name; a contact on Cal can't have its name changed
remove_contactRemove a contact and its tags
list_contact_tagsList your tags, 50 per page, with how many contacts carry each
create_contact_tagCreate a tag, without putting it on any contact
add_contact_tagPut one tag on a contact
remove_contact_tagTake one tag off a contact; the tag itself stays

Discover

Published Discover listings, searched or read by the ids a search returned, which need the EVENT_TYPE_READ OAuth scope; calls and online bookings at web-found businesses and requests to be told when a provider joins, which need PROFILE_WRITE.

ToolDescription
search_listingsSearch listings by category, free text, area, price, duration and an open slot window, with each listing's booking link; when the area has nothing, businesses found on the web there
get_discover_listingsRead up to 50 listings as their public cards show them, optionally with each one's earliest open slot in the next 7 days
call_business_to_bookHave Cal call a business that search_listings found on the web to book a service, once the user approves; returns the call's page to follow it on
book_onlineHave Cal's booking agent book a business that search_listings found on the web on its own booking page, once the user approves; returns the job's page, where the user picks an option and approves the price and terms
record_service_requestAsk to be emailed at your account address when a provider for a service Discover has no listing for joins; asking again for the same need in the same region within 90 days changes nothing

Teams & memberships

ToolDescription
get_my_teamsGet the teams you belong to
get_org_teamsGet organization teams
create_team_inviteInvite someone to a team
create_team_membershipCreate a team membership
get_team_membershipsGet all team memberships
get_team_membershipGet a team membership
update_team_membershipUpdate a team membership
delete_team_membershipDelete a team membership

Organizations

ToolDescription
get_org_membershipsGet all organization memberships
create_org_membershipCreate an organization membership
get_org_membershipGet an organization membership
update_org_membershipUpdate an organization membership
delete_org_membershipDelete an organization membership
get_org_attributesGet organization attributes
get_org_attributeGet an organization attribute
get_attribute_optionsGet options for an attribute
get_user_attributesGet attributes assigned to a user
assign_attribute_to_userAssign an attribute to a user
update_user_attributeUpdate an attribute assigned to a user
unassign_attribute_from_userUnassign an attribute from a user
get_user_attribute_historyGet the attribute assignment history of a user

Routing forms

ToolDescription
calculate_routing_form_slotsCalculate slots based on routing form response
get_org_routing_formsGet organization routing forms
get_org_routing_form_responsesGet routing form responses
get_team_routing_formsGet team routing forms
create_routing_formCreate a team routing form that starts with a fallback route
get_routing_formGet a team routing form's questions and routes
get_routing_form_historyGet a team routing form's change history, newest first: who changed what and when; supports limit (max 50) and cursor pagination
edit_routing_form_routesPreview and apply edits to a team routing form's routes
edit_routing_form_fieldsPreview and apply edits to a team routing form's questions

API catalog

ToolDescription
find_api_operationSearch the full API v2 operation catalog
describe_api_operationGet the input schema for an API operation
call_api_operationExecute 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

This documentation is built and hosted on Mintlify, a developer documentation platform.