MCP Tools Reference: calendarmcp.googleapis.com

Alat: list_events

Menampilkan acara di kalender tertentu yang cocok dengan semua batasan yang ditentukan. Batasan waktu tidak boleh ditentukan kecuali diminta oleh pengguna. Untuk penelusuran berbasis topik atau kata kunci terbuka di kalender utama, alat search_events harus digunakan.

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

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

Skema Input

ListEventsRequest

Representasi JSON 
{
  "eventTypeFilter": [
    string
  ],
  "eventType": [
    enum (EventType)
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

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

string

Opsional. Tidak digunakan lagi: gunakan event_type sebagai gantinya.
eventType[]

enum (EventType)

Opsional. Jenis peristiwa yang akan ditampilkan. Jika kosong, hanya jenis peristiwa berikut yang ditampilkan: DEFAULT, OUT_OF_OFFICE, FOCUS_TIME, FROM_GMAIL

Kolom union _calendar_id.

_calendar_id hanya dapat berupa salah satu dari hal berikut:
calendarId

string

Opsional. ID kalender yang berisi acara. Alamat email - dapat diselesaikan menggunakan list_calendars. Default: kalender utama.

Kolom union _page_size.

_page_size hanya dapat berupa salah satu dari hal berikut:
pageSize

integer

Opsional. Jumlah maksimum peristiwa per halaman (default 100, maksimum 250). Direkomendasikan: 10.

Kolom union _page_token.

_page_token hanya dapat berupa salah satu dari hal berikut:
pageToken

string

Opsional. Token halaman berikutnya. Gunakan nilai dari nextPageToken halaman sebelumnya.

Kolom union _start_time.

_start_time hanya dapat berupa salah satu dari hal berikut:
startTime

string

Opsional. Batas bawah rentang waktu. Hanya boleh disetel jika jangka waktu tertentu diminta oleh pengguna. Harus berupa stempel waktu ISO 8601 yang kurang dari end_time.

Kolom union _end_time.

_end_time hanya dapat berupa salah satu dari hal berikut:
endTime

string

Opsional. Batas atas rentang waktu. Hanya boleh disetel jika jangka waktu tertentu atau waktu di masa lalu diminta oleh pengguna. Harus berupa stempel waktu ISO 8601 yang lebih besar dari start_time.

Kolom union _time_zone.

_time_zone hanya dapat berupa salah satu dari hal berikut:
timeZone

string

Opsional. Zona waktu (ID IANA, misalnya Europe/Zurich) yang digunakan untuk menyelesaikan tanggal tanpa zona waktu. Default: 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. Penelusuran bentuk bebas yang tidak peka huruf besar/kecil yang cocok dengan judul, deskripsi, lokasi, atau peserta. Mencocokkan peristiwa yang berisi semua istilah kueri secara harfiah (penelusuran AND).

EventType

Jenis peristiwa. Tidak dapat diubah setelah dibuat.

Enum
EVENT_TYPE_UNSPECIFIED Diperlakukan sebagai DEFAULT.
DEFAULT Acara reguler. Nilai default.
OUT_OF_OFFICE Acara tidak di kantor.
FOCUS_TIME Acara waktu fokus.
WORKING_LOCATION Acara lokasi kerja.
BIRTHDAY Acara khusus sepanjang hari dengan pengulangan tahunan.
FROM_GMAIL Acara dari Gmail. Jenis acara ini tidak dapat dibuat.

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 pembaruan terakhir (ISO 8601) kalender.
timeZone

string

Zona waktu kalender.
accessRole

string

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

  • none - Tidak ada akses.
  • freeBusyReader - Akses baca ke informasi senggang/sibuk.
  • reader - Akses baca ke kalender. Acara pribadi akan muncul, tetapi detail acara disembunyikan.
  • writer - Akses baca dan tulis. Acara pribadi akan muncul, dan detail acara dapat dilihat.
  • owner - Akses pengelola, termasuk kemampuan untuk mengubah setelan berbagi kalender.
Penting: Peran owner berbeda dengan pemilik data kalender. Kalender memiliki satu pemilik data, tetapi dapat memiliki beberapa pengguna dengan peran owner.
defaultReminders[]

object (Reminder)

Pengingat default untuk acara di kalender.
events[]

object (Event)

Daftar acara.

Kolom union _next_page_token.

_next_page_token hanya dapat berupa salah satu dari hal berikut:
nextPageToken

string

Token halaman berikutnya. Dihilangkan jika tidak ada halaman berikutnya.

Pengingat

Representasi JSON 
{

  "method": string

  "minutes": integer
}
Kolom

Kolom union _method.

_method hanya dapat berupa salah satu dari hal berikut:
method

string

Wajib. Metode penayangan. 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 dipicu.

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

string

ID unik.
status

string

Opsional. Status. Nilai yang dimungkinkan adalah:

  • confirmed - Acara dikonfirmasi (default).
  • tentative - Acara dikonfirmasi sementara.
  • cancelled - Acara dibatalkan atau dihapus.
htmlLink

string

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

string

Hanya output. Waktu pembuatan (ISO 8601).
updated

string

Hanya output. Waktu modifikasi terakhir (ISO 8601).
summary

string

Judul.
description

string

Opsional. Deskripsi. Dapat berisi HTML.
location

string

Opsional. Lokasi.
creator

object (Principal)

Hanya output. Kreator.
organizer

object (Principal)

Hanya output. Penyelenggara. Juga tercantum dalam peserta jika hadir.
start

object (DateOrDateTime)

Waktu mulai (inklusif). Untuk acara berulang, instance pertama digunakan.
end

object (DateOrDateTime)

Waktu berakhir (eksklusif). Untuk acara berulang, instance pertama digunakan.
recurrence[]

string

Aturan pengulangan sebagai string RRULE, EXRULE, RDATE, atau EXDATE (per RFC 5545). Dihilangkan untuk acara tunggal. Waktu mulai/berakhir harus ditetapkan di kolom start/end.
recurringEventId

string

ID acara rutin induk untuk instance acara rutin.
originalStartTime

object (DateOrDateTime)

Waktu mulai asli instance berulang. Ini adalah waktu saat instance ini akan dimulai menurut data pengulangan.
transparency
(deprecated)

string

Opsional. Tidak digunakan lagi: gunakan availability sebagai gantinya.
visibility

string

Opsional. Visibilitas acara. Nilai yang dimungkinkan adalah:

  • default - Menggunakan visibilitas default untuk acara di kalender. Nilai ini merupakan default.
  • public - Detail acara dapat dilihat oleh semua pembaca kalender.
  • private - Hanya tamu acara yang dapat melihat detail acara.

attendees[]

object (Attendee)

Peserta.
conferenceUrl

string

Link konferensi video.
colorId

string

Warna acara. Hanya memengaruhi tampilan kalender Anda sendiri. Ini adalah ID yang merujuk ke entri dalam palet warna kalender (string '1'-'11'):

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

overrideReminders[]

object (Reminder)

Pengingat. Kembali ke default kalender jika tidak disetel.
attachments[]

object (Attachment)

Lampiran file.
guestPermissions

object (GuestPermissions)

Izin tamu.
eventType

enum (EventType)

Jenis peristiwa.
workingLocationProperties

object (WorkingLocationProperties)

Properti lokasi kerja. Diisi hanya jika event_type adalah WORKING_LOCATION.
availability

enum (Availability)

Opsional. Setelan ketersediaan.

Akun utama

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

string

Email.
displayName

string

Nama.
self

boolean

Hanya output. Apakah prinsipal ini sesuai dengan kalender tempat salinan acara ini muncul. Default: false.

DateOrDateTime

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

string

Tanggal ISO 8601 pada tengah malam UTC (misalnya, '2019-11-20T00:00:00Z').
dateTime

string

Stempel waktu ISO 8601 (misalnya, '2019-11-20T08:19:06-07:00').
timeZone

string

Nama zona waktu TZDB.

Tamu

Representasi JSON 
{

  "id": string

  "email": string

  "displayName": string

  "organizer": boolean

  "self": boolean

  "resource": boolean

  "optionalAttendee": boolean

  "responseStatus": string

  "comment": string

  "additionalGuests": integer
}
Kolom

Kolom union _id.

_id hanya dapat berupa salah satu dari hal berikut:
id

string

Hanya output. ID Profil.

Kolom union _email.

_email hanya dapat berupa salah satu dari hal berikut:
email

string

Wajib. Alamat email peserta.

Kolom union _display_name.

_display_name hanya dapat berupa salah satu dari hal berikut:
displayName

string

Opsional. Nama.

Kolom union _organizer.

_organizer hanya dapat berupa salah satu dari hal berikut:
organizer

boolean

Hanya output. Apakah peserta adalah penyelenggara. Default: false.

Kolom union _self.

_self hanya dapat berupa salah satu dari hal berikut:
self

boolean

Hanya output. Apakah entri ini mewakili kalender tempat salinan acara ini muncul. Default: false.

Kolom union _resource.

_resource hanya dapat berupa salah satu dari hal berikut:
resource

boolean

Opsional. Apakah tamu adalah fasilitas (misalnya, ruang). Tidak dapat diubah, hanya dapat ditetapkan saat peserta ditambahkan pertama kali. Default: false.

Kolom union _optional_attendee.

_optional_attendee hanya dapat berupa salah satu dari hal berikut:
optionalAttendee

boolean

Opsional. Apakah peserta bersifat opsional. Default: false.

Kolom union _response_status.

_response_status hanya dapat berupa salah satu dari hal berikut:
responseStatus

string

Opsional. Status respons. Nilai yang dimungkinkan adalah:

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

Kolom union _comment.

_comment hanya dapat berupa salah satu dari hal berikut:
comment

string

Hanya output. Komentar respons.

Kolom union _additional_guests.

_additional_guests hanya dapat berupa salah satu dari hal berikut:
additionalGuests

integer

Opsional. Jumlah tamu tambahan. Default: 0.

Lampiran

Representasi JSON 
{

  "fileUrl": string

  "title": string
}
Kolom

Kolom union _file_url.

_file_url hanya dapat berupa salah satu dari hal berikut:
fileUrl

string

Wajib. Link URL ke lampiran.

Kolom union _title.

_title hanya dapat berupa salah satu dari hal berikut:
title

string

Opsional. Judul lampiran.

GuestPermissions

Representasi JSON 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
Kolom

Kolom union _guests_can_invite_others.

_guests_can_invite_others hanya dapat berupa salah satu dari hal berikut:
guestsCanInviteOthers

boolean

Opsional. Apakah tamu dapat mengundang orang lain.

Kolom union _guests_can_modify.

_guests_can_modify hanya dapat berupa salah satu dari hal berikut:
guestsCanModify

boolean

Opsional. Apakah tamu dapat mengubah acara.

Kolom union _guests_can_see_guests.

_guests_can_see_guests hanya dapat berupa salah satu dari hal berikut:
guestsCanSeeGuests

boolean

Opsional. Apakah tamu dapat melihat tamu lain.

WorkingLocationProperties

Representasi JSON 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
Kolom

Kolom union _type.

_type hanya dapat berupa salah satu dari hal berikut:
type

enum (WorkingLocationType)

Opsional. Jenis lokasi kerja.

Kolom union _custom_location_label.

_custom_location_label hanya dapat berupa salah satu dari hal berikut:
customLocationLabel

string

Opsional. Label untuk lokasi kustom. Wajib jika jenisnya adalah CUSTOM_LOCATION.

EventType

Jenis peristiwa. Tidak dapat diubah setelah dibuat.

Enum
EVENT_TYPE_UNSPECIFIED Diperlakukan sebagai DEFAULT.
DEFAULT Acara reguler. Nilai default.
OUT_OF_OFFICE Acara tidak di kantor.
FOCUS_TIME Acara waktu fokus.
WORKING_LOCATION Acara lokasi kerja.
BIRTHDAY Acara khusus sepanjang hari dengan pengulangan tahunan.
FROM_GMAIL Acara dari Gmail. Jenis acara ini tidak dapat dibuat.

WorkingLocationType

Jenis lokasi kerja.

Enum
WORKING_LOCATION_TYPE_UNSPECIFIED Jenis lokasi kerja tidak ditentukan. Akan diperlakukan sebagai HOME_OFFICE.
HOME_OFFICE Kantor rumah.
CUSTOM_LOCATION Lokasi kustom.

Ketersediaan

Setelan ketersediaan untuk acara.

Enum
AVAILABILITY_UNSPECIFIED Default. Diperlakukan sebagai BUSY.
AVAILABILITY_BUSY Memblokir waktu di kalender.
AVAILABILITY_FREE Tidak memblokir waktu.

Anotasi Alat

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

Cakupan Otorisasi

Memerlukan salah satu cakupan OAuth berikut:

  • 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