MCP Tools Reference: calendarmcp.googleapis.com

Narzędzie: list_events

Wyświetla listę wydarzeń w danym kalendarzu, które spełniają określone warunki.

Najważniejsze funkcje:

  • Dowolny identyfikator kalendarza, który może być kalendarzem głównym użytkownika lub innym kalendarzem.
  • Filtrowanie według zakresu czasu.
  • Pobiera WSZYSTKIE zdarzenia spełniające ograniczenia czasowe.

Jeśli jest dostępny, użyj narzędzia search_events do wyszukiwania w kalendarzu głównym użytkownika, gdy:

  • Wyszukujesz wydarzenia pasujące do określonego tematu, kategorii lub intencji (np. „spotkania przy lunchu”, „synchronizacja projektu”).
  • Musisz znaleźć (K) najbardziej odpowiednich zdarzeń, a nie wszystkich zdarzeń spełniających ograniczenia.
  • Potrzebujesz funkcji wyszukiwania słów kluczowych lub wyszukiwania semantycznego.

Używaj tego narzędzia w przypadku zapytań takich jak:

  • Co mam jutro w kalendarzu?
  • Co mam w kalendarzu na 14 lipca 2025 roku?
  • Jakie spotkania mam w przyszłym tygodniu?
  • Czy mam jakieś konflikty w tym popołudniu?

  • Jakie spotkania ma jutro Jan?

Przykład:

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.

Poniższy przykład pokazuje, jak za pomocą znaku curl wywołać narzędzie list_events MCP.

Żądanie 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
}'

Schemat wejściowy

ListEventsRequest

Zapis JSON 
{
  "eventTypeFilter": [
    string
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Pola
eventTypeFilter[]

string

Opcjonalnie. Typy zdarzeń do zwrócenia. Możliwe wartości to:

  • default – zwykłe wydarzenia (domyślne).
  • outOfOffice – wydarzenia poza biurem;
  • focusTime – wydarzenia typu czas skupienia.
  • workingLocation – zdarzenia dotyczące lokalizacji miejsca pracy.
  • birthday – wydarzenia związane z urodzinami.
  • fromGmail – Wydarzenia z Gmaila.

Jeśli to pole jest puste, zwracane są tylko te typy zdarzeń: default, outOfOffice, focusTime, fromGmail

Pole zbiorcze _calendar_id.

Pole _calendar_id może mieć tylko jedną z tych wartości:
calendarId

string

Opcjonalnie. Identyfikator kalendarza, z którego mają być wyświetlane wydarzenia. Domyślnie jest to kalendarz główny użytkownika.

Pole zbiorcze _page_size.

Pole _page_size może mieć tylko jedną z tych wartości:
pageSize

integer

Opcjonalnie. Maksymalna liczba zdarzeń zwracanych na jednej stronie wyników. Liczba zdarzeń na stronie wyników może być mniejsza od tej wartości lub może nie być ich wcale, nawet jeśli istnieje więcej zdarzeń pasujących do zapytania. Niekompletne strony można wykryć za pomocą niepustego pola next_page_token w odpowiedzi. Domyślna wartość to 250 zdarzeń. Rozmiar strony nigdy nie może przekraczać 2500 zdarzeń.

Pole zbiorcze _page_token.

Pole _page_token może mieć tylko jedną z tych wartości:
pageToken

string

Opcjonalnie. Token określający, którą stronę wyników należy zwrócić.

Pole zbiorcze _start_time.

Pole _start_time może mieć tylko jedną z tych wartości:
startTime

string

Opcjonalnie. Dolna granica (wyłączna) czasu zakończenia wydarzenia. Zwracane są tylko wydarzenia, które kończą się po tym czasie (czyli początek przedziału czasu, w którym należy szukać). Jeśli nie podano wartości start_time ani end_time, domyślnie jest to bieżący czas. Jeśli wartość została określona, nie może być większa niż end_time. Musi to być sygnatura czasowa w formacie ISO 8601. Na przykład 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z lub 2026-06-03T10:00:00. Możesz podać milisekundy, ale zostaną one zignorowane.

Pole zbiorcze _end_time.

Pole _end_time może mieć tylko jedną z tych wartości:
endTime

string

Opcjonalnie. Górna granica (wyłączna) czasu rozpoczęcia wydarzenia. Zwracane są tylko wydarzenia, które rozpoczęły się ściśle przed tym czasem (czyli przed końcem przedziału czasu wyszukiwania). Jeśli została określona, musi być równa lub większa niż start_time. Musi to być sygnatura czasowa w formacie ISO 8601. Na przykład 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z lub 2026-06-03T10:00:00. Możesz podać milisekundy, ale zostaną one zignorowane.

Pole zbiorcze _time_zone.

Pole _time_zone może mieć tylko jedną z tych wartości:
timeZone

string

Opcjonalnie. Strefa czasowa używana w odpowiedzi i do rozwiązywania dat bez strefy czasowej w żądaniu (sformatowana jako nazwa z bazy danych stref czasowych IANA, np. Europe/Zurich). Domyślnie jest to strefa czasowa kalendarza.

Pole zbiorcze _order_by.

Pole _order_by może mieć tylko jedną z tych wartości:
orderBy

string

Opcjonalnie. Kolejność, w jakiej mają być zwracane zdarzenia. Możliwe wartości to:

  • default – nieokreślone, ale deterministyczne porządkowanie (domyślnie).
  • startTime – sortowanie według godziny rozpoczęcia w kolejności rosnącej.
  • startTimeDesc – sortowanie według godziny rozpoczęcia w kolejności malejącej.
  • lastModified – sortowanie według czasu ostatniej modyfikacji w kolejności rosnącej.

Pole zbiorcze _full_text.

Pole _full_text może mieć tylko jedną z tych wartości:
fullText

string

Opcjonalnie. Dowolne zapytanie wyszukiwania, które obejmuje tytuł, opis, lokalizację i uczestników.

Schemat wyjściowy

ListEventsResponse

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

  "nextPageToken": string
}
Pola
summary

string

Tytuł kalendarza.
description

string

Opis kalendarza.
updated

string

Czas ostatniej modyfikacji kalendarza (sygnatura czasowa w formacie ISO 8601).
timeZone

string

Strefa czasowa kalendarza.
accessRole

string

Rola dostępu użytkownika do tego kalendarza. Tylko do odczytu. Możliwe wartości to:

  • none – użytkownik nie ma dostępu.
  • freeBusyReader – użytkownik ma dostęp do odczytu informacji o stanie Wolny/Zajęty.
  • reader – użytkownik ma uprawnienia do odczytu kalendarza. Wydarzenia prywatne będą widoczne dla użytkowników z dostępem do odczytu, ale szczegóły wydarzeń będą ukryte.
  • writer – użytkownik ma uprawnienia do odczytu i zapisu w kalendarzu. Wydarzenia prywatne będą widoczne dla użytkowników z uprawnieniami do pisania, a szczegóły wydarzeń będą widoczne.
  • owner – użytkownik ma dostęp do kalendarza jako menedżer. Ta rola ma wszystkie uprawnienia roli osoby piszącej, a dodatkowo umożliwia wyświetlanie i modyfikowanie poziomów dostępu innych użytkowników. Ważne: rola właściciela różni się od właściciela danych kalendarza. Kalendarz ma jednego właściciela danych, ale może mieć wielu użytkowników z rolą właściciela.
defaultReminders[]

object (Reminder)

Domyślne przypomnienia w kalendarzu uwierzytelnionego użytkownika. Te przypomnienia dotyczą wszystkich wydarzeń w tym kalendarzu, które nie są wyraźnie zastąpione (tzn. nie zawierają pola override_reminders).
events[]

object (Event)

Lista wydarzeń w kalendarzu.

Pole zbiorcze _next_page_token.

Pole _next_page_token może mieć tylko jedną z tych wartości:
nextPageToken

string

Token używany do uzyskiwania dostępu do następnej strony tego wyniku. Pomijane, jeśli nie ma więcej wyników.

Przypomnienie

Zapis JSON 
{

  "method": string

  "minutes": integer
}
Pola

Pole zbiorcze _method.

Pole _method może mieć tylko jedną z tych wartości:
method

string

Wymagane. Sposób dostarczania przypomnienia do użytkownika. Możliwe wartości to:

  • email – przypomnienia są wysyłane e-mailem.
  • popup – przypomnienia są wysyłane w wyskakującym okienku interfejsu.

Pole zbiorcze _minutes.

Pole _minutes może mieć tylko jedną z tych wartości:
minutes

integer

Wymagane. Liczba minut przed wydarzeniem, kiedy ma zostać wysłane przypomnienie.

Zdarzenie

Zapis 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)
    }
  ]
}
Pola
id

string

Nieprzezroczysty identyfikator zdarzenia. Podczas tworzenia nowych wydarzeń jednorazowych lub cyklicznych możesz określić ich identyfikatory. Podane identyfikatory muszą być zgodne z tymi regułami:

  • Dozwolone znaki w identyfikatorze to znaki używane w kodowaniu base32hex, czyli małe litery a–v i cyfry 0–9.Więcej informacji znajdziesz w sekcji 3. 1.2 dokumentu RFC2938.
  • długość identyfikatora musi wynosić od 5 do 1024 znaków;
  • identyfikator musi być unikalny w przypadku każdego kalendarza;

Ze względu na globalny charakter systemu nie możemy zagwarantować, że kolizje identyfikatorów zostaną wykryte w momencie tworzenia zdarzenia. Aby zminimalizować ryzyko kolizji, zalecamy użycie sprawdzonego algorytmu UUID, takiego jak opisany w RFC4122.

Jeśli nie podasz identyfikatora, zostanie on wygenerowany automatycznie przez serwer.

Pamiętaj, że icalUID i identyfikator nie są identyczne i tylko jeden z nich powinien być podany w momencie tworzenia wydarzenia. Jedną z różnic w ich semantyce jest to, że w przypadku wydarzeń cyklicznych wszystkie wystąpienia jednego wydarzenia mają różne identyfikatory, ale wszystkie mają te same identyfikatory icalUID.
status

string

Stan zdarzenia. Opcjonalnie. Możliwe wartości to:

  • confirmed – wydarzenie zostało potwierdzone. Jest to stan domyślny.
  • tentative – wydarzenie jest wstępnie potwierdzone.
  • cancelled – wydarzenie zostało odwołane (usunięte). Metoda list zwraca anulowane wydarzenia tylko w przypadku synchronizacji przyrostowej (gdy określono syncToken lub updatedMin) lub jeśli flaga showDeleted ma wartość true. Metoda get zawsze je zwraca.

Stan anulowania reprezentuje 2 różne stany w zależności od typu zdarzenia:

  1. Anulowane wyjątki nieanulowanego wydarzenia cyklicznego wskazują, że ta instancja nie powinna być już prezentowana użytkownikowi. Klienci powinni przechowywać te zdarzenia przez cały okres istnienia nadrzędnego zdarzenia cyklicznego.W przypadku anulowanych wyjątków gwarantowane jest tylko wypełnienie pól id, recurringEventId i originalStartTime. Pozostałe pola mogą być puste.
  2. Wszystkie inne odwołane wydarzenia to usunięte wydarzenia. Klienci powinni usunąć lokalnie zsynchronizowane kopie. Takie odwołane wydarzenia znikną z czasem, więc nie możesz zakładać, że będą dostępne bezterminowo. W przypadku usuniętych wydarzeń gwarantujemy tylko wypełnienie pola id.

W kalendarzu organizatora anulowane wydarzenia nadal zawierają szczegóły (podsumowanie, lokalizację itp.), dzięki czemu można je przywrócić (cofnąć usunięcie). Podobnie wydarzenia, na które użytkownik został zaproszony i które ręcznie usunął, nadal dostarczają szczegółowych informacji. Żądania synchronizacji przyrostowej z parametrem showDeleted ustawionym na wartość false nie zwracają jednak tych szczegółów.

Jeśli organizator wydarzenia zmieni się (np. w wyniku operacji przenoszenia), a pierwotny organizator nie znajduje się na liście uczestników, pozostanie po nim anulowane wydarzenie, w którym tylko pole identyfikatora będzie na pewno wypełnione.
htmlLink

string

Bezwzględny link do tego wydarzenia w interfejsie internetowym Kalendarza Google. Tylko do odczytu.
created

string

Czas utworzenia wydarzenia (sygnatura czasowa w formacie ISO 8601). Tylko do odczytu.
updated

string

Czas ostatniej modyfikacji głównych danych wydarzenia (sygnatura czasowa w formacie ISO 8601). Aktualizowanie przypomnień o wydarzeniach nie spowoduje zmiany tego ustawienia. Tylko do odczytu.
summary

string

Nazwa wydarzenia,
description

string

Opis wydarzenia. Może zawierać kod HTML. Opcjonalnie.
location

string

Położenie geograficzne wydarzenia w formie dowolnego tekstu. Opcjonalnie.
creator

object (Principal)

Twórca wydarzenia. Tylko do odczytu.
organizer

object (Principal)

Organizator wydarzenia. Jeśli organizator jest też uczestnikiem, jest to oznaczone osobnym wpisem w uczestnikach z polem organizator ustawionym na wartość Prawda. Tylko do odczytu.
start

object (DateOrDateTime)

Czas rozpoczęcia wydarzenia (włącznie z wartościami granicznymi). W przypadku wydarzenia cyklicznego jest to czas rozpoczęcia pierwszego wystąpienia.
end

object (DateOrDateTime)

Godzina zakończenia wydarzenia (wyłącznie). W przypadku wydarzenia cyklicznego jest to czas zakończenia pierwszego wystąpienia.
recurrence[]

string

Lista wierszy RRULE, EXRULE, RDATE i EXDATE dla wydarzenia cyklicznego zgodnie ze specyfikacją RFC5545. Pamiętaj, że w tym polu nie można używać wierszy DTSTART i DTEND. Czas rozpoczęcia i zakończenia wydarzenia jest określony w polach rozpoczęcia i zakończenia. To pole jest pomijane w przypadku pojedynczych wydarzeń lub wystąpień wydarzeń cyklicznych.
recurringEventId

string

W przypadku wystąpienia wydarzenia cyklicznego jest to identyfikator wydarzenia cyklicznego, do którego należy to wystąpienie. Niezmienna.
originalStartTime

object (DateOrDateTime)

W przypadku wystąpienia wydarzenia cyklicznego jest to czas, w którym to wydarzenie powinno się rozpocząć zgodnie z danymi o powtarzaniu w wydarzeniu cyklicznym zidentyfikowanym przez recurringEventId. Unikalnie identyfikuje wystąpienie w serii wydarzeń cyklicznych, nawet jeśli zostało ono przeniesione na inny czas. Niezmienna.
transparency

string

Czy wydarzenie blokuje czas w kalendarzu. Opcjonalnie. Możliwe wartości to:

  • opaque – wartość domyślna. Wydarzenie blokuje czas w kalendarzu. Odpowiada to ustawieniu „Pokaż mnie jako zajętego” w interfejsie Kalendarza.
  • transparent – wydarzenie nie blokuje czasu w kalendarzu. Odpowiada to ustawieniu „Pokaż mnie jako” na „Dostępny” w interfejsie Kalendarza.
visibility

string

Widoczność wydarzenia. Opcjonalnie. Możliwe wartości to:

  • default – używa domyślnej widoczności wydarzeń w kalendarzu. Jest to wartość domyślna.
  • public – wydarzenie jest publiczne, a szczegóły wydarzenia są widoczne dla wszystkich osób, które mają dostęp do kalendarza.
  • private – wydarzenie jest prywatne i tylko uczestnicy mogą wyświetlać jego szczegóły.
  • confidential – wydarzenie jest prywatne. Ta wartość jest podawana ze względu na zgodność.
attendees[]

object (Attendee)

Uczestnicy wydarzenia.
eventType

string

Konkretny typ zdarzenia. Po utworzeniu wydarzenia nie można zmienić tego ustawienia. Możliwe wartości to:

  • birthday – specjalne wydarzenie całodniowe, które powtarza się co roku.
  • default – zwykłe wydarzenie lub nieokreślone.
  • focusTime – wydarzenie typu czas skupienia.
  • fromGmail – wydarzenie z Gmaila. Nie można utworzyć tego typu wydarzenia.
  • outOfOffice – wydarzenie poza biurem.
  • workingLocation – zdarzenie związane z lokalizacją miejsca pracy.
conferenceUrl

string

Link do spotkania w Google Meet dotyczącego wydarzenia.
colorId

string

Identyfikator koloru zdarzenia (ciąg znaków 1–11):

  • 1. Lawendowy
  • 2. Sage
  • 3. Winogrona
  • 4: Flaming
  • 5. Banan
  • 6. Mandarynka
  • 7. Paw
  • 8. Grafit
  • 9. Jagoda
  • 10. Bazylia
  • 11. Pomidor.

W Kalendarzu Google kolory wydarzeń pełnią funkcję kategorii, które można ustawić dla każdego wydarzenia lub serii. Użytkownicy mogą przypisywać niestandardowe etykiety do kolorów w interfejsie internetowym (np. 1:1s, Break), ale interfejs API udostępnia tylko identyfikatory numeryczne, a nie te etykiety. Wpływa tylko na widok kalendarza użytkownika – każdy uczestnik kontroluje kolor wydarzenia.
overrideReminders[]

object (Reminder)

Przypomnienia zdefiniowane dla tego wydarzenia, które zastępują domyślne przypomnienia dla kalendarza. Jeśli nie zostanie ustawiony, używane będą domyślne przypomnienia w kalendarzu.

Podmiot zabezpieczeń

Zapis JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Pola
email

string

Adres e-mail podmiotu zabezpieczeń (kalendarza).
displayName

string

Nazwa podmiotu zabezpieczeń (jeśli jest dostępna).
self

boolean

Czy ten podmiot odpowiada kalendarzowi, w którym pojawia się ta kopia wydarzenia. Tylko do odczytu. Wartość domyślna to False (fałsz).

DateOrDateTime

Zapis JSON 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Pola
date

string

Data w formacie ISO 8601 o północy UTC, np. 2019-11-20T00:00:00Z. Jeśli to pole jest ustawione, nie można ustawić pola date_time.
dateTime

string

Sygnatura czasowa w formacie ISO 8601, np. 2019-11-20T08:19:06-07:00 lub 2019-11-20T08:19:06Z. Jeśli to pole jest ustawione, nie można ustawić pola date.
timeZone

string

Nazwa strefy czasowej TZDB, jeśli jest dostępna.

Uczestnik

Zapis JSON 
{
  "id": string,
  "email": string,
  "displayName": string,
  "organizer": boolean,
  "self": boolean,
  "resource": boolean,
  "optionalAttendee": boolean,
  "responseStatus": string,
  "comment": string,
  "additionalGuests": integer
}
Pola
id

string

Identyfikator profilu uczestnika (jeśli jest dostępny).
email

string

Adres e-mail uczestnika, jeśli jest dostępny. To pole musi być obecne podczas dodawania uczestnika. Musi to być prawidłowy adres e-mail zgodny ze standardem RFC5322. Wymagane podczas dodawania uczestnika.
displayName

string

Imię i nazwisko uczestnika (jeśli są dostępne). Opcjonalnie.
organizer

boolean

Określa, czy uczestnik jest organizatorem wydarzenia. Tylko do odczytu. Wartość domyślna to False (fałsz).
self

boolean

Określa, czy ten wpis reprezentuje kalendarz, w którym pojawia się ta kopia wydarzenia. Tylko do odczytu. Wartość domyślna to False (fałsz).
resource

boolean

Określa, czy uczestnik jest zasobem. Można ustawić tylko wtedy, gdy uczestnik jest dodawany do wydarzenia po raz pierwszy. Kolejne modyfikacje są ignorowane. Opcjonalnie. Wartość domyślna to False (fałsz).
optionalAttendee

boolean

Określ, czy uczestnik jest opcjonalny. Opcjonalnie. Wartość domyślna to False (fałsz).
responseStatus

string

Stan odpowiedzi uczestnika. Możliwe wartości to:

  • needsAction – uczestnik nie odpowiedział na zaproszenie (zalecane w przypadku nowych wydarzeń).
  • declined – uczestnik odrzucił zaproszenie.
  • tentative – uczestnik wstępnie zaakceptował zaproszenie.
  • accepted – uczestnik zaakceptował zaproszenie.
comment

string

Komentarz uczestnika do odpowiedzi. Opcjonalnie.
additionalGuests

integer

Liczba dodatkowych gości. Opcjonalnie. Wartość domyślna to 0.

Adnotacje narzędzi

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌