MCP Tools Reference: calendarmcp.googleapis.com

Tool: list_events

Listet Kalendertermine in einem bestimmten Kalender auf, die die angegebenen Bedingungen erfüllen.

Wichtigste Funktionen:

  • Eine beliebige Kalender-ID, z. B. der primäre Kalender des Nutzers oder andere Kalender.
  • Filtern nach Zeitraum
  • Ruft ALLE Ereignisse ab, die den Zeitbeschränkungen entsprechen.

Verwenden Sie stattdessen das Tool „search_events“ für Suchanfragen im primären Kalender des Nutzers, wenn:

  • Sie fragen nach Ereignissen ab, die einem bestimmten Thema, einer bestimmten Kategorie oder einer bestimmten Absicht entsprechen (z.B. „Mittagsbesprechungen“, „Projektabstimmungen“).
  • Sie müssen die (K) relevantesten Ereignisse und nicht alle Ereignisse finden, die die Einschränkungen erfüllen.
  • Sie benötigen Funktionen für die Keyword- oder semantische Suche.

Verwenden Sie dieses Tool für Abfragen wie:

  • Was steht morgen in meinem Kalender?
  • Welche Termine stehen am 14. Juli 2025 an?
  • Welche Besprechungen habe ich nächste Woche?
  • Habe ich heute Nachmittag Terminkonflikte?

  • Welche Besprechungen hat Max morgen?

Beispiel:

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.

Im folgenden Beispiel wird gezeigt, wie Sie mit curl das MCP-Tool list_events aufrufen.

Curl-Anfrage 
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
}'

Eingabeschema

ListEventsRequest

JSON-Darstellung 
{
  "eventTypeFilter": [
    string
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Felder
eventTypeFilter[]

string

Optional. Die Ereignistypen, die zurückgegeben werden sollen. Folgende Werte sind möglich:

  • default: Regelmäßige Ereignisse (Standard).
  • outOfOffice – Außer-Haus-Termine.
  • focusTime – Fokuszeittermine.
  • workingLocation – Ereignisse zum Arbeitsort.
  • birthday – Geburtstagsereignisse
  • fromGmail – Termine aus Gmail

Wenn leer, werden nur die folgenden Ereignistypen zurückgegeben: default, outOfOffice, focusTime, fromGmail.

Union-Feld _calendar_id.

Für _calendar_id ist nur einer der folgenden Werte zulässig:
calendarId

string

Optional. Die Kalender-ID, aus der Termine aufgelistet werden sollen. Standardmäßig wird der primäre Kalender des Nutzers verwendet.

Union-Feld _page_size.

Für _page_size ist nur einer der folgenden Werte zulässig:
pageSize

integer

Optional. Maximale Anzahl von Ereignissen, die auf einer Ergebnisseite zurückgegeben werden. Die Anzahl der Ereignisse auf der resultierenden Seite kann geringer als dieser Wert sein oder sogar null betragen, auch wenn es mehr Ereignisse gibt, die der Anfrage entsprechen. Unvollständige Seiten können durch ein nicht leeres Feld next_page_token in der Antwort erkannt werden. Der Standardwert ist 250 Ereignisse. Die Seitengröße darf nie mehr als 2.500 Ereignisse umfassen.

Union-Feld _page_token.

Für _page_token ist nur einer der folgenden Werte zulässig:
pageToken

string

Optional. Token, das angibt, welche Ergebnisseite zurückgegeben werden soll.

Union-Feld _start_time.

Für _start_time ist nur einer der folgenden Werte zulässig:
startTime

string

Optional. Untergrenze (exklusiv) für die Endzeit eines Ereignisses. Es werden nur Termine zurückgegeben, die nach diesem Zeitpunkt enden (d.h. der Beginn des Zeitfensters für die Suche). Wenn weder start_time noch end_time angegeben wird, wird standardmäßig die aktuelle Uhrzeit verwendet. Falls angegeben, muss der Wert kleiner oder gleich end_time sein. Muss ein ISO 8601-Zeitstempel sein. Beispiele: 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z oder 2026-06-03T10:00:00. Millisekunden können angegeben werden, werden aber ignoriert.

Union-Feld _end_time.

Für _end_time ist nur einer der folgenden Werte zulässig:
endTime

string

Optional. Exklusive Obergrenze für die Startzeit eines Ereignisses. Es werden nur Ereignisse zurückgegeben, die vor diesem Zeitpunkt beginnen (d.h. das Ende des zu durchsuchenden Zeitfensters). Falls angegeben, muss der Wert größer oder gleich start_time sein. Muss ein ISO 8601-Zeitstempel sein. Beispiele: 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z oder 2026-06-03T10:00:00. Millisekunden können angegeben werden, werden aber ignoriert.

Union-Feld _time_zone.

Für _time_zone ist nur einer der folgenden Werte zulässig:
timeZone

string

Optional. Die in der Antwort verwendete Zeitzone und die Zeitzone, die zum Auflösen von datumsbezogenen Angaben ohne Zeitzone in der Anfrage verwendet wird (formatiert als Name der IANA-Zeitzonendatenbank, z.B. Europe/Zurich). Standardmäßig wird die Zeitzone des Kalenders verwendet.

Union-Feld _order_by.

Für _order_by ist nur einer der folgenden Werte zulässig:
orderBy

string

Optional. Die Reihenfolge, in der Ereignisse zurückgegeben werden sollen. Folgende Werte sind möglich:

  • default: Nicht angegeben, aber deterministische Reihenfolge (Standard).
  • startTime: Nach Startzeit aufsteigend sortieren.
  • startTimeDesc: Nach Startzeit in absteigender Reihenfolge sortieren.
  • lastModified: Nach Zeit der letzten Änderung aufsteigend sortieren.

Union-Feld _full_text.

Für _full_text ist nur einer der folgenden Werte zulässig:
fullText

string

Optional. Freiform-Suchanfrage, mit der Sie Titel, Beschreibung, Ort und Teilnehmer durchsuchen können.

Ausgabeschema

ListEventsResponse

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

  "nextPageToken": string
}
Felder
summary

string

Titel des Kalenders.
description

string

Beschreibung des Kalenders.
updated

string

Zeitpunkt der letzten Änderung des Kalenders (als ISO 8601-Zeitstempel).
timeZone

string

Die Zeitzone des Kalenders.
accessRole

string

Die Zugriffsrolle des Nutzers für diesen Kalender. Schreibgeschützt. Folgende Werte sind möglich:

  • none: Der Nutzer hat keinen Zugriff.
  • freeBusyReader: Der Nutzer hat Lesezugriff auf Verfügbarkeitsdaten.
  • reader: Der Nutzer hat Lesezugriff auf den Kalender. Private Termine werden Nutzern mit Lesezugriff angezeigt, Termindetails sind jedoch ausgeblendet.
  • writer: Der Nutzer hat Lese- und Schreibzugriff auf den Kalender. Private Termine werden Nutzern mit Schreibzugriff angezeigt und Termindetails sind sichtbar.
  • owner: Der Nutzer hat Zugriff auf den Kalender als Administrator. Diese Rolle hat alle Berechtigungen der Rolle „Autor“ und kann zusätzlich die Zugriffsebenen anderer Nutzer aufrufen und ändern. Wichtig: Die Rolle „Inhaber“ unterscheidet sich vom Dateninhaber des Kalenders. Ein Kalender hat einen einzelnen Dateninhaber, kann aber mehrere Nutzer mit der Rolle „Inhaber“ haben.
defaultReminders[]

object (Reminder)

Die Standarderinnerungen im Kalender für den authentifizierten Nutzer. Diese Erinnerungen gelten für alle Termine in diesem Kalender, für die sie nicht explizit überschrieben werden (d.h. für die „override_reminders“ nicht ausgefüllt ist).
events[]

object (Event)

Liste der Termine im Kalender.

Union-Feld _next_page_token.

Für _next_page_token ist nur einer der folgenden Werte zulässig:
nextPageToken

string

Token für den Zugriff auf die nächste Seite dieses Ergebnisses. Wird weggelassen, wenn keine weiteren Ergebnisse verfügbar sind.

Erinnerung

JSON-Darstellung 
{

  "method": string

  "minutes": integer
}
Felder

Union-Feld _method.

Für _method ist nur einer der folgenden Werte zulässig:
method

string

Erforderlich. Wie die Erinnerung an den Nutzer gesendet wird. Folgende Werte sind möglich:

  • email: Erinnerungen werden per E‑Mail gesendet.
  • popup: Erinnerungen werden über ein Pop-up in der Benutzeroberfläche gesendet.

Union-Feld _minutes.

Für _minutes ist nur einer der folgenden Werte zulässig:
minutes

integer

Erforderlich. Anzahl der Minuten vor dem Termin, zu dem die Erinnerung gesendet werden soll.

Ereignis

JSON-Darstellung 
{
  "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)
    }
  ]
}
Felder
id

string

Opake Kennung des Ereignisses. Wenn Sie neue einmalige oder wiederkehrende Ereignisse erstellen, können Sie deren IDs angeben. Die bereitgestellten IDs müssen den folgenden Regeln entsprechen:

  • Die in der ID zulässigen Zeichen sind die, die in der base32hex-Codierung verwendet werden, d. h. Kleinbuchstaben a–v und Ziffern 0–9 (siehe Abschnitt 3.1.2 in RFC2938).
  • Die ID muss zwischen 5 und 1.024 Zeichen lang sein.
  • Die ID muss pro Kalender eindeutig sein.

Da das System weltweit verteilt ist, können wir nicht garantieren, dass ID-Kollisionen bei der Ereigniserstellung erkannt werden. Um das Risiko von Kollisionen zu minimieren, empfehlen wir die Verwendung eines etablierten UUID-Algorithmus, z. B. eines in RFC4122 beschriebenen.

Wenn Sie keine ID angeben, wird sie automatisch vom Server generiert.

Beachten Sie, dass icalUID und ID nicht identisch sind und nur eine von beiden beim Erstellen des Termins angegeben werden sollte. Ein semantischer Unterschied besteht darin, dass alle Instanzen eines wiederkehrenden Termins unterschiedliche IDs, aber dieselben icalUIDs haben.
status

string

Status des Ereignisses. Optional. Folgende Werte sind möglich:

  • confirmed: Der Termin wurde bestätigt. Das ist der Standardstatus.
  • tentative: Der Termin ist vorläufig bestätigt.
  • cancelled: Die Veranstaltung wurde abgesagt (gelöscht). Die Listenmethode gibt stornierte Ereignisse nur bei der inkrementellen Synchronisierung (wenn syncToken oder updatedMin angegeben sind) oder wenn das Flag showDeleted auf „true“ gesetzt ist zurück. Die Methode „get“ gibt sie immer zurück.

Der Status „Abgebrochen“ kann je nach Ereignistyp zwei verschiedene Status darstellen:

  1. Abgesagte Ausnahmen eines nicht abgesagten wiederkehrenden Termins deuten darauf hin, dass diese Instanz dem Nutzer nicht mehr präsentiert werden sollte. Clients sollten diese Ereignisse für die gesamte Dauer des übergeordneten wiederkehrenden Ereignisses speichern.Bei abgesagten Ausnahmen sind nur die Felder „id“, „recurringEventId“ und „originalStartTime“ garantiert ausgefüllt. Die anderen Felder sind möglicherweise leer.
  2. Alle anderen abgesagten Termine sind gelöschte Termine. Kunden sollten ihre lokal synchronisierten Kopien entfernen. Solche abgesagten Veranstaltungen verschwinden irgendwann. Verlassen Sie sich also nicht darauf, dass sie auf unbestimmte Zeit verfügbar sind. Bei gelöschten Ereignissen ist garantiert nur das Feld „id“ ausgefüllt.

Im Kalender des Organisators werden für abgesagte Termine weiterhin Termindetails (Zusammenfassung, Ort usw.) angezeigt, damit sie wiederhergestellt werden können. Ebenso werden weiterhin Details zu den Ereignissen bereitgestellt, zu denen der Nutzer eingeladen wurde und die er manuell entfernt hat. Bei inkrementellen Synchronisierungsanfragen, bei denen „showDeleted“ auf „false“ gesetzt ist, werden diese Details jedoch nicht zurückgegeben.

Wenn sich der Organisator eines Termins ändert (z. B. durch die Verschiebeoperation) und der ursprüngliche Organisator nicht in der Teilnehmerliste enthalten ist, wird ein abgesagter Termin zurückgelassen, bei dem nur das Feld „id“ garantiert ausgefüllt ist.
htmlLink

string

Ein absoluter Link zu diesem Termin in der Google Kalender-Web-UI. Schreibgeschützt.
created

string

Erstellungszeit des Ereignisses (als ISO 8601-formatierter Zeitstempel). Schreibgeschützt.
updated

string

Zeitpunkt der letzten Änderung der Hauptereignisdaten (als ISO 8601-formatierter Zeitstempel). Das Aktualisieren von Terminerinnerungen führt nicht zu einer Änderung. Schreibgeschützt.
summary

string

Titel der Veranstaltung.
description

string

Beschreibung der Veranstaltung. Kann HTML enthalten. Optional.
location

string

Der geografische Standort des Ereignisses als Freitext. Optional.
creator

object (Principal)

Der Ersteller des Ereignisses. Schreibgeschützt.
organizer

object (Principal)

Der Organisator des Termins. Wenn der Organisator auch ein Teilnehmer ist, wird dies durch einen separaten Eintrag unter „attendees“ angezeigt, bei dem das Feld „organizer“ auf „True“ gesetzt ist. Schreibgeschützt.
start

object (DateOrDateTime)

Die (inklusive) Startzeit des Ereignisses. Bei einem wiederkehrenden Termin ist dies die Startzeit der ersten Instanz.
end

object (DateOrDateTime)

Die (ausgeschlossene) Endzeit des Ereignisses. Bei einem wiederkehrenden Termin ist dies die Endzeit des ersten Termins.
recurrence[]

string

Liste der RRULE-, EXRULE-, RDATE- und EXDATE-Zeilen für ein wiederkehrendes Ereignis, wie in RFC5545 angegeben. Die Zeilen DTSTART und DTEND sind in diesem Feld nicht zulässig. Start- und Endzeiten von Terminen werden in den Feldern „Start“ und „Ende“ angegeben. Dieses Feld wird für einzelne Ereignisse oder Instanzen wiederkehrender Ereignisse ausgelassen.
recurringEventId

string

Bei einer Instanz eines wiederkehrenden Termins ist dies die ID des wiederkehrenden Termins, zu dem diese Instanz gehört. Nicht veränderbar.
originalStartTime

object (DateOrDateTime)

Für eine Instanz eines wiederkehrenden Termins ist dies die Uhrzeit, zu der dieser Termin gemäß den Wiederholungsdaten im wiederkehrenden Termin mit der ID „recurringEventId“ beginnen würde. Sie identifiziert die Instanz innerhalb der Reihe wiederkehrender Termine eindeutig, auch wenn die Instanz auf eine andere Zeit verschoben wurde. Nicht veränderbar.
transparency

string

Gibt an, ob der Termin Zeit im Kalender blockiert. Optional. Folgende Werte sind möglich:

  • opaque – Standardwert. Der Termin blockiert Zeit im Kalender. Dies entspricht der Einstellung „Als beschäftigt anzeigen“ in der Kalender-Benutzeroberfläche.
  • transparent: Der Termin blockiert keine Zeit im Kalender. Das entspricht der Einstellung „Als verfügbar anzeigen“ in der Kalender-Benutzeroberfläche.
visibility

string

Sichtbarkeit des Ereignisses. Optional. Folgende Werte sind möglich:

  • default: Hier wird die Standardsichtbarkeit für Termine im Kalender verwendet. Das ist der Standardwert.
  • public: Der Termin ist öffentlich und Termindetails sind für alle Leser des Kalenders sichtbar.
  • private: Der Termin ist privat und nur die Teilnehmer können die Termindetails sehen.
  • confidential: Das Ereignis ist privat. Dieser Wert wird aus Kompatibilitätsgründen angegeben.
attendees[]

object (Attendee)

Die Teilnehmer der Veranstaltung.
eventType

string

Die genaue Art des Ereignisses. Dies kann nach dem Erstellen des Ereignisses nicht mehr geändert werden. Folgende Werte sind möglich:

  • birthday: Ein besonderes ganztägiges Ereignis, das jährlich wiederkehrt.
  • default – Ein reguläres Ereignis oder nicht weiter angegeben.
  • focusTime: Ein Fokuszeittermin.
  • fromGmail – Ein Termin aus Gmail. Dieser Ereignistyp kann nicht erstellt werden.
  • outOfOffice: Ein Außer-Haus-Termin.
  • workingLocation: Ein Ereignis für den Arbeitsort.
conferenceUrl

string

Der Google Meet-Link für den Termin.
colorId

string

Ereignisfarb-ID (String 1–11):

  • 1: Lavendel
  • 2: Sage
  • 3: Traube
  • 4. Flamingo
  • 5: Banane
  • 6: Mandarine
  • 7: Pfau
  • 8: Graphite
  • 9. Blaubeere
  • 10: Basilikum
  • 11: Tomate

In Google Kalender dienen Terminfarben als Kategorien, die pro Termin oder pro Terminserie festgelegt werden können. Nutzer können Farben in der Web-UI benutzerdefinierte Labels zuweisen (z. B. 1:1s, Break). Die API stellt jedoch nur numerische IDs und nicht diese Labels zur Verfügung. Wirkt sich nur auf Ihre eigene Kalenderansicht aus. Jeder Teilnehmer kann die Farbe des Termins selbst festlegen.
overrideReminders[]

object (Reminder)

Für dieses Ereignis definierte Erinnerungen, die die Standarderinnerungen für den Kalender überschreiben. Wenn nicht festgelegt, werden die Standarderinnerungen im Kalender verwendet.

Hauptkonto

JSON-Darstellung 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Felder
email

string

E-Mail-Adresse des Hauptkontos (Kalender).
displayName

string

Der Name des Auftraggebers, falls verfügbar.
self

boolean

Gibt an, ob dieses Prinzipal dem Kalender entspricht, in dem diese Kopie des Termins angezeigt wird. Schreibgeschützt. Die Standardeinstellung ist "False".

DateOrDateTime

JSON-Darstellung 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Felder
date

string

Ein im ISO 8601-Format angegebenes Datum um Mitternacht UTC, z. B. 2019-11-20T00:00:00Z. Wenn dieses Feld festgelegt ist, darf date_time nicht festgelegt werden.
dateTime

string

Ein Zeitstempel im ISO 8601-Format, z. B. 2019-11-20T08:19:06-07:00 oder 2019-11-20T08:19:06Z. Wenn dieses Feld festgelegt ist, darf date nicht festgelegt werden.
timeZone

string

TZDB-Zeitzonenname, falls verfügbar.

Gast

JSON-Darstellung 
{
  "id": string,
  "email": string,
  "displayName": string,
  "organizer": boolean,
  "self": boolean,
  "resource": boolean,
  "optionalAttendee": boolean,
  "responseStatus": string,
  "comment": string,
  "additionalGuests": integer
}
Felder
id

string

Die Profil-ID des Teilnehmers, falls verfügbar.
email

string

Die E‑Mail-Adresse des Teilnehmers, sofern verfügbar. Dieses Feld muss beim Hinzufügen eines Teilnehmers angegeben werden. Es muss eine gültige E-Mail-Adresse gemäß RFC5322 sein. Erforderlich, wenn ein Teilnehmer hinzugefügt wird.
displayName

string

Der Name des Teilnehmers, falls verfügbar. Optional.
organizer

boolean

Gibt an, ob der Teilnehmer der Organisator des Termins ist. Schreibgeschützt. Die Standardeinstellung ist "False".
self

boolean

Gibt an, ob dieser Eintrag den Kalender darstellt, in dem diese Kopie des Termins angezeigt wird. Schreibgeschützt. Die Standardeinstellung ist "False".
resource

boolean

Gibt an, ob der Teilnehmer eine Ressource ist. Kann nur festgelegt werden, wenn der Teilnehmer dem Termin zum ersten Mal hinzugefügt wird. Nachfolgende Änderungen werden ignoriert. Optional. Die Standardeinstellung ist "False".
optionalAttendee

boolean

Gibt an, ob es sich um einen optionalen Teilnehmer handelt. Optional. Die Standardeinstellung ist "False".
responseStatus

string

Der Antwortstatus des Teilnehmers. Folgende Werte sind möglich:

  • needsAction: Der Teilnehmer hat nicht auf die Einladung reagiert (empfohlen für neue Termine).
  • declined: Der Teilnehmer hat die Einladung abgelehnt.
  • tentative: Der Teilnehmer hat die Einladung vorläufig angenommen.
  • accepted: Der Teilnehmer hat die Einladung angenommen.
comment

string

Der Antwortkommentar des Teilnehmers. Optional.
additionalGuests

integer

Anzahl der zusätzlichen Gäste. Optional. Der Standardwert ist 0.

Tool-Annotationen

Destruktiver Hinweis: ❌ | Idempotenter Hinweis: ✅ | Nur-Lese-Hinweis: ✅ | Open-World-Hinweis: ❌