Cal.com MCP
officielConnectez 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 --opendans 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.
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
- Node.js >= 18
- Une clé API Cal.com — générez-en une dans Settings → Developer → API Keys
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éfinissezMCP_POSTGRES_PASSWORD=mcp, ou modifiez le mot de passe avecALTER 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
bookingsetavailabilitysont tous deux activés, ce qui est le cas par défaut si vous ne transmettez pastoolsets. 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 quebooking.created,booking.rescheduled,booking.cancelled,meeting.endedetrecording.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, etdelivery.secretdoit être un secretwhsec_. Avant d’enregistrer l’abonnement, le serveur envoie une requête de vérification signée contenant une valeurchallengeque 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
| Outil | Description |
|---|---|
get_app_link | Cré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
| Outil | Description |
|---|---|
search_docs | Rechercher dans la documentation du produit Cal.com ; renvoie les pages classées par pertinence, avec un extrait du meilleur résultat |
Profil utilisateur
| Outil | Description |
|---|---|
get_me | Obtenir le profil de l’utilisateur authentifié |
update_me | Mettre à jour votre profil utilisateur |
Types d’événements
| Outil | Description |
|---|---|
get_event_types | Répertorier tous les types d’événements |
get_event_type | Obtenir un type d’événement spécifique par ID |
create_event_type | Créer un type d’événement |
update_event_type | Mettre à jour un type d’événement |
delete_event_type | Supprimer un type d’événement |
duplicate_event_type | Dupliquer 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_settings | Obtenir les paramètres d’un type d’événement |
get_event_type_history | Obtenir l’historique des modifications d’un type d’événement |
get_scheduling_config | Obtenir la configuration de planification d’un type d’événement |
get_crm_sync_errors | Obtenir 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.
| Outil | Description |
|---|---|
get_events | Ré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_event | Obtenir un événement par uuid |
invite_cal_event_guests | Envoyer 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
| Outil | Description |
|---|---|
get_bookings | Répertorier les réservations avec des filtres facultatifs |
get_booking | Obtenir une réservation spécifique par UID |
create_booking | Créer une réservation |
reschedule_booking | Reprogrammer une réservation |
cancel_booking | Annuler une réservation |
confirm_booking | Confirmer une réservation en attente |
mark_booking_absent | Signaler l’absence à une réservation |
get_booking_attendees | Obtenir tous les participants d’une réservation |
add_booking_attendee | Ajouter un participant à une réservation |
get_booking_attendee | Obtenir un participant spécifique |
get_booking_routing_trace | Obtenir la trace de routage d’une réservation |
get_org_team_bookings | Obtenir les réservations d’une équipe d’organisation |
get_org_user_bookings | Obtenir les réservations d’un utilisateur d’organisation |
Plannings
| Outil | Description |
|---|---|
get_schedules | Répertorier tous les plannings |
get_schedule | Obtenir un planning spécifique par ID |
create_schedule | Créer un planning |
update_schedule | Mettre à jour un planning |
delete_schedule | Supprimer un planning |
get_default_schedule | Obtenir votre planning par défaut |
Disponibilités et calendriers
| Outil | Description |
|---|---|
get_availability | Obtenir les créneaux horaires disponibles |
get_busy_times | Obtenir les périodes occupées dans les calendriers |
get_connected_calendars | Répertorier les calendriers connectés |
get_conferencing_apps | Ré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.
| Outil | Description |
|---|---|
list_contacts | Lister 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_contact | Ajouter un contact par e-mail, avec un nom facultatif |
update_contact | Modifier le nom d’un contact ; le nom d’un contact sur Cal ne peut pas être modifié |
remove_contact | Supprimer un contact et ses étiquettes |
list_contact_tags | Lister vos étiquettes, 50 par page, avec le nombre de contacts associés à chacune |
create_contact_tag | Créer une étiquette, sans l’attribuer à aucun contact |
add_contact_tag | Attribuer une étiquette à un contact |
remove_contact_tag | Retirer 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.
| Outil | Description |
|---|---|
search_listings | Rechercher 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_listings | Consulter 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_book | Demander à 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_online | Demander à 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_request | Demander à 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
| Outil | Description |
|---|---|
get_my_teams | Obtenir les équipes auxquelles vous appartenez |
get_org_teams | Obtenir les équipes de l’organisation |
create_team_invite | Inviter quelqu’un dans une équipe |
create_team_membership | Créer une adhésion à une équipe |
get_team_memberships | Obtenir toutes les adhésions aux équipes |
get_team_membership | Obtenir une adhésion à une équipe |
update_team_membership | Modifier une adhésion à une équipe |
delete_team_membership | Supprimer une adhésion à une équipe |
Organisations
| Outil | Description |
|---|---|
get_org_memberships | Obtenir toutes les adhésions à une organisation |
create_org_membership | Créer une adhésion à une organisation |
get_org_membership | Obtenir une adhésion à une organisation |
update_org_membership | Modifier une adhésion à une organisation |
delete_org_membership | Supprimer une adhésion à une organisation |
get_org_attributes | Obtenir les attributs d’une organisation |
get_org_attribute | Obtenir un attribut d’organisation |
get_attribute_options | Obtenir les options d’un attribut |
get_user_attributes | Obtenir les attributs attribués à un utilisateur |
assign_attribute_to_user | Attribuer un attribut à un utilisateur |
update_user_attribute | Modifier un attribut attribué à un utilisateur |
unassign_attribute_from_user | Retirer un attribut à un utilisateur |
get_user_attribute_history | Obtenir l’historique des attributions d’attributs d’un utilisateur |
Formulaires de routage
| Outil | Description |
|---|---|
calculate_routing_form_slots | Calculer les créneaux en fonction des réponses au formulaire de routage |
get_org_routing_forms | Obtenir les formulaires de routage de l’organisation |
get_org_routing_form_responses | Obtenir les réponses aux formulaires de routage |
get_team_routing_forms | Obtenir les formulaires de routage de l’équipe |
create_routing_form | Créer un formulaire de routage d’équipe qui commence par une route de secours |
get_routing_form | Obtenir les questions et les routes d’un formulaire de routage d’équipe |
get_routing_form_history | Obtenir 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_routes | Prévisualiser et appliquer les modifications aux routes d’un formulaire de routage d’équipe |
edit_routing_form_fields | Prévisualiser et appliquer les modifications aux questions d’un formulaire de routage d’équipe |
Catalogue API
| Outil | Description |
|---|---|
find_api_operation | Rechercher dans le catalogue complet des opérations de l’API v2 |
describe_api_operation | Obtenir le schéma d’entrée d’une opération API |
call_api_operation | Exé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
- Guide des agents IA — créer des agents IA en utilisant directement l’API Cal.com
- Référence de l’API v2 — documentation complète des points de terminaison de l’API
Cette documentation est créée et hébergée sur Mintlify, une plateforme de documentation pour développeurs.
