Cal.com MCP

officiel

Connectez les clients IA à la planification Cal.com via le protocole de contexte de modèle en utilisant le serveur hébergé sur mcp.cal.com ou une instance locale.

Que pouvez-vous faire avec Cal Com MCP ?

  • Gérer les réservations — Demandez à votre assistant de répertorier, créer, reprogrammer, annuler ou confirmer des réservations, ainsi que d’ajouter ou de consulter des participants.
  • Vérifier les disponibilités — Consultez les créneaux libres, les périodes occupées dans les calendriers connectés, ainsi que vos calendriers et applications de visioconférence connectés.
  • Configurer les types d’événements — Créez, mettez à jour, dupliquez ou supprimez des types d’événements, et consultez leurs paramètres, leur configuration de planification et leur historique des modifications.
  • Gérer les plannings — Répertoriez, créez, mettez à jour ou supprimez des plannings, et récupérez votre planning par défaut.
  • Gérer les équipes et les organisations — Consultez les équipes, gérez les membres et les invitations aux équipes, ainsi que les membres et les attributs des organisations.
  • Rechercher dans le catalogue de l’API — Recherchez, décrivez et exécutez n’importe quelle opération de l’API Cal.com v2 via les méta-outils du catalogue.

Documentation

Serveur MCP

Connectez les clients IA à la planification de Cal.com via le Model Context Protocol, à l’aide du serveur hébergé sur mcp.cal.com ou d’une instance locale.

Le serveur MCP de Cal.com encapsule l’API Cal.com v2 dans le Model Context Protocol, ce qui vous permet de gérer les réservations, les types d’événements, les plannings et bien plus encore en langage naturel dans tout client compatible avec MCP.

Serveur hébergé (mcp.cal.com)

Le moyen le plus rapide de commencer consiste à connecter directement votre client MCP à mcp.cal.com. Le serveur hébergé utilise le transport HTTP Streamable avec l’authentification OAuth 2.1 : votre client gère automatiquement le flux d’autorisation.

Connecter votre client

Configurez l’URL du serveur hébergé dans votre client MCP :

https://mcp.cal.com/mcp

Lors de votre première connexion, votre client vous guide dans un flux d’autorisation OAuth où vous accordez au serveur l’accès à votre compte Cal.com. Aucune clé API n’est nécessaire. Tout client MCP peut se connecter : les clients s’enregistrent dynamiquement via POST /oauth/register ou s’identifient avec un document de métadonnées client (une URL https client_id). Avant la connexion à Cal.com, une page de consentement indique le nom du client et l’hôte vers lequel vous serez redirigé.

[!NOTE]

L’écran de consentement demande également les autorisations d’équipe nécessaires pour créer, modifier et supprimer des types d’événements d’équipe, ainsi que pour consulter et gérer les membres des équipes. Votre client IA peut ainsi configurer des types d’événements d’équipe et ajouter des personnes aux équipes. Il demande également les autorisations de profil d’organisation, afin que le client IA d’un administrateur d’organisation puisse répertorier, créer, modifier et supprimer les équipes de l’organisation. Cal.com vérifie toujours votre rôle et vos autorisations dans l’équipe à chaque appel. Il demande aussi l’autorisation de consulter, d’ajouter, de renommer et de supprimer vos contacts personnels (CONTACT_READ, CONTACT_WRITE). Si vous vous êtes connecté avant l’ajout de ces autorisations, déconnectez le serveur, puis reconnectez-le pour les accorder.

[tab] Claude Desktop

Ajoutez ce qui suit à votre 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

Ouvrez Settings → MCP et ajoutez un nouveau serveur avec l’URL https://mcp.cal.com/mcp, ou ajoutez-la à votre .cursor/mcp.json :

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

[tab] VS Code

Ajoutez le serveur aux paramètres MCP de VS Code :

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

[tab] fx

Ajoutez ce qui suit à votre ~/.fx/mcp.json :

{
  "mcp": {
    "calcom": {
      "type": "http",
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

Exécutez ensuite /mcp auth calcom --open dans fx pour vous autoriser. Consultez la documentation MCP de fx pour en savoir plus sur les transports, les options d’authentification et la découverte des outils.

[tab] Grok

Grok se connecte via le bot Cal.com plutôt qu’avec une configuration JSON. Dans Settings → Developer → MCP, sélectionnez Grok Bot sous Client setup, puis scannez le code QR ou cliquez sur Add Bot pour ouvrir le bot Cal.com dans 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

Serveur auto-hébergé (stdio)

Si vous préférez exécuter le serveur localement, vous pouvez utiliser le transport stdio avec une clé API. Cette option est utile pour le développement ou si vous souhaitez contrôler entièrement le serveur.

Prérequis

Connecter votre client

Ajoutez ce qui suit à la configuration de votre client MCP :

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

Remplacez cal_live_xxxx par votre véritable clé API.

[!WARNING]

Ne partagez et ne validez jamais votre clé API dans un dépôt. Si elle est exposée, révoquez-la immédiatement dans vos paramètres Cal.com.

Exécuter le serveur HTTP avec Docker Compose

Pour auto-héberger le serveur HTTP Streamable avec OAuth, utilisez le fichier apps/mcp/docker-compose.yml du dépôt Cal.com. Il exécute le serveur MCP et sa base de données PostgreSQL derrière un proxy Caddy sur les ports 80 et 443.

Définissez MCP_POSTGRES_PASSWORD avant de le démarrer. Compose refuse de démarrer sans cette variable. Comme le mot de passe est également intégré à la chaîne de connexion à la base de données du serveur, utilisez uniquement des caractères compatibles avec les URL.

export MCP_POSTGRES_PASSWORD="$(openssl rand -hex 24)"
docker compose -f apps/mcp/docker-compose.yml up -d

PostgreSQL n’est pas exposé sur un port de l’hôte. Seul le serveur MCP peut y accéder via le réseau Compose. Pour vous connecter vous-même à la base de données, utilisez docker compose -f apps/mcp/docker-compose.yml exec postgres psql -U mcp mcp.

[!NOTE]

PostgreSQL ne lit le mot de passe que lors de la création initiale de son volume de données. Si vous avez créé le volume avec une version antérieure du fichier Compose, son mot de passe est toujours mcp. Définissez MCP_POSTGRES_PASSWORD=mcp, ou modifiez le mot de passe avec ALTER USER mcp PASSWORD '...' et définissez la nouvelle valeur.

Ensembles d’outils

Vous pouvez limiter les outils que le serveur enregistre pour une session en ajoutant un paramètre de requête toolsets à l’URL du serveur :

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

Ensembles d’outils valides : profile, event-types, events, bookings, availability, schedules, calendars, contacts, discover, teams, organizations, routing-forms, catalog (les méta-outils find_api_operation / describe_api_operation / call_api_operation). Les noms inconnus sont rejetés avec 400 invalid_request. Si vous omettez le paramètre, tous les outils sont enregistrés ; les outils locaux get_app_link et search_docs sont toujours enregistrés, quel que soit votre choix. Pour un serveur stdio auto-hébergé, définissez plutôt MCP_TOOLSETS.

Vues interactives (MCP Apps)

Dans les clients compatibles avec MCP Apps, get_availability et get_bookings affichent également une vue interactive dans la conversation. Vous pouvez ainsi choisir des horaires et gérer les réservations par clic plutôt qu’en saisissant du texte :

  • Sélecteur de créneaux (get_availability) : affiche les horaires disponibles, regroupés par jour. Utilisez les flèches pour passer à des dates antérieures ou ultérieures, cliquez sur un horaire, saisissez le nom et l’adresse e-mail du participant, puis cliquez sur Book. Lorsque l’assistant recherche un nouvel horaire pour une réservation existante, cliquer sur un horaire propose plutôt Move booking here.
  • Réservations (get_bookings) : affiche une carte par réservation, avec son horaire et ses participants. Les réservations à venir proposent Join (si la réservation comporte un lien de réunion), Reschedule, qui affiche les horaires disponibles de la semaine suivante, et Cancel, qui vous demande de confirmer directement sur la carte.

Les horaires sont affichés dans le fuseau horaire indiqué par votre client, et les vues respectent son thème clair ou sombre. Les actions utilisent les mêmes outils create_booking, reschedule_booking et cancel_booking sur votre connexion existante, et l’assistant est informé de vos actions.

[!NOTE]

Les vues sont disponibles uniquement lorsque les ensembles d’outils bookings et availability sont tous deux activés, ce qui est le cas par défaut si vous ne transmettez pas toolsets. Les clients qui ne prennent pas en charge MCP Apps reçoivent les mêmes résultats textuels qu’auparavant.

Abonnements aux événements (MCP Events)

Le serveur hébergé prend en charge MCP Events, ce qui permet aux clients utilisant la version de protocole 2026-07-28 d’être avertis lorsqu’un événement survient dans votre compte Cal.com, au lieu d’interroger le serveur périodiquement. Le serveur annonce la capacité events et gère trois méthodes :

  • events/list : renvoie les événements auxquels vous pouvez vous abonner, tels que booking.created, booking.rescheduled, booking.cancelled, meeting.ended et recording.ready, chacun avec un schéma d’entrée et un schéma de charge utile.
  • events/subscribe : abonne une URL de rappel à un événement. L’URL de rappel doit être une URL HTTPS publique, et delivery.secret doit être un secret whsec_. Avant d’enregistrer l’abonnement, le serveur envoie une requête de vérification signée contenant une valeur challenge que votre point de terminaison doit renvoyer dans sa réponse JSON. Un nouvel abonnement avec la même URL, le même événement et les mêmes arguments actualise l’abonnement existant.
  • events/unsubscribe : supprime l’un de vos abonnements. L’appel réussit même si l’abonnement n’existe plus.

Les notifications sont signées avec Standard Webhooks à l’aide de votre secret whsec_. Les abonnements expirent au bout de 7 jours par défaut ; définissez ttlMs pour demander une durée comprise entre 1 heure et 30 jours.

Votre premier abonnement crée un webhook Cal.com sur votre compte, qui envoie les événements à la route POST /events/calcom/<ref> du serveur. La suppression de votre dernier abonnement supprime ce webhook. Vous n’appelez pas cette route vous-même.

[!NOTE]

MCP Events est disponible uniquement via le transport HTTP Streamable, et non via le serveur stdio auto-hébergé. Cette fonctionnalité n’a aucun lien avec l’ensemble d’outils events, qui gère les pages RSVP de Cal Events.

Outils disponibles

Le serveur MCP expose 85 outils organisés par catégorie :

Liens vers l’application

OutilDescription
get_app_linkCréer une URL qui ouvre une réservation, un type d’événement, un planning, une équipe, un formulaire de routage ou une page de paramètres dans l’application Web Cal.com

Documentation

OutilDescription
search_docsRechercher dans la documentation du produit Cal.com ; renvoie les pages classées par pertinence, avec un extrait du meilleur résultat

Profil utilisateur

OutilDescription
get_meObtenir le profil de l’utilisateur authentifié
update_meMettre à jour votre profil utilisateur

Types d’événements

OutilDescription
get_event_typesRépertorier tous les types d’événements
get_event_typeObtenir un type d’événement spécifique par ID
create_event_typeCréer un type d’événement
update_event_typeMettre à jour un type d’événement
delete_event_typeSupprimer un type d’événement
duplicate_event_typeDupliquer un type d’événement d’équipe d’organisation dans la même équipe ou dans une autre équipe de l’organisation
get_event_type_settingsObtenir les paramètres d’un type d’événement
get_event_type_historyObtenir l’historique des modifications d’un type d’événement
get_scheduling_configObtenir la configuration de planification d’un type d’événement
get_crm_sync_errorsObtenir les erreurs de synchronisation CRM d’un type d’événement

Événements

Les Cal Events sont des pages RSVP à date fixe accessibles sur cal.com/{slug} — ce ne sont ni des types d’événements ni des événements de calendrier. get_events et get_event nécessitent l’autorisation OAuth EVENT_READ, et invite_cal_event_guests nécessite EVENT_WRITE.

OutilDescription
get_eventsRépertorier les événements dont vous êtes propriétaire ou coorganisateur, du plus récent au plus ancien ; prend en charge limit (maximum 250), la pagination cursor et un filtre slug
get_eventObtenir un événement par uuid
invite_cal_event_guestsEnvoyer une invitation par e-mail à chaque adresse, à chacun de vos contacts par ID (contactIds) ou à tous les contacts associés à l’une de vos étiquettes de contact (contactTagIds) ; les contacts nécessitent la fonctionnalité contacts ; indique le résultat pour chaque adresse

Réservations

OutilDescription
get_bookingsRépertorier les réservations avec des filtres facultatifs
get_bookingObtenir une réservation spécifique par UID
create_bookingCréer une réservation
reschedule_bookingReprogrammer une réservation
cancel_bookingAnnuler une réservation
confirm_bookingConfirmer une réservation en attente
mark_booking_absentSignaler l’absence à une réservation
get_booking_attendeesObtenir tous les participants d’une réservation
add_booking_attendeeAjouter un participant à une réservation
get_booking_attendeeObtenir un participant spécifique
get_booking_routing_traceObtenir la trace de routage d’une réservation
get_org_team_bookingsObtenir les réservations d’une équipe d’organisation
get_org_user_bookingsObtenir les réservations d’un utilisateur d’organisation

Plannings

OutilDescription
get_schedulesRépertorier tous les plannings
get_scheduleObtenir un planning spécifique par ID
create_scheduleCréer un planning
update_scheduleMettre à jour un planning
delete_scheduleSupprimer un planning
get_default_scheduleObtenir votre planning par défaut

Disponibilités et calendriers

OutilDescription
get_availabilityObtenir les créneaux horaires disponibles
get_busy_timesObtenir les périodes occupées dans les calendriers
get_connected_calendarsRépertorier les calendriers connectés
get_conferencing_appsRépertorier les applications de visioconférence

Contacts

Vos contacts personnels et leurs étiquettes de votre page Contacts — jamais les membres d’une équipe ou d’une organisation. Les listes nécessitent le scope OAuth CONTACT_READ et les écritures, CONTACT_WRITE. Les étiquettes sont partagées avec vos liens.

OutilDescription
list_contactsLister vos contacts, 50 par page, éventuellement uniquement ceux qui ont certaines étiquettes, et indiquer si chacun est sur Cal et peut rejoindre une réunion de groupe
add_contactAjouter un contact par e-mail, avec un nom facultatif
update_contactModifier le nom d’un contact ; le nom d’un contact sur Cal ne peut pas être modifié
remove_contactSupprimer un contact et ses étiquettes
list_contact_tagsLister vos étiquettes, 50 par page, avec le nombre de contacts associés à chacune
create_contact_tagCréer une étiquette, sans l’attribuer à aucun contact
add_contact_tagAttribuer une étiquette à un contact
remove_contact_tagRetirer une étiquette d’un contact ; l’étiquette elle-même est conservée

Découvrir

Les annonces Discover publiées, recherchées ou consultées à partir des identifiants renvoyés par une recherche, nécessitent le scope OAuth EVENT_TYPE_READ ; les appels et réservations en ligne auprès d’entreprises trouvées sur le Web, ainsi que les demandes d’être averti lorsqu’un prestataire rejoint la plateforme, nécessitent PROFILE_WRITE.

OutilDescription
search_listingsRechercher des annonces par catégorie, texte libre, zone, prix, durée et plage de créneaux disponibles, avec le lien de réservation de chaque annonce ; si aucun résultat n’est disponible dans la zone, rechercher des entreprises sur le Web dans cette zone
get_discover_listingsConsulter jusqu’à 50 annonces telles qu’elles apparaissent sur leurs fiches publiques, avec éventuellement le premier créneau disponible de chacune au cours des 7 prochains jours
call_business_to_bookDemander à Cal d’appeler une entreprise que search_listings a trouvée sur le Web pour réserver un service, après approbation de l’utilisateur ; renvoie la page de l’appel pour en suivre le déroulement
book_onlineDemander à l’agent de réservation de Cal de réserver un service auprès d’une entreprise que search_listings a trouvée sur le Web, sur la page de réservation de l’entreprise, après approbation de l’utilisateur ; renvoie la page de la tâche, où l’utilisateur choisit une option et approuve le prix et les conditions
record_service_requestDemander à recevoir un e-mail à l’adresse de votre compte lorsqu’un prestataire rejoint la plateforme pour un service qui n’a pas d’annonce sur Discover ; une nouvelle demande pour le même besoin dans la même région dans les 90 jours ne change rien

Équipes et adhésions

OutilDescription
get_my_teamsObtenir les équipes auxquelles vous appartenez
get_org_teamsObtenir les équipes de l’organisation
create_team_inviteInviter quelqu’un dans une équipe
create_team_membershipCréer une adhésion à une équipe
get_team_membershipsObtenir toutes les adhésions aux équipes
get_team_membershipObtenir une adhésion à une équipe
update_team_membershipModifier une adhésion à une équipe
delete_team_membershipSupprimer une adhésion à une équipe

Organisations

OutilDescription
get_org_membershipsObtenir toutes les adhésions à une organisation
create_org_membershipCréer une adhésion à une organisation
get_org_membershipObtenir une adhésion à une organisation
update_org_membershipModifier une adhésion à une organisation
delete_org_membershipSupprimer une adhésion à une organisation
get_org_attributesObtenir les attributs d’une organisation
get_org_attributeObtenir un attribut d’organisation
get_attribute_optionsObtenir les options d’un attribut
get_user_attributesObtenir les attributs attribués à un utilisateur
assign_attribute_to_userAttribuer un attribut à un utilisateur
update_user_attributeModifier un attribut attribué à un utilisateur
unassign_attribute_from_userRetirer un attribut à un utilisateur
get_user_attribute_historyObtenir l’historique des attributions d’attributs d’un utilisateur

Formulaires de routage

OutilDescription
calculate_routing_form_slotsCalculer les créneaux en fonction des réponses au formulaire de routage
get_org_routing_formsObtenir les formulaires de routage de l’organisation
get_org_routing_form_responsesObtenir les réponses aux formulaires de routage
get_team_routing_formsObtenir les formulaires de routage de l’équipe
create_routing_formCréer un formulaire de routage d’équipe qui commence par une route de secours
get_routing_formObtenir les questions et les routes d’un formulaire de routage d’équipe
get_routing_form_historyObtenir l’historique des modifications d’un formulaire de routage d’équipe, de la plus récente à la plus ancienne : qui a modifié quoi et quand ; prend en charge limit (maximum 50) et la pagination cursor
edit_routing_form_routesPrévisualiser et appliquer les modifications aux routes d’un formulaire de routage d’équipe
edit_routing_form_fieldsPrévisualiser et appliquer les modifications aux questions d’un formulaire de routage d’équipe

Catalogue API

OutilDescription
find_api_operationRechercher dans le catalogue complet des opérations de l’API v2
describe_api_operationObtenir le schéma d’entrée d’une opération API
call_api_operationExécuter n’importe quelle opération API v2 du catalogue

Exemples de requêtes

Une fois connecté, vous pouvez interagir avec Cal.com en langage naturel :

  • « Quelles réservations ai-je cette semaine ? »
  • « Crée un type d’événement de 30 minutes appelé “Discussion rapide” »
  • « Annule ma réunion avec John demain »
  • « Montre-moi mes créneaux disponibles pour lundi prochain »
  • « Reprogramme ma réunion de 14 h à jeudi à 15 h »
  • « Quels types d’événements ai-je ? »

Ressources associées

Cette documentation est créée et hébergée sur Mintlify, une plateforme de documentation pour développeurs.