MCP Tools Reference: calendarmcp.googleapis.com

Outil : list_events

Répertorie les événements d'agenda dans un agenda donné qui répondent aux conditions spécifiées.

Principales fonctionnalités :

  • Tout ID d'agenda, qui peut être l'agenda principal de l'utilisateur ou d'autres agendas.
  • Filtrage par période.
  • Récupère TOUS les événements correspondant aux contraintes temporelles.

Si l'outil search_events est disponible, utilisez-le plutôt pour les recherches dans l'agenda principal de l'utilisateur si :

  • Vous recherchez des événements correspondant à un thème, une catégorie ou une intention spécifiques (par exemple, "déjeuners", "synchronisations de projet").
  • Vous devez trouver les événements les plus pertinents (K premiers) plutôt que tous les événements qui répondent aux contraintes.
  • Vous avez besoin de fonctionnalités de recherche par mot clé ou sémantique.

Utilisez cet outil pour les requêtes telles que :

  • Qu'y a-t-il dans mon agenda demain ?
  • Qu'y a-t-il dans mon agenda pour le 14 juillet 2025 ?
  • Quelles sont mes réunions la semaine prochaine ?
  • Est-ce que j'ai des réunions qui se chevauchent cet après-midi ?

  • Quelles réunions John a-t-il demain ?

Exemple :

list_events(
            startTime='2024-09-17T06:00:00',
            endTime='2024-09-17T12:00:00',
            pageSize=10
        )
        # Returns up to 10 calendar events between 6:00 AM and 12:00 PM on September 17, 2024 from the user's primary calendar.

L'exemple suivant montre comment utiliser curl pour appeler l'outil MCP list_events.

Requête curl 
curl --location 'https://calendarmcp.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_events",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schéma d'entrée

ListEventsRequest

Représentation JSON 
{
  "eventTypeFilter": [
    string
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Champs
eventTypeFilter[]

string

Facultatif. Types d'événements à renvoyer. Valeurs possibles :

  • default : événements réguliers (par défaut)
  • outOfOffice : absences du bureau.
  • focusTime : événements "Moment de concentration".
  • workingLocation : événements liés au lieu de travail.
  • birthday : événements d'anniversaire
  • fromGmail : événements ajoutés à partir de Gmail.

Si ce champ est vide, seuls les types d'événements suivants sont renvoyés : default, outOfOffice, focusTime, fromGmail.

Champ d'union _calendar_id.

_calendar_id ne peut être qu'un des éléments suivants :
calendarId

string

Facultatif. ID de l'agenda à partir duquel lister les événements. Par défaut, il s'agit de l'agenda principal de l'utilisateur.

Champ d'union _page_size.

_page_size ne peut être qu'un des éléments suivants :
pageSize

integer

Facultatif. Nombre maximal d'événements renvoyés sur une page de résultats. Le nombre d'événements sur la page résultante peut être inférieur à cette valeur, voire nul, même si d'autres événements correspondent à la requête. Les pages incomplètes peuvent être détectées par un champ next_page_token non vide dans la réponse. La valeur par défaut est de 250 événements. La taille de la page ne peut jamais dépasser 2 500 événements.

Champ d'union _page_token.

_page_token ne peut être qu'un des éléments suivants :
pageToken

string

Facultatif. Jeton spécifiant la page de résultats à renvoyer.

Champ d'union _start_time.

_start_time ne peut être qu'un des éléments suivants :
startTime

string

Facultatif. Limite inférieure (exclusive) de l'heure de fin d'un événement. Seuls les événements se terminant strictement après cette heure sont renvoyés (c'est-à-dire le début de la période à rechercher). La valeur par défaut est l'heure actuelle si ni start_time ni end_time ne sont fournis. Si elle est spécifiée, elle doit être inférieure ou égale à end_time. Doit être un code temporel ISO 8601. Par exemple : 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z ou 2026-06-03T10:00:00. Les millisecondes peuvent être fournies, mais elles sont ignorées.

Champ d'union _end_time.

_end_time ne peut être qu'un des éléments suivants :
endTime

string

Facultatif. Limite supérieure (exclusive) de l'heure de début d'un événement. Seuls les événements commençant strictement avant cette heure sont renvoyés (c'est-à-dire la fin de la période à rechercher). Si elle est spécifiée, elle doit être supérieure ou égale à start_time. Doit être un code temporel ISO 8601. Par exemple : 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z ou 2026-06-03T10:00:00. Les millisecondes peuvent être fournies, mais elles sont ignorées.

Champ d'union _time_zone.

_time_zone ne peut être qu'un des éléments suivants :
timeZone

string

Facultatif. Fuseau horaire utilisé dans la réponse et pour résoudre les dates sans fuseau horaire dans la requête (formaté sous forme de nom de la base de données des fuseaux horaires de l'IANA, par exemple Europe/Zurich). Le fuseau horaire du calendrier est utilisé par défaut.

Champ d'union _order_by.

_order_by ne peut être qu'un des éléments suivants :
orderBy

string

Facultatif. Ordre dans lequel les événements doivent être renvoyés. Valeurs possibles :

  • default : ordre non spécifié, mais déterministe (par défaut).
  • startTime : tri par ordre croissant de l'heure de début.
  • startTimeDesc : tri par heure de début décroissante.
  • lastModified : trier par ordre croissant de la date et heure de la dernière modification.

Champ d'union _full_text.

_full_text ne peut être qu'un des éléments suivants :
fullText

string

Facultatif. Requête de recherche au format libre pour rechercher un titre, une description, un lieu et des participants.

Schéma de sortie

ListEventsResponse

Représentation JSON 
{
  "summary": string,
  "description": string,
  "updated": string,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      object (Reminder)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],

  "nextPageToken": string
}
Champs
summary

string

Titre de l'agenda.
description

string

Description de l'agenda.
updated

string

Date et heure de la dernière modification de l'agenda (au format ISO 8601).
timeZone

string

Fuseau horaire de l'agenda.
accessRole

string

Rôle d'accès de l'utilisateur pour cet agenda. Lecture seule. Valeurs possibles :

  • none : l'utilisateur n'a pas accès au contenu.
  • freeBusyReader : l'utilisateur dispose d'un accès en lecture aux informations de disponibilité.
  • reader : l'utilisateur dispose d'un accès en lecture à l'agenda. Les événements privés s'affichent pour les utilisateurs ayant accès en lecture, mais les détails sont masqués.
  • writer : l'utilisateur dispose d'un accès en lecture et en écriture à l'agenda. Les événements privés s'affichent pour les utilisateurs disposant d'un accès en écriture, et les détails des événements sont visibles.
  • owner : l'utilisateur dispose d'un accès administrateur à l'agenda. Ce rôle dispose de toutes les autorisations du rôle Rédacteur, ainsi que de la possibilité de consulter et de modifier les niveaux d'accès des autres utilisateurs. Important : Le rôle de propriétaire est différent de celui de propriétaire des données de l'agenda. Un agenda ne peut avoir qu'un seul propriétaire des données, mais peut avoir plusieurs utilisateurs avec le rôle de propriétaire.
defaultReminders[]

object (Reminder)

Rappels par défaut dans l'agenda de l'utilisateur authentifié. Ces rappels s'appliquent à tous les événements de cet agenda qui ne les remplacent pas explicitement (c'est-à-dire qui ne renseignent pas override_reminders).
events[]

object (Event)

Liste des événements de l'agenda.

Champ d'union _next_page_token.

_next_page_token ne peut être qu'un des éléments suivants :
nextPageToken

string

Jeton utilisé pour accéder à la page suivante de ce résultat. Omis si aucun autre résultat n'est disponible.

Rappel

Représentation JSON 
{

  "method": string

  "minutes": integer
}
Champs

Champ d'union _method.

_method ne peut être qu'un des éléments suivants :
method

string

Obligatoire. Mode d'envoi du rappel à l'utilisateur. Valeurs possibles :

  • email : les rappels sont envoyés par e-mail.
  • popup : les rappels sont envoyés via un pop-up de l'UI.

Champ d'union _minutes.

_minutes ne peut être qu'un des éléments suivants :
minutes

integer

Obligatoire. Nombre de minutes avant l'événement auquel le rappel doit être envoyé.

Événement

Représentation JSON 
{
  "id": string,
  "status": string,
  "htmlLink": string,
  "created": string,
  "updated": string,
  "summary": string,
  "description": string,
  "location": string,
  "creator": {
    object (Principal)
  },
  "organizer": {
    object (Principal)
  },
  "start": {
    object (DateOrDateTime)
  },
  "end": {
    object (DateOrDateTime)
  },
  "recurrence": [
    string
  ],
  "recurringEventId": string,
  "originalStartTime": {
    object (DateOrDateTime)
  },
  "transparency": string,
  "visibility": string,
  "attendees": [
    {
      object (Attendee)
    }
  ],
  "eventType": string,
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ]
}
Champs
id

string

Identifiant opaque de l'événement. Lorsque vous créez des événements uniques ou récurrents, vous pouvez spécifier leurs ID. Les ID fournis doivent respecter les règles suivantes :

  • Les caractères autorisés dans l'ID sont ceux utilisés dans l'encodage base32hex, c'est-à-dire les lettres minuscules a à v et les chiffres 0 à 9.Pour en savoir plus, consultez la section 3. 1.2 de la RFC2938.
  • La longueur de l'ID doit être comprise entre 5 et 1 024 caractères.
  • l'ID doit être unique pour chaque agenda.

En raison de la nature distribuée à l'échelle mondiale du système, nous ne pouvons pas garantir que les collisions d'ID seront détectées au moment de la création de l'événement. Pour minimiser le risque de collisions, nous vous recommandons d'utiliser un algorithme UUID établi, tel que celui décrit dans la RFC4122.

Si vous ne spécifiez pas d'ID, il sera généré automatiquement par le serveur.

Notez que les valeurs icalUID et id ne sont pas identiques. Vous ne devez fournir qu'une seule de ces valeurs lors de la création de l'événement. Une différence sémantique réside dans le fait que, dans les événements récurrents, toutes les occurrences d'un événement ont des ID différents, mais partagent toutes les mêmes icalUID.
status

string

État de l'événement. Facultatif. Valeurs possibles :

  • confirmed : l'événement est confirmé. Il s'agit de l'état par défaut.
  • tentative : l'événement est provisoirement confirmé.
  • cancelled : l'événement est annulé (supprimé). La méthode list ne renvoie les événements annulés que lors de la synchronisation incrémentielle (lorsque syncToken ou updatedMin sont spécifiés) ou si l'indicateur showDeleted est défini sur "true". La méthode get les renvoie toujours.

L'état "Annulée" représente deux états différents selon le type d'événement :

  1. Les exceptions annulées d'un événement périodique non annulé indiquent que cette instance ne doit plus être présentée à l'utilisateur. Les clients doivent stocker ces événements pendant toute la durée de l'événement récurrent parent.Les exceptions annulées sont garanties d'avoir des valeurs pour les champs "id", "recurringEventId" et "originalStartTime". Les autres champs peuvent être vides.
  2. Tous les autres événements annulés représentent des événements supprimés. Les clients doivent supprimer leurs copies synchronisées localement. Ces événements annulés finiront par disparaître. Ne comptez donc pas sur leur disponibilité indéfinie. Seul le champ "id" des événements supprimés est garanti d'être renseigné.

Dans l'agenda de l'organisateur, les événements annulés continuent d'afficher les détails de l'événement (résumé, lieu, etc.) afin de pouvoir être restaurés. De même, les événements auxquels l'utilisateur a été invité et qu'il a supprimés manuellement continuent de fournir des détails. Toutefois, les demandes de synchronisation incrémentielle avec showDeleted défini sur "false" ne renverront pas ces informations.

Si l'organisateur d'un événement change (par exemple, via l'opération de déplacement) et que l'organisateur d'origine ne figure pas dans la liste des participants, un événement annulé sera laissé derrière, où seul le champ "id" est garanti d'être renseigné.
htmlLink

string

Lien absolu vers cet événement dans l'interface utilisateur Web de Google Agenda. Lecture seule.
created

string

Heure de création de l'événement (code temporel au format ISO 8601). Lecture seule.
updated

string

Heure de la dernière modification des données d'événement principales (sous forme de code temporel au format ISO 8601). La modification des rappels d'événements n'aura aucune incidence. Lecture seule.
summary

string

Titre de l'événement.
description

string

Description de l'événement. Peut contenir du code HTML. Facultatif.
location

string

Emplacement géographique de l'événement sous forme de texte libre. Facultatif.
creator

object (Principal)

Créateur de l'événement. Lecture seule.
organizer

object (Principal)

Organisateur de l'événement. Si l'organisateur est également un participant, cela est indiqué dans une entrée distincte dans la liste des participants, avec le champ "organisateur" défini sur "True". Lecture seule.
start

object (DateOrDateTime)

Heure de début (incluse) de l'événement. Pour un événement périodique, il s'agit de l'heure de début de la première instance.
end

object (DateOrDateTime)

Heure de fin (exclusive) de l'événement. Pour un événement périodique, il s'agit de l'heure de fin de la première instance.
recurrence[]

string

Liste des lignes RRULE, EXRULE, RDATE et EXDATE pour un événement périodique, comme spécifié dans la RFC5545. Notez que les lignes DTSTART et DTEND ne sont pas autorisées dans ce champ. Les heures de début et de fin de l'événement sont spécifiées dans les champs de début et de fin. Ce champ est omis pour les événements ponctuels ou les instances d'événements récurrents.
recurringEventId

string

Pour une instance d'événement périodique, il s'agit de l'ID de l'événement périodique auquel appartient cette instance. Immuable.
originalStartTime

object (DateOrDateTime)

Pour une instance d'un événement périodique, il s'agit de l'heure à laquelle cet événement doit commencer selon les données de récurrence de l'événement périodique identifié par recurringEventId. Il identifie de manière unique l'instance dans la série d'événements périodiques, même si elle a été déplacée à une autre heure. Immuable.
transparency

string

Indique si l'événement bloque du temps dans l'agenda. Facultatif. Valeurs possibles :

  • opaque : valeur par défaut. L'événement bloque du temps dans l'agenda. Cela équivaut à définir "M'afficher comme occupé" dans l'interface utilisateur de l'agenda.
  • transparent : l'événement ne bloque pas de plage horaire dans l'agenda. Cela équivaut à définir "M'afficher comme" sur "Disponible" dans l'interface utilisateur de l'agenda.
visibility

string

Visibilité de l'événement. Facultatif. Valeurs possibles :

  • default : utilise la visibilité par défaut des événements dans l'agenda. Il s'agit de la valeur par défaut.
  • public : l'événement est public et les détails de l'événement sont visibles par tous les lecteurs de l'agenda.
  • private : l'événement est privé et seuls les participants peuvent en afficher les détails.
  • confidential : l'événement est privé. Cette valeur est fournie pour des raisons de compatibilité.
attendees[]

object (Attendee)

Participants à l'événement.
eventType

string

Type spécifique de l'événement. Vous ne pourrez plus modifier ce paramètre une fois l'événement créé. Valeurs possibles :

  • birthday : événement spécial d'une journée entière qui se répète chaque année.
  • default : événement régulier ou non spécifié.
  • focusTime : événement "Moment de concentration".
  • fromGmail : un événement ajouté à partir de Gmail. Ce type d'événement ne peut pas être créé.
  • outOfOffice : absence du bureau.
  • workingLocation : événement lié au lieu de travail.
conferenceUrl

string

Lien Google Meet vers l'événement.
colorId

string

ID de couleur de l'événement (chaîne 1-11) :

  • 1 : Lavande
  • 2 : Sage
  • 3 : Raisin
  • 4 : Flamant rose
  • 5 : Banana
  • 6 : Mandarine
  • 7 : Paon
  • 8 : Graphite
  • 9) Myrtille
  • 10 : Basilic
  • 11 : Tomate.

Dans Google Agenda, les couleurs des événements fonctionnent comme des catégories. Vous pouvez les définir pour chaque événement ou chaque série. Les utilisateurs peuvent attribuer des libellés personnalisés aux couleurs dans l'UI Web (par exemple, 1:1s, Break), mais l'API n'expose que des ID numériques, et non ces libellés. Cela n'affecte que votre propre vue de l'agenda. Chaque participant contrôle la couleur de son événement.
overrideReminders[]

object (Reminder)

Rappels définis pour cet événement, qui remplacent les rappels par défaut de l'agenda. Si ce paramètre n'est pas défini, les rappels par défaut du calendrier sont utilisés.

Compte principal

Représentation JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Champs
email

string

Adresse e-mail du compte principal (agenda).
displayName

string

Nom du responsable, s'il est disponible.
self

boolean

Indique si ce principal correspond à l'agenda dans lequel cette copie de l'événement apparaît. Lecture seule. La valeur par défaut est "False" (faux).

DateOrDateTime

Représentation JSON 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Champs
date

string

Date au format ISO 8601 à minuit UTC, par exemple 2019-11-20T00:00:00Z. Si ce champ est défini, date_time ne doit pas l'être.
dateTime

string

Code temporel au format ISO 8601, tel que 2019-11-20T08:19:06-07:00 ou 2019-11-20T08:19:06Z. Si ce champ est défini, date ne doit pas l'être.
timeZone

string

Nom du fuseau horaire TZDB, si disponible.

Participant

Représentation JSON 
{
  "id": string,
  "email": string,
  "displayName": string,
  "organizer": boolean,
  "self": boolean,
  "resource": boolean,
  "optionalAttendee": boolean,
  "responseStatus": string,
  "comment": string,
  "additionalGuests": integer
}
Champs
id

string

ID de profil du participant, s'il est disponible.
email

string

Adresse e-mail du participant, si disponible. Ce champ doit être présent lorsque vous ajoutez un participant. Il doit s'agir d'une adresse e-mail valide conformément à la norme RFC5322. Obligatoire lors de l'ajout d'un participant.
displayName

string

Nom du participant, s'il est disponible. Facultatif.
organizer

boolean

Indique si le participant est l'organisateur de l'événement. Lecture seule. La valeur par défaut est "False" (faux).
self

boolean

Indique si cette entrée représente l'agenda dans lequel cette copie de l'événement apparaît. Lecture seule. La valeur par défaut est "False" (faux).
resource

boolean

Indique si le participant est une ressource. Ne peut être défini que lorsque le participant est ajouté à l'événement pour la première fois. Les modifications ultérieures sont ignorées. Facultatif. La valeur par défaut est "False" (faux).
optionalAttendee

boolean

Indique si le participant est facultatif. Facultatif. La valeur par défaut est "False" (faux).
responseStatus

string

État de la réponse du participant. Valeurs possibles :

  • needsAction : le participant n'a pas répondu à l'invitation (recommandé pour les nouveaux événements).
  • declined : le participant a refusé l'invitation.
  • tentative : le participant a accepté provisoirement l'invitation.
  • accepted : le participant a accepté l'invitation.
comment

string

Commentaire de la réponse du participant. Facultatif.
additionalGuests

integer

Nombre d'invités supplémentaires. Facultatif. La valeur par défaut est 0.

Annotations d'outils

Indication destructive : ❌ | Indication idempotente : ✅ | Indication en lecture seule : ✅ | Indication Open World : ❌