MCP Tools Reference: calendarmcp.googleapis.com

Tool: list_events

Gibt Termine im angegebenen Kalender zurück, die allen angegebenen Einschränkungen entsprechen. Zeitliche Einschränkungen sollten nur angegeben werden, wenn der Nutzer dies wünscht. Für offene Keyword- oder themenbasierte Suchanfragen im primären Kalender muss stattdessen das Tool „search_events“ verwendet werden.

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

Curl-Anfrage 
curl --location 'https://calendarmcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--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
  ],
  "eventType": [
    enum (EventType)
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Felder
eventTypeFilter[]
(deprecated)

string

Optional. Verworfen. Verwenden Sie stattdessen event_type.
eventType[]

enum (EventType)

Optional. Die Ereignistypen, die zurückgegeben werden sollen. Wenn leer, werden nur die folgenden Ereignistypen zurückgegeben: DEFAULT, OUT_OF_OFFICE, FOCUS_TIME, FROM_GMAIL.

Union-Feld _calendar_id.

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

string

Optional. ID des Kalenders mit den Terminen. E‑Mail-Adresse – kann mit list_calendars aufgelöst werden. Standard: primärer Kalender.

Union-Feld _page_size.

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

integer

Optional. Maximale Anzahl von Ereignissen pro Seite (Standardwert: 100, Maximalwert: 250). Empfohlen: 10.

Union-Feld _page_token.

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

string

Optional. Token für nächste Seite Verwenden Sie den Wert aus nextPageToken auf der vorherigen Seite.

Union-Feld _start_time.

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

string

Optional. Die Untergrenze eines Zeitraums. Darf nur festgelegt werden, wenn der Nutzer einen bestimmten Zeitraum angibt. Muss ein ISO 8601-Zeitstempel sein, der kleiner als end_time ist.

Union-Feld _end_time.

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

string

Optional. Die Obergrenze eines Zeitraums. Muss nur festgelegt werden, wenn der Nutzer einen bestimmten Zeitraum oder eine Zeit in der Vergangenheit angibt. Muss ein ISO 8601-Zeitstempel sein, der größer als start_time ist.

Union-Feld _time_zone.

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

string

Optional. Zeitzone (IANA-ID, z. B. Europe/Zurich), die zum Auflösen von Datumsangaben ohne Zeitzone verwendet wird. Standard: Zeitzone des Kalenders.

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 absteigend sortieren.
  • lastModified: Nach aufsteigender Zeit der letzten Änderung sortieren.

Union-Feld _full_text.

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

string

Optional. Freiformsuche ohne Berücksichtigung der Groß-/Kleinschreibung, die mit Titel, Beschreibung, Ort oder Teilnehmern übereinstimmt. Es werden Ereignisse zurückgegeben, die alle Suchbegriffe exakt enthalten (UND-Suche).

EventType

Ereignistyp Nach der Erstellung nicht mehr veränderbar.

Enums
EVENT_TYPE_UNSPECIFIED Wird als DEFAULT behandelt.
DEFAULT Regelmäßig stattfindender Termin. Standardwert.
OUT_OF_OFFICE Außer-Haus-Termin.
FOCUS_TIME Fokuszeit-Termin
WORKING_LOCATION Termin am Arbeitsort
BIRTHDAY Besonderes ganztägiges Event, das jährlich wiederkehrt.
FROM_GMAIL Termin aus Gmail. Dieser Ereignistyp kann nicht erstellt werden.

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

Uhrzeit der letzten Aktualisierung des Kalenders (ISO 8601).
timeZone

string

Zeitzone des Kalenders.
accessRole

string

Nur Ausgabe. Die Zugriffsrolle des Nutzers für den Kalender. Folgende Werte sind möglich:

  • none – Kein Zugriff.
  • freeBusyReader – Lesezugriff auf Verfügbarkeitsdaten.
  • reader – Lesezugriff auf den Kalender. Private Termine werden angezeigt, Termindetails sind jedoch ausgeblendet.
  • writer – Lese- und Schreibzugriff. Private Termine werden angezeigt und Termindetails sind sichtbar.
  • owner – Managerzugriff, einschließlich der Möglichkeit, die Freigabeeinstellungen des Kalenders zu ändern.
Wichtig: Die Rolle owner unterscheidet sich vom Dateninhaber des Kalenders. Ein Kalender hat einen einzelnen Dateninhaber, kann aber mehrere Nutzer mit der Rolle owner haben.
defaultReminders[]

object (Reminder)

Standarderinnerungen für Termine im Kalender
events[]

object (Event)

Liste der Ereignisse.

Union-Feld _next_page_token.

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

string

Token für nächste Seite Wird weggelassen, wenn keine nächste Seite vorhanden ist.

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. Die Schaltungsmethode. 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. Minuten vor dem Termin, zu dem die Erinnerung ausgelöst wird.

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)
    }
  ],
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ],
  "attachments": [
    {
      object (Attachment)
    }
  ],
  "guestPermissions": {
    object (GuestPermissions)
  },
  "eventType": enum (EventType),
  "workingLocationProperties": {
    object (WorkingLocationProperties)
  },
  "availability": enum (Availability)
}
Felder
id

string

Eindeutige Kennung.
status

string

Optional. Status aus. Folgende Werte sind möglich:

  • confirmed: Der Termin ist bestätigt (Standard).
  • tentative: Der Termin ist vorläufig bestätigt.
  • cancelled – Das Event wurde abgesagt oder gelöscht.
htmlLink

string

Nur Ausgabe. Ein absoluter Link zu diesem Termin in der Google Kalender-Web-UI.
created

string

Nur Ausgabe. Erstellungszeit (ISO 8601).
updated

string

Nur Ausgabe. Letzte Änderung (ISO 8601).
summary

string

Titel
description

string

Optional. Beschreibung: Kann HTML enthalten.
location

string

Optional. Standort.
creator

object (Principal)

Nur Ausgabe. Creator
organizer

object (Principal)

Nur Ausgabe. Organisator Wenn Sie teilnehmen, werden Sie auch in der Liste der Teilnehmer aufgeführt.
start

object (DateOrDateTime)

Beginn (einschließlich). Bei wiederkehrenden Ereignissen wird die erste Instanz verwendet.
end

object (DateOrDateTime)

Endzeit (ausschließlich). Bei wiederkehrenden Terminen wird die erste Instanz verwendet.
recurrence[]

string

Wiederholungsregeln als RRULE-, EXRULE-, RDATE- oder EXDATE-Strings (gemäß RFC 5545). Bei einzelnen Ereignissen wird sie nicht angegeben. Die Start- und Endzeit muss in den Feldern start/end festgelegt werden.
recurringEventId

string

ID des übergeordneten wiederkehrenden Termins für Instanzen von wiederkehrenden Terminen.
originalStartTime

object (DateOrDateTime)

Ursprüngliche Startzeit von wiederkehrenden Instanzen. Dies ist die Uhrzeit, zu der diese Instanz gemäß den Daten für wiederkehrende Termine beginnen würde.
transparency
(deprecated)

string

Optional. Verworfen. Verwenden Sie stattdessen availability.
visibility

string

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

  • default: Die Standardsichtbarkeit für Termine im Kalender wird verwendet. „Immer“ ist der Standardwert.
  • public: Termindetails sind für alle Leser des Kalenders sichtbar.
  • private: Nur Teilnehmer der Veranstaltung können die Termindetails sehen.

attendees[]

object (Attendee)

Teilnehmer
conferenceUrl

string

Link zur Videokonferenz.
colorId

string

Die Farbe des Ereignisses. Wirkt sich nur auf Ihre eigene Kalenderansicht aus. Dies ist eine ID, die sich auf einen Eintrag in der Farbpalette des Kalenders bezieht (String '1'–'11'):

  • 1: Lavendel
  • 2: Salbei
  • 3: Grape
  • 4: Flamingo
  • 5: Banane
  • 6: Mandarine
  • 7: Peacock
  • 8: Graphite
  • 9: Blaubeere
  • 10: Basilikum
  • 11: Tomato.

overrideReminders[]

object (Reminder)

Erinnerungen. Wenn kein Wert festgelegt ist, wird auf die Kalendereinstellungen zurückgegriffen.
attachments[]

object (Attachment)

Dateianhänge
guestPermissions

object (GuestPermissions)

Berechtigungen für Gäste.
eventType

enum (EventType)

Ereignistyp
workingLocationProperties

object (WorkingLocationProperties)

Eigenschaften des Arbeitsorts. Wird nur ausgefüllt, wenn event_type WORKING_LOCATION ist.
availability

enum (Availability)

Optional. Verfügbarkeitseinstellung

Hauptkonto

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

string

E‑Mail-Adresse
displayName

string

Name
self

boolean

Nur Ausgabe. Gibt an, ob dieses Prinzipal dem Kalender entspricht, in dem diese Kopie des Termins angezeigt wird. Standard: false.

DateOrDateTime

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

string

ISO 8601-Datum um Mitternacht UTC (z. B. '2019-11-20T00:00:00Z').
dateTime

string

ISO 8601-Zeitstempel (z. B. '2019-11-20T08:19:06-07:00').
timeZone

string

TZDB-Zeitzonenname.

Teilnehmer

JSON-Darstellung 
{

  "id": string

  "email": string

  "displayName": string

  "organizer": boolean

  "self": boolean

  "resource": boolean

  "optionalAttendee": boolean

  "responseStatus": string

  "comment": string

  "additionalGuests": integer
}
Felder

Union-Feld _id.

Für _id ist nur einer der folgenden Werte zulässig:
id

string

Nur Ausgabe. Profil-ID.

Union-Feld _email.

Für _email ist nur einer der folgenden Werte zulässig:
email

string

Erforderlich. E-Mail-Adresse des Teilnehmers.

Union-Feld _display_name.

Für _display_name ist nur einer der folgenden Werte zulässig:
displayName

string

Optional. Name

Union-Feld _organizer.

Für _organizer ist nur einer der folgenden Werte zulässig:
organizer

boolean

Nur Ausgabe. Gibt an, ob der Teilnehmer der Organisator ist. Standard: false.

Union-Feld _self.

Für _self ist nur einer der folgenden Werte zulässig:
self

boolean

Nur Ausgabe. Gibt an, ob dieser Eintrag den Kalender darstellt, in dem diese Kopie des Termins angezeigt wird. Standard: false.

Union-Feld _resource.

Für _resource ist nur einer der folgenden Werte zulässig:
resource

boolean

Optional. Gibt an, ob der Teilnehmer eine Ressource ist (z. B. ein Raum). Unveränderlich, kann nur beim ersten Hinzufügen des Teilnehmers festgelegt werden. Standard: false.

Union-Feld _optional_attendee.

Für _optional_attendee ist nur einer der folgenden Werte zulässig:
optionalAttendee

boolean

Optional. Gibt an, ob der Teilnehmer optional ist. Standard: false.

Union-Feld _response_status.

Für _response_status ist nur einer der folgenden Werte zulässig:
responseStatus

string

Optional. Antwortstatus. Folgende Werte sind möglich:

  • needsAction – Der Teilnehmer hat noch nicht auf die Einladung geantwortet (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.

Union-Feld _comment.

Für _comment ist nur einer der folgenden Werte zulässig:
comment

string

Nur Ausgabe. Kommentar zur Antwort.

Union-Feld _additional_guests.

Für _additional_guests ist nur einer der folgenden Werte zulässig:
additionalGuests

integer

Optional. Anzahl der zusätzlichen Gäste. Standard: 0.

Anhang

JSON-Darstellung 
{

  "fileUrl": string

  "title": string
}
Felder

Union-Feld _file_url.

Für _file_url ist nur einer der folgenden Werte zulässig:
fileUrl

string

Erforderlich. URL-Link zum Anhang.

Union-Feld _title.

Für _title ist nur einer der folgenden Werte zulässig:
title

string

Optional. Titel des Anhangs.

GuestPermissions

JSON-Darstellung 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
Felder

Union-Feld _guests_can_invite_others.

Für _guests_can_invite_others ist nur einer der folgenden Werte zulässig:
guestsCanInviteOthers

boolean

Optional. Ob Gäste andere einladen können.

Union-Feld _guests_can_modify.

Für _guests_can_modify ist nur einer der folgenden Werte zulässig:
guestsCanModify

boolean

Optional. Gäste können den Termin bearbeiten.

Union-Feld _guests_can_see_guests.

Für _guests_can_see_guests ist nur einer der folgenden Werte zulässig:
guestsCanSeeGuests

boolean

Optional. Ob Gäste andere Gäste sehen können.

WorkingLocationProperties

JSON-Darstellung 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
Felder

Union-Feld _type.

Für _type ist nur einer der folgenden Werte zulässig:
type

enum (WorkingLocationType)

Optional. Typ des Arbeitsorts.

Union-Feld _custom_location_label.

Für _custom_location_label ist nur einer der folgenden Werte zulässig:
customLocationLabel

string

Optional. Das Label für einen benutzerdefinierten Standort. Erforderlich, wenn der Typ CUSTOM_LOCATION ist.

EventType

Ereignistyp Nach der Erstellung nicht mehr veränderbar.

Enums
EVENT_TYPE_UNSPECIFIED Wird als DEFAULT behandelt.
DEFAULT Regelmäßig stattfindender Termin. Standardwert.
OUT_OF_OFFICE Außer-Haus-Termin.
FOCUS_TIME Fokuszeit-Termin
WORKING_LOCATION Termin am Arbeitsort
BIRTHDAY Besonderes ganztägiges Event, das jährlich wiederkehrt.
FROM_GMAIL Termin aus Gmail. Dieser Ereignistyp kann nicht erstellt werden.

WorkingLocationType

Art des Arbeitsorts.

Enums
WORKING_LOCATION_TYPE_UNSPECIFIED Nicht angegebener Arbeitsorttyp. Wird als HOME_OFFICE behandelt.
HOME_OFFICE Home office.
CUSTOM_LOCATION Benutzerdefinierter Standort

Verfügbarkeit

Verfügbarkeitseinstellung für ein Ereignis.

Enums
AVAILABILITY_UNSPECIFIED Standard. Wird als BUSY behandelt.
AVAILABILITY_BUSY Blockiert Zeit im Kalender.
AVAILABILITY_FREE Es wird keine Zeit blockiert.

Tool-Annotationen

Destruktiver Hinweis: ❌ | Idempotenter Hinweis: ✅ | Hinweis „Nur lesen“: ✅ | Hinweis „Offene Welt“: ❌

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • https://www.googleapis.com/auth/calendar
  • https://www.googleapis.com/auth/calendar.events
  • https://www.googleapis.com/auth/calendar.events.readonly
  • https://www.googleapis.com/auth/calendar.readonly