MCP Tools Reference: calendarmcp.googleapis.com

Araç: list_events

Belirtilen takvimdeki, belirtilen tüm kısıtlamalarla eşleşen etkinlikleri döndürür. Kullanıcı tarafından istenmediği sürece zaman kısıtlamaları belirtilmemelidir. Birincil takvimde açık uçlu anahtar kelime veya konuya dayalı aramalar için bunun yerine search_events aracı kullanılmalıdır.

Aşağıdaki örnekte, list_events MCP aracını çağırmak için curl simgesinin nasıl kullanılacağı gösterilmektedir.

Curl İsteği 
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
}'

Giriş Şeması

ListEventsRequest

JSON gösterimi 
{
  "eventTypeFilter": [
    string
  ],
  "eventType": [
    enum (EventType)
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

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

string

İsteğe bağlı. Desteği sonlandırıldı: Bunun yerine event_type kullanın.
eventType[]

enum (EventType)

İsteğe bağlı. Döndürülecek etkinlik türleri. Boşsa yalnızca şu etkinlik türleri döndürülür: DEFAULT, OUT_OF_OFFICE, FOCUS_TIME, FROM_GMAIL

_calendar_id birleşik alanı.

_calendar_id aşağıdakilerden yalnızca biri olabilir:
calendarId

string

İsteğe bağlı. Etkinlikleri içeren takvimin kimliği. E-posta adresi: list_calendars kullanılarak çözümlenebilir. Varsayılan: birincil takvim.

_page_size birleşik alanı.

_page_size aşağıdakilerden yalnızca biri olabilir:
pageSize

integer

İsteğe bağlı. Sayfa başına maksimum etkinlik sayısı (varsayılan 100, maksimum 250). Önerilen: 10.

_page_token birleşik alanı.

_page_token aşağıdakilerden yalnızca biri olabilir:
pageToken

string

İsteğe bağlı. Sonraki sayfa jetonu. Önceki sayfanın nextPageToken değerini kullanın.

_start_time birleşik alanı.

_start_time aşağıdakilerden yalnızca biri olabilir:
startTime

string

İsteğe bağlı. Bir zaman aralığının alt sınırı. Yalnızca kullanıcı tarafından belirli bir zaman aralığı istendiğinde ayarlanmalıdır. end_time değerinden küçük bir ISO 8601 zaman damgası olmalıdır.

_end_time birleşik alanı.

_end_time aşağıdakilerden yalnızca biri olabilir:
endTime

string

İsteğe bağlı. Bir zaman aralığının üst sınırı. Yalnızca kullanıcı tarafından belirli bir zaman aralığı veya geçmişte bir zaman istendiğinde ayarlanmalıdır. start_time değerinden büyük bir ISO 8601 zaman damgası olmalıdır.

_time_zone birleşik alanı.

_time_zone aşağıdakilerden yalnızca biri olabilir:
timeZone

string

İsteğe bağlı. Saat dilimi olmayan tarihleri çözümlemek için kullanılan saat dilimi (örneğin, IANA kimliği Europe/Zurich). Varsayılan: Takvimin saat dilimi.

_order_by birleşik alanı.

_order_by aşağıdakilerden yalnızca biri olabilir:
orderBy

string

İsteğe bağlı. Etkinliklerin döndürülmesi gereken sıra. Olası değerler:

  • default: Belirtilmemiş ancak sıralama belirlidir (varsayılan).
  • startTime: Başlangıç zamanına göre artan düzende sıralayın.
  • startTimeDesc: Başlangıç zamanına göre azalan düzende sıralayın.
  • lastModified: Son değiştirme zamanına göre artan sırada sıralayın.

_full_text birleşik alanı.

_full_text aşağıdakilerden yalnızca biri olabilir:
fullText

string

İsteğe bağlı. Başlık, açıklama, konum veya katılımcılarla eşleşen, büyük/küçük harfe duyarsız serbest biçimli arama. Tüm sorgu terimlerini tam olarak içeren etkinliklerle eşleşir (AND araması).

EventType

Etkinlik türü. Oluşturulduktan sonra değiştirilemez.

Sıralamalar
EVENT_TYPE_UNSPECIFIED DEFAULT olarak değerlendirilir.
DEFAULT Normal etkinlik. Varsayılan değer.
OUT_OF_OFFICE Ofis dışında etkinliği.
FOCUS_TIME Odaklanma zamanı etkinliği.
WORKING_LOCATION Çalışma yeri etkinliği.
BIRTHDAY Yılda bir kez düzenlenen, tüm gün süren özel etkinlik.
FROM_GMAIL Gmail'den alınan etkinlikler. Bu tür etkinlikler oluşturulamaz.

Çıkış Şeması

ListEventsResponse

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

  "nextPageToken": string
}
Alanlar
summary

string

Takvimin başlığı.
description

string

Takvimin açıklaması.
updated

string

Takvimin son güncelleme zamanı (ISO 8601).
timeZone

string

Takvimin saat dilimi
accessRole

string

Yalnızca çıkış. Kullanıcının takvimdeki erişim rolü. Olası değerler:

  • none: Erişim yok.
  • freeBusyReader - Uygun/meşgul bilgilerine okuma erişimi.
  • reader - Takvime okuma erişimi. Gizli etkinlikler görünür ancak etkinlik ayrıntıları gizlenir.
  • writer - Okuma ve yazma erişimi. Gizli etkinlikler görünür ve etkinlik ayrıntıları gösterilir.
  • owner - Takvimin paylaşım ayarlarını değiştirme özelliği de dahil olmak üzere yönetici erişimi.
Önemli: owner rolü, takvimin veri sahibinden farklıdır. Bir takvimin tek bir veri sahibi vardır ancak owner rolüne sahip birden fazla kullanıcısı olabilir.
defaultReminders[]

object (Reminder)

Takvimdeki etkinlikler için varsayılan hatırlatıcılar.
events[]

object (Event)

Etkinlik listesi.

_next_page_token birleşik alanı.

_next_page_token aşağıdakilerden yalnızca biri olabilir:
nextPageToken

string

Sonraki sayfa jetonu. Sonraki sayfa yoksa atlanır.

Hatırlatma

JSON gösterimi 
{

  "method": string

  "minutes": integer
}
Alanlar

_method birleşik alanı.

_method aşağıdakilerden yalnızca biri olabilir:
method

string

Zorunlu. Yayınlanma yöntemi. Olası değerler:

  • email - Hatırlatıcılar e-postayla gönderilir.
  • popup: Hatırlatmalar, kullanıcı arayüzü pop-up'ı aracılığıyla gönderilir.

_minutes birleşik alanı.

_minutes aşağıdakilerden yalnızca biri olabilir:
minutes

integer

Zorunlu. Hatırlatıcının kaç dakika önce tetikleneceği

Etkinlik

JSON gösterimi 
{
  "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)
}
Alanlar
id

string

Benzersiz tanımlayıcı.
status

string

İsteğe bağlı. Durum'a dokunun. Olası değerler:

  • confirmed - Etkinlik onaylandı (varsayılan).
  • tentative: Etkinlik geçici olarak onaylandı.
  • cancelled - Etkinlik iptal edildi veya silindi.
htmlLink

string

Yalnızca çıkış. Google Takvim web kullanıcı arayüzünde bu etkinliğe giden mutlak bağlantı.
created

string

Yalnızca çıkış. Oluşturulma zamanı (ISO 8601).
updated

string

Yalnızca çıkış. Son değiştirme zamanı (ISO 8601).
summary

string

Başlık.
description

string

İsteğe bağlı. Açıklama. HTML içerebilir.
location

string

İsteğe bağlı. Konum'a dokunun.
creator

object (Principal)

Yalnızca çıkış. İçerik üretici.
organizer

object (Principal)

Yalnızca çıkış. Düzenleyen. Katılımcılar listesinde de gösterilir.
start

object (DateOrDateTime)

Başlangıç zamanı (dahil). Yinelenen etkinliklerde ilk örnek kullanılır.
end

object (DateOrDateTime)

Bitiş zamanı (dahil değil). Düzenli etkinliklerde ilk örnek kullanılır.
recurrence[]

string

Yinelenme kuralları RRULE, EXRULE, RDATE veya EXDATE dizeleri (RFC 5545'e göre) olarak. Tek seferlik etkinlikler için atlanır. Başlangıç/bitiş zamanları start/end alanlarında ayarlanmalıdır.
recurringEventId

string

Düzenli etkinlik örnekleri için üst düzenli etkinlik kimliği.
originalStartTime

object (DateOrDateTime)

Tekrarlanan örneklerin orijinal başlangıç zamanı. Bu, yinelenme verilerine göre bu örneğin başlayacağı zamandır.
transparency
(deprecated)

string

İsteğe bağlı. Desteği sonlandırıldı: Bunun yerine availability kullanın.
visibility

string

İsteğe bağlı. Etkinliğin görünürlüğü. Olası değerler:

  • default: Takvimdeki etkinlikler için varsayılan görünürlüğü kullanır. Bu, varsayılan değerdir.
  • public - Etkinlik ayrıntıları, takvimin tüm okuyucuları tarafından görülebilir.
  • private - Etkinlik ayrıntılarını yalnızca etkinlik katılımcıları görüntüleyebilir.

attendees[]

object (Attendee)

Katılımcılar
conferenceUrl

string

Video konferans bağlantısı.
colorId

string

Etkinliğin rengi. Yalnızca kendi takvim görünümünüzü etkiler. Bu, takvimin renk paletindeki bir girişi ifade eden kimliktir (dize '1'-'11'):

  • 1: Lavanta
  • 2: Adaçayı
  • 3: Üzüm
  • 4: Flamingo
  • 5: Muz
  • 6: Mandalina
  • 7: Peacock
  • 8: Grafit
  • 9: Yaban mersini
  • 10: Fesleğen
  • 11: Domates.

overrideReminders[]

object (Reminder)

Hatırlatıcılar'a dokunun. Ayarlanmamışsa takvim varsayılanlarına geri döner.
attachments[]

object (Attachment)

Dosya ekleri
guestPermissions

object (GuestPermissions)

Davetli izinleri
eventType

enum (EventType)

Etkinlik türü.
workingLocationProperties

object (WorkingLocationProperties)

Çalışma yeri özellikleri. Yalnızca event_type WORKING_LOCATION olduğunda doldurulur.
availability

enum (Availability)

İsteğe bağlı. Kullanılabilirlik ayarı.

Ana hesap

JSON gösterimi 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Alanlar
email

string

E-posta'yı tıklayın.
displayName

string

Ad.
self

boolean

Yalnızca çıkış. Bu asıl kullanıcının, etkinliğin bu kopyasının göründüğü takvime karşılık gelip gelmediği. Varsayılan: false.

DateOrDateTime

JSON gösterimi 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Alanlar
date

string

UTC saatine göre gece yarısı ISO 8601 tarihi (örneğin, '2019-11-20T00:00:00Z').
dateTime

string

ISO 8601 zaman damgası (örneğin, '2019-11-20T08:19:06-07:00').
timeZone

string

TZDB saat dilimi adı.

Katılımcı

JSON gösterimi 
{

  "id": string

  "email": string

  "displayName": string

  "organizer": boolean

  "self": boolean

  "resource": boolean

  "optionalAttendee": boolean

  "responseStatus": string

  "comment": string

  "additionalGuests": integer
}
Alanlar

_id birleşik alanı.

_id aşağıdakilerden yalnızca biri olabilir:
id

string

Yalnızca çıkış. Profil kimliği.

_email birleşik alanı.

_email aşağıdakilerden yalnızca biri olabilir:
email

string

Zorunlu. Katılımcının e-posta adresi.

_display_name birleşik alanı.

_display_name aşağıdakilerden yalnızca biri olabilir:
displayName

string

İsteğe bağlı. Ad.

_organizer birleşik alanı.

_organizer aşağıdakilerden yalnızca biri olabilir:
organizer

boolean

Yalnızca çıkış. Katılımcının düzenleyici olup olmadığı. Varsayılan: false.

_self birleşik alanı.

_self aşağıdakilerden yalnızca biri olabilir:
self

boolean

Yalnızca çıkış. Bu giriş, etkinliğin bu kopyasının göründüğü takvimi temsil edip etmediği. Varsayılan: false.

_resource birleşik alanı.

_resource aşağıdakilerden yalnızca biri olabilir:
resource

boolean

İsteğe bağlı. Katılımcının kaynak (ör. oda) olup olmadığı. Değiştirilemez, yalnızca katılımcı ilk kez eklendiğinde ayarlanabilir. Varsayılan: false.

_optional_attendee birleşik alanı.

_optional_attendee aşağıdakilerden yalnızca biri olabilir:
optionalAttendee

boolean

İsteğe bağlı. Katılımcının isteğe bağlı olup olmadığı. Varsayılan: false.

_response_status birleşik alanı.

_response_status aşağıdakilerden yalnızca biri olabilir:
responseStatus

string

İsteğe bağlı. Yanıt durumu. Olası değerler:

  • needsAction - Katılımcı davetiye yanıt vermedi (yeni etkinlikler için önerilir).
  • declined: Katılımcı davetiyeyi reddetti.
  • tentative: Katılımcı, daveti geçici olarak kabul etti.
  • accepted: Katılımcı daveti kabul etti.

_comment birleşik alanı.

_comment aşağıdakilerden yalnızca biri olabilir:
comment

string

Yalnızca çıkış. Yanıt yorumu.

_additional_guests birleşik alanı.

_additional_guests aşağıdakilerden yalnızca biri olabilir:
additionalGuests

integer

İsteğe bağlı. Ek davetli sayısı. Varsayılan: 0.

Ek

JSON gösterimi 
{

  "fileUrl": string

  "title": string
}
Alanlar

_file_url birleşik alanı.

_file_url aşağıdakilerden yalnızca biri olabilir:
fileUrl

string

Zorunlu. Ekin URL bağlantısı.

_title birleşik alanı.

_title aşağıdakilerden yalnızca biri olabilir:
title

string

İsteğe bağlı. Ek başlığı

GuestPermissions

JSON gösterimi 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
Alanlar

_guests_can_invite_others birleşik alanı.

_guests_can_invite_others aşağıdakilerden yalnızca biri olabilir:
guestsCanInviteOthers

boolean

İsteğe bağlı. Davetlilerin başkalarını davet edip edemeyeceği

_guests_can_modify birleşik alanı.

_guests_can_modify aşağıdakilerden yalnızca biri olabilir:
guestsCanModify

boolean

İsteğe bağlı. Davetlilerin etkinliği değiştirip değiştiremeyeceği

_guests_can_see_guests birleşik alanı.

_guests_can_see_guests aşağıdakilerden yalnızca biri olabilir:
guestsCanSeeGuests

boolean

İsteğe bağlı. Davetlilerin diğer davetlileri görüp göremeyeceği

WorkingLocationProperties

JSON gösterimi 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
Alanlar

_type birleşik alanı.

_type aşağıdakilerden yalnızca biri olabilir:
type

enum (WorkingLocationType)

İsteğe bağlı. Çalışma yeri türü.

_custom_location_label birleşik alanı.

_custom_location_label aşağıdakilerden yalnızca biri olabilir:
customLocationLabel

string

İsteğe bağlı. Özel konumun etiketi. Tür CUSTOM_LOCATION ise zorunludur.

EventType

Etkinlik türü. Oluşturulduktan sonra değiştirilemez.

Sıralamalar
EVENT_TYPE_UNSPECIFIED DEFAULT olarak değerlendirilir.
DEFAULT Normal etkinlik. Varsayılan değer.
OUT_OF_OFFICE Ofis dışında etkinliği.
FOCUS_TIME Odaklanma zamanı etkinliği.
WORKING_LOCATION Çalışma yeri etkinliği.
BIRTHDAY Yılda bir kez düzenlenen, tüm gün süren özel etkinlik.
FROM_GMAIL Gmail'den alınan etkinlikler. Bu tür etkinlikler oluşturulamaz.

WorkingLocationType

Çalışma yerinin türü.

Sıralamalar
WORKING_LOCATION_TYPE_UNSPECIFIED Çalışma yeri türü belirtilmedi. HOME_OFFICE olarak kabul edilir.
HOME_OFFICE Ev ofisi.
CUSTOM_LOCATION Özel konum.

Kullanılabilirlik

Bir etkinlik için müsaitlik durumu ayarı.

Sıralamalar
AVAILABILITY_UNSPECIFIED Varsayılan. BUSY olarak değerlendirilir.
AVAILABILITY_BUSY Takvimde zaman engeller.
AVAILABILITY_FREE Zamanı engellemez.

Araç Ek Açıklamaları

Yıkıcı İpucu: ❌ | İdempotent İpucu: ✅ | Salt Okunur İpucu: ✅ | Açık Dünya İpucu: ❌

Yetkilendirme Kapsamları

Aşağıdaki OAuth kapsamlarından birini gerektirir:

  • 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