MCP Tools Reference: calendarmcp.googleapis.com

Alat: list_events

Mencantumkan acara kalender dalam kalender tertentu yang memenuhi kondisi tertentu.

Fitur Utama:

  • ID Kalender apa pun, yang dapat berupa kalender utama pengguna atau kalender lainnya.
  • Pemfilteran rentang waktu.
  • Mengambil SEMUA peristiwa yang cocok dengan batasan waktu.

Jika tersedia, gunakan alat search_events untuk penelusuran di kalender utama pengguna jika:

  • Anda membuat kueri untuk acara yang cocok dengan topik, kategori, atau maksud tertentu (misalnya, 'rapat makan siang', 'sinkronisasi project').
  • Anda perlu menemukan (K teratas) peristiwa yang paling relevan, bukan semua peristiwa yang memenuhi batasan.
  • Anda memerlukan kemampuan penelusuran kata kunci atau semantik.

Gunakan alat ini untuk kueri seperti:

  • Apa agenda saya besok?
  • Ada acara apa di kalender saya pada 14 Juli 2025?
  • Apa saja rapat saya minggu depan?
  • Apakah ada rapat yang bentrok siang ini?

  • Apa saja rapat yang dijadwalkan untuk Joni besok?

Contoh:

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.

Contoh berikut menunjukkan cara menggunakan curl untuk memanggil alat MCP list_events.

Permintaan 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
}'

Skema Input

ListEventsRequest

Representasi JSON 
{
  "eventTypeFilter": [
    string
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Kolom
eventTypeFilter[]

string

Opsional. Jenis peristiwa yang akan ditampilkan. Nilai yang dimungkinkan adalah:

  • default - Acara reguler (default).
  • outOfOffice - Acara tidak di kantor.
  • focusTime - Acara waktu fokus.
  • workingLocation - Peristiwa lokasi kerja.
  • birthday - Acara ulang tahun.
  • fromGmail - Acara dari Gmail.

Jika kosong, hanya jenis peristiwa berikut yang ditampilkan: default, outOfOffice, focusTime, fromGmail

Kolom union _calendar_id.

_calendar_id hanya dapat berupa salah satu dari hal berikut:
calendarId

string

Opsional. ID kalender untuk mencantumkan acara. Defaultnya adalah kalender utama pengguna.

Kolom union _page_size.

_page_size hanya dapat berupa salah satu dari hal berikut:
pageSize

integer

Opsional. Jumlah maksimum peristiwa yang ditampilkan di satu halaman hasil. Jumlah peristiwa di halaman hasil mungkin kurang dari nilai ini, atau tidak ada sama sekali, meskipun ada lebih banyak peristiwa yang cocok dengan kueri. Halaman yang tidak lengkap dapat dideteksi oleh kolom next_page_token yang tidak kosong dalam respons. Secara default, nilainya adalah 250 peristiwa. Ukuran halaman tidak boleh lebih besar dari 2.500 peristiwa.

Kolom union _page_token.

_page_token hanya dapat berupa salah satu dari hal berikut:
pageToken

string

Opsional. Token yang menentukan halaman hasil mana yang akan ditampilkan.

Kolom union _start_time.

_start_time hanya dapat berupa salah satu dari hal berikut:
startTime

string

Opsional. Batas bawah (eksklusif) untuk waktu berakhir acara. Hanya acara yang berakhir tepat setelah waktu ini yang ditampilkan (yaitu, awal rentang waktu untuk penelusuran). Nilai defaultnya adalah waktu saat ini jika start_time maupun end_time tidak diberikan. Jika ditentukan, harus kurang dari atau sama dengan end_time. Harus berupa stempel waktu ISO 8601. Misalnya, 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z, atau 2026-06-03T10:00:00. Milidetik dapat diberikan, tetapi akan diabaikan.

Kolom union _end_time.

_end_time hanya dapat berupa salah satu dari hal berikut:
endTime

string

Opsional. Batas atas (eksklusif) untuk waktu mulai acara. Hanya acara yang dimulai tepat sebelum waktu ini yang ditampilkan (yaitu, akhir jangka waktu penelusuran). Jika ditentukan, harus lebih besar dari atau sama dengan start_time. Harus berupa stempel waktu ISO 8601. Misalnya, 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z, atau 2026-06-03T10:00:00. Milidetik dapat diberikan, tetapi akan diabaikan.

Kolom union _time_zone.

_time_zone hanya dapat berupa salah satu dari hal berikut:
timeZone

string

Opsional. Zona waktu yang digunakan dalam respons dan untuk menyelesaikan tanggal tanpa zona waktu dalam permintaan (diformat sebagai nama Database Zona Waktu IANA, misalnya Europe/Zurich). Defaultnya adalah zona waktu kalender.

Kolom union _order_by.

_order_by hanya dapat berupa salah satu dari hal berikut:
orderBy

string

Opsional. Urutan acara yang harus ditampilkan. Nilai yang dimungkinkan adalah:

  • default - Tidak ditentukan, tetapi pengurutan deterministik (default).
  • startTime - Urutkan berdasarkan waktu mulai menaik.
  • startTimeDesc - Urutkan menurut waktu mulai menurun.
  • lastModified - Urutkan berdasarkan waktu modifikasi terakhir secara menaik.

Kolom union _full_text.

_full_text hanya dapat berupa salah satu dari hal berikut:
fullText

string

Opsional. Kueri penelusuran bentuk bebas untuk menelusuri judul, deskripsi, lokasi, dan peserta.

Skema Output

ListEventsResponse

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

  "nextPageToken": string
}
Kolom
summary

string

Judul kalender.
description

string

Deskripsi kalender.
updated

string

Waktu modifikasi terakhir kalender (sebagai stempel waktu ISO 8601).
timeZone

string

Zona waktu kalender.
accessRole

string

Peran akses pengguna untuk kalender ini. Hanya baca. Nilai yang dimungkinkan adalah:

  • none - Pengguna tidak memiliki akses.
  • freeBusyReader - Pengguna memiliki akses baca ke informasi senggang/sibuk.
  • reader - Pengguna memiliki akses baca ke kalender. Acara pribadi akan muncul bagi pengguna dengan akses pelihat, tetapi detail acara akan disembunyikan.
  • writer - Pengguna memiliki akses baca dan tulis ke kalender. Acara pribadi akan muncul bagi pengguna dengan akses penulis, dan detail acara akan terlihat.
  • owner - Pengguna memiliki akses pengelola ke kalender. Peran ini memiliki semua izin peran penulis dengan kemampuan tambahan untuk melihat dan mengubah tingkat akses pengguna lain. Penting: peran pemilik berbeda dengan pemilik data kalender. Kalender memiliki satu pemilik data, tetapi dapat memiliki beberapa pengguna dengan peran pemilik.
defaultReminders[]

object (Reminder)

Pengingat default di kalender untuk pengguna yang diautentikasi. Pengingat ini berlaku untuk semua acara di kalender ini yang tidak secara eksplisit menggantikannya (yaitu, tidak mengisi override_reminders).
events[]

object (Event)

Daftar acara di kalender.

Kolom union _next_page_token.

_next_page_token hanya dapat berupa salah satu dari hal berikut:
nextPageToken

string

Token yang digunakan untuk mengakses halaman berikutnya dari hasil ini. Dihilangkan jika tidak ada hasil lainnya.

Pengingat

Representasi JSON 
{

  "method": string

  "minutes": integer
}
Kolom

Kolom union _method.

_method hanya dapat berupa salah satu dari hal berikut:
method

string

Wajib. Cara pengingat dikirimkan kepada pengguna. Nilai yang dimungkinkan adalah:

  • email - Pengingat dikirim melalui email.
  • popup - Pengingat dikirim melalui pop-up UI.

Kolom union _minutes.

_minutes hanya dapat berupa salah satu dari hal berikut:
minutes

integer

Wajib. Jumlah menit sebelum pengingat harus dikirim.

Acara

Representasi 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)
    }
  ]
}
Kolom
id

string

ID buram peristiwa. Saat membuat acara baru satu kali atau berulang, Anda dapat menentukan ID-nya. ID yang diberikan harus mengikuti aturan berikut:

  • karakter yang diizinkan dalam ID adalah karakter yang digunakan dalam encoding base32hex, yaitu huruf kecil a-v dan digit 0-9, lihat bagian 3.1.2 dalam RFC2938
  • panjang ID harus antara 5 dan 1024 karakter
  • ID harus unik per kalender

Karena sifat sistem yang didistribusikan secara global, kami tidak dapat menjamin bahwa tabrakan ID akan terdeteksi pada saat pembuatan acara. Untuk meminimalkan risiko bentrokan, sebaiknya gunakan algoritma UUID yang sudah mapan seperti yang dijelaskan dalam RFC4122.

Jika Anda tidak menentukan ID, ID akan dibuat secara otomatis oleh server.

Perhatikan bahwa icalUID dan id tidak identik dan hanya salah satunya yang harus diberikan pada saat pembuatan acara. Salah satu perbedaan semantiknya adalah bahwa dalam acara berulang, semua kemunculan satu acara memiliki ID yang berbeda, tetapi semuanya memiliki icalUID yang sama.
status

string

Status acara. Opsional. Nilai yang dimungkinkan adalah:

  • confirmed - Acara dikonfirmasi. Ini adalah status default.
  • tentative - Acara dikonfirmasi sementara.
  • cancelled - Acara dibatalkan (dihapus). Metode daftar menampilkan peristiwa yang dibatalkan hanya pada sinkronisasi inkremental (saat syncToken atau updatedMin ditentukan) atau jika tanda showDeleted disetel ke benar. Metode get selalu menampilkannya.

Status dibatalkan mewakili dua status berbeda, bergantung pada jenis peristiwanya:

  1. Pengecualian yang dibatalkan dari acara berulang yang tidak dibatalkan menunjukkan bahwa instance ini tidak boleh lagi ditampilkan kepada pengguna. Klien harus menyimpan peristiwa ini selama masa aktif acara berulang induk.Pengecualian yang dibatalkan hanya dijamin memiliki nilai untuk kolom id, recurringEventId, dan originalStartTime yang diisi. Kolom lainnya mungkin kosong.
  2. Semua acara lain yang dibatalkan mewakili acara yang dihapus. Klien harus menghapus salinan yang disinkronkan secara lokal. Acara yang dibatalkan tersebut pada akhirnya akan hilang, jadi jangan mengandalkan ketersediaannya tanpa batas waktu. Peristiwa yang dihapus hanya dijamin memiliki kolom id yang terisi.

Di kalender penyelenggara, acara yang dibatalkan terus menampilkan detail acara (ringkasan, lokasi, dll.) sehingga dapat dipulihkan (dibatalkan penghapusannya). Demikian pula, acara yang mengundang pengguna dan yang dihapus secara manual oleh pengguna akan terus memberikan detail. Namun, permintaan sinkronisasi inkremental dengan showDeleted yang ditetapkan ke false tidak akan menampilkan detail ini.

Jika penyelenggara acara berubah (misalnya melalui operasi pemindahan) dan penyelenggara asli tidak ada dalam daftar peserta, acara yang dibatalkan akan ditinggalkan dan hanya kolom id yang dijamin terisi.
htmlLink

string

Link absolut ke acara ini di UI Web Google Kalender. Hanya baca.
created

string

Waktu pembuatan acara (sebagai stempel waktu berformat ISO 8601). Hanya baca.
updated

string

Waktu modifikasi terakhir data acara utama (sebagai stempel waktu berformat ISO 8601). Memperbarui pengingat acara tidak akan mengubahnya. Hanya baca.
summary

string

Judul acara.
description

string

Deskripsi acara. Dapat berisi HTML. Opsional.
location

string

Lokasi geografis acara sebagai teks bebas. Opsional.
creator

object (Principal)

Pembuat acara. Hanya baca.
organizer

object (Principal)

Penyelenggara acara. Jika penyelenggara juga merupakan tamu, hal ini ditunjukkan dengan entri terpisah di tamu dengan kolom penyelenggara ditetapkan ke True. Hanya baca.
start

object (DateOrDateTime)

Waktu mulai (inklusif) acara. Untuk acara berulang, ini adalah waktu mulai instance pertama.
end

object (DateOrDateTime)

Waktu berakhir (eksklusif) acara. Untuk acara berulang, ini adalah waktu berakhir instance pertama.
recurrence[]

string

Daftar baris RRULE, EXRULE, RDATE, dan EXDATE untuk acara berulang, seperti yang ditentukan dalam RFC5545. Perhatikan bahwa baris DTSTART dan DTEND tidak diizinkan dalam kolom ini; waktu mulai dan akhir acara ditentukan dalam kolom mulai dan akhir. Kolom ini tidak disertakan untuk acara tunggal atau instance acara berulang.
recurringEventId

string

Untuk instance acara berulang, ini adalah ID acara berulang yang memiliki instance ini. Tidak dapat diubah.
originalStartTime

object (DateOrDateTime)

Untuk instance acara berulang, ini adalah waktu dimulainya acara ini menurut data pengulangan dalam acara berulang yang diidentifikasi oleh recurringEventId. ID ini mengidentifikasi instance secara unik dalam rangkaian acara berulang meskipun instance dipindahkan ke waktu yang berbeda. Tidak dapat diubah.
transparency

string

Apakah acara memblokir waktu di kalender. Opsional. Nilai yang dimungkinkan adalah:

  • opaque - Nilai default. Acara tersebut memblokir waktu di kalender. Tindakan ini sama dengan menyetel Tampilkan saya sebagai Sibuk di UI Kalender.
  • transparent - Acara tidak memblokir waktu di kalender. Tindakan ini sama dengan menyetel Tampilkan saya sebagai ke Tersedia di UI Kalender.
visibility

string

Visibilitas acara. Opsional. Nilai yang dimungkinkan adalah:

  • default - Menggunakan visibilitas default untuk acara di kalender. Nilai ini adalah nilai default.
  • public - Acara bersifat publik dan detail acara dapat dilihat oleh semua pembaca kalender.
  • private - Acara bersifat pribadi dan hanya tamu acara yang dapat melihat detail acara.
  • confidential - Acara bersifat pribadi. Nilai ini diberikan karena alasan kompatibilitas.
attendees[]

object (Attendee)

Peserta acara.
eventType

string

Jenis peristiwa tertentu. Setelan ini tidak dapat diubah setelah acara dibuat. Nilai yang dimungkinkan adalah:

  • birthday - Acara khusus sepanjang hari dengan pengulangan tahunan.
  • default - Acara reguler atau tidak ditentukan lebih lanjut.
  • focusTime - Acara waktu fokus.
  • fromGmail - Acara dari Gmail. Jenis acara ini tidak dapat dibuat.
  • outOfOffice - Acara tidak di kantor.
  • workingLocation - Acara lokasi kerja.
conferenceUrl

string

Link Google Meet untuk acara.
colorId

string

ID warna acara (string 1-11):

  • 1: Lavender
  • 2: Sage
  • 3: Anggur
  • 4: Flamingo
  • 5: Pisang
  • 6: Tangerine
  • 7: Merak
  • 8: Grafit
  • 9: Bluberi
  • 10: Basil
  • 11: Tomat.

Di Google Kalender, warna acara berfungsi sebagai kategori — dapat disetel per acara atau per rangkaian. Pengguna dapat menetapkan label kustom ke warna di UI web (misalnya, 1:1s, Break), tetapi API hanya menampilkan ID numerik, bukan label tersebut. Hanya memengaruhi tampilan kalender Anda sendiri — setiap tamu mengontrol warna acaranya sendiri.
overrideReminders[]

object (Reminder)

Pengingat yang ditentukan untuk acara ini, menggantikan pengingat default untuk kalender. Jika tidak disetel, pengingat default di kalender akan digunakan.

Akun utama

Representasi JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Kolom
email

string

Alamat email kepala sekolah (kalender).
displayName

string

Nama kepala sekolah, jika tersedia.
self

boolean

Apakah prinsipal ini sesuai dengan kalender tempat salinan acara ini muncul. Hanya baca. Defaultnya adalah False.

DateOrDateTime

Representasi JSON 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Kolom
date

string

Tanggal berformat ISO 8601 pada tengah malam UTC, seperti 2019-11-20T00:00:00Z. Jika kolom ini disetel, date_time tidak boleh disetel.
dateTime

string

Stempel waktu berformat ISO 8601 seperti 2019-11-20T08:19:06-07:00 atau 2019-11-20T08:19:06Z. Jika kolom ini disetel, date tidak boleh disetel.
timeZone

string

Nama zona waktu TZDB jika tersedia.

Peserta

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

string

ID Profil tamu, jika tersedia.
email

string

Alamat email peserta, jika tersedia. Kolom ini harus ada saat menambahkan tamu. Alamat email harus valid sesuai dengan RFC5322. Wajib diisi saat menambahkan tamu.
displayName

string

Nama tamu, jika tersedia. Opsional.
organizer

boolean

Apakah tamu adalah penyelenggara acara. Hanya baca. Defaultnya adalah False.
self

boolean

Apakah entri ini mewakili kalender tempat salinan acara ini muncul. Hanya baca. Defaultnya adalah False.
resource

boolean

Apakah peserta adalah resource. Hanya dapat ditetapkan saat tamu ditambahkan ke acara untuk pertama kalinya. Modifikasi berikutnya akan diabaikan. Opsional. Defaultnya adalah False.
optionalAttendee

boolean

Apakah ini adalah tamu opsional. Opsional. Defaultnya adalah False.
responseStatus

string

Status respons peserta. Nilai yang dimungkinkan adalah:

  • needsAction - Tamu belum merespons undangan (direkomendasikan untuk acara baru).
  • declined - Tamu telah menolak undangan.
  • tentative - Tamu telah menerima undangan untuk sementara.
  • accepted - Tamu telah menerima undangan.
comment

string

Komentar respons peserta. Opsional.
additionalGuests

integer

Jumlah tamu tambahan. Opsional. Defaultnya adalah 0.

Anotasi Alat

Petunjuk Destruktif: ❌ | Petunjuk Idempoten: ✅ | Petunjuk Hanya Baca: ✅ | Petunjuk Dunia Terbuka: ❌