MCP Tools Reference: calendarmcp.googleapis.com

Araç: list_events

Belirli bir takvimdeki, belirli koşulları karşılayan takvim etkinliklerini listeler.

Temel Özellikler:

  • Kullanıcının birincil takvimi veya diğer takvimler olabilen herhangi bir takvim kimliği.
  • Zaman aralığına göre filtreleme.
  • Zaman kısıtlamalarıyla eşleşen TÜM etkinlikleri alır.

Kullanıcının birincil takviminde arama yaparken mümkünse bunun yerine search_events aracını kullanın:

  • Belirli bir konu, kategori veya amaca (ör. "öğle yemeği toplantıları", "proje senkronizasyonları") uyan etkinlikler için sorgu gönderiyorsunuz.
  • Kısıtlamaları karşılayan tüm etkinlikler yerine en alakalı (en üstteki K) etkinlikleri bulmanız gerekir.
  • Anahtar kelime veya semantik arama özelliklerine ihtiyacınız var.

Bu aracı aşağıdaki gibi sorgular için kullanın:

  • Yarın takvimimde ne var?
  • 14 Temmuz 2025'te takvimimde ne var?
  • Gelecek hafta hangi toplantılarım var?
  • Bu öğleden sonra çakışan toplantım var mı?

  • Can'ın yarın hangi toplantıları var?

Örnek:

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.

Aşağıdaki örnekte, curl kullanılarak list_events MCP aracının nasıl çağrılacağı gösterilmektedir.

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

Giriş Şeması

ListEventsRequest

JSON gösterimi 
{
  "eventTypeFilter": [
    string
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Alanlar
eventTypeFilter[]

string

İsteğe bağlı. Döndürülecek etkinlik türleri. Olası değerler:

  • default - Düzenli etkinlikler (varsayılan).
  • outOfOffice - Ofis dışında etkinlikleri
  • focusTime - Odaklanma zamanı etkinlikleri.
  • workingLocation - Çalışma yeri etkinlikleri.
  • birthday - Doğum günü etkinlikleri
  • fromGmail - Gmail'den Etkinlikler.

Boşsa yalnızca şu etkinlik türleri döndürülür: default, outOfOffice, focusTime, fromGmail

_calendar_id birleşik alanı.

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

string

İsteğe bağlı. Etkinliklerin listeleneceği takvimin kimliği. Varsayılan olarak kullanıcının birincil takvimi kullanılır.

_page_size birleşik alanı.

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

integer

İsteğe bağlı. Bir sonuç sayfasında döndürülen maksimum etkinlik sayısı. Sorguyla eşleşen daha fazla etkinlik olsa bile sonuç sayfasındaki etkinlik sayısı bu değerden daha az olabilir veya hiç etkinlik olmayabilir. Eksik sayfalar, yanıttaki boş olmayan bir next_page_token alanı tarafından algılanabilir. Varsayılan olarak değer 250 etkinliktir. Sayfa boyutu hiçbir zaman 2.500 etkinlikten büyük olamaz.

_page_token birleşik alanı.

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

string

İsteğe bağlı. Hangi sonuç sayfasının döndürüleceğini belirten jeton.

_start_time birleşik alanı.

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

string

İsteğe bağlı. Bir etkinliğin bitiş zamanı için alt sınır (hariç). Yalnızca bu saatten kesinlikle sonra sona eren etkinlikler döndürülür (ör. aranacak zaman aralığının başlangıcı). Ne start_time ne de end_time sağlanmazsa varsayılan olarak geçerli saat kullanılır. Belirtilmişse end_time veya daha küçük olmalıdır. ISO 8601 zaman damgası olmalıdır. Örneğin, 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z veya 2026-06-03T10:00:00. Milisaniye belirtilebilir ancak yoksayılır.

_end_time birleşik alanı.

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

string

İsteğe bağlı. Bir etkinliğin başlangıç zamanı için üst sınır (hariç). Yalnızca bu saatten kesinlikle önce başlayan etkinlikler döndürülür (ör. arama yapılacak zaman aralığının sonu). Belirtilmişse start_time değerine eşit veya daha büyük olmalıdır. ISO 8601 zaman damgası olmalıdır. Örneğin, 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z veya 2026-06-03T10:00:00. Milisaniye belirtilebilir ancak yoksayılır.

_time_zone birleşik alanı.

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

string

İsteğe bağlı. Yanıtın oluşturulmasında ve istekteki saat dilimi içermeyen tarihler çözümlenirken kullanılan saat dilimi (IANA Saat Dilimi Veritabanı adı olarak biçimlendirilir, ör. Europe/Zurich). Varsayılan olarak takvimin saat dilimi kullanılır.

_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ırala.

_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 ve katılımcılar arasında arama yapmak için serbest biçimli arama sorgusu.

Çı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 değiştirilme zamanı (ISO 8601 zaman damgası olarak).
timeZone

string

Takvimin saat dilimi
accessRole

string

Kullanıcının bu takvimdeki erişim rolü. Salt okunur. Olası değerler:

  • none: Kullanıcının erişimi yok.
  • freeBusyReader: Kullanıcının uygun/meşgul bilgilerine okuma erişimi vardır.
  • reader - Kullanıcının takvime okuma erişimi vardır. Gizli etkinlikler, okuyucu erişimi olan kullanıcılara gösterilir ancak etkinlik ayrıntıları gizlenir.
  • writer - Kullanıcının takvime okuma ve yazma erişimi vardır. Yazma erişimi olan kullanıcılar, gizli etkinlikleri ve etkinlik ayrıntılarını görebilir.
  • owner - Kullanıcının takvime yönetici erişimi olmalıdır. Bu rol, yazar rolünün tüm izinlerine ek olarak diğer kullanıcıların erişim düzeylerini görme ve değiştirme özelliğine sahiptir. Önemli: Sahip rolü, takvimin veri sahibinden farklıdır. Bir takvimin tek bir veri sahibi vardır ancak sahip rolüne sahip birden fazla kullanıcısı olabilir.
defaultReminders[]

object (Reminder)

Kimliği doğrulanmış kullanıcının takvimindeki varsayılan hatırlatıcılar. Bu hatırlatıcılar, bu takvimdeki açıkça geçersiz kılınmayan (ör. override_reminders doldurulmayan) tüm etkinlikler için geçerlidir.
events[]

object (Event)

Takvimdeki etkinliklerin listesi.

_next_page_token birleşik alanı.

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

string

Bu sonucun sonraki sayfasına erişmek için kullanılan jeton. Başka sonuç 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. Hatırlatmanın kullanıcıya nasıl iletileceği. Olası değerler:

  • email - Hatırlatıcılar e-postayla gönderilir.
  • popup: Hatırlatmalar, kullanıcı arayüzünde pop-up olarak 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 gönderileceğ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)
    }
  ],
  "eventType": string,
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ]
}
Alanlar
id

string

Etkinliğin opak tanımlayıcısı. Yeni tek seferlik veya yinelenen etkinlikler oluştururken bunların kimliklerini belirtebilirsiniz. Gönderilen kimlikler aşağıdaki kurallara uymalıdır:

  • Kimlikte izin verilen karakterler, base32hex kodlamasında kullanılan karakterlerdir. Yani a-v arasındaki küçük harfler ve 0-9 arasındaki rakamlar. RFC2938'deki 3.1.2 bölümüne bakın.
  • Kimliğin uzunluğu 5 ile 1.024 karakter arasında olmalıdır.
  • Kimlik, her takvim için benzersiz olmalıdır.

Sistemin küresel olarak dağıtılmış yapısı nedeniyle, kimlik çakışmalarının etkinlik oluşturma sırasında tespit edileceğini garanti edemeyiz. Çakışma riskini en aza indirmek için RFC4122'de açıklanan gibi yerleşik bir UUID algoritması kullanmanızı öneririz.

Kimlik belirtmezseniz sunucu tarafından otomatik olarak oluşturulur.

icalUID ve kimliğin aynı olmadığını ve etkinlik oluşturma sırasında yalnızca birinin sağlanması gerektiğini unutmayın. Semantiklerindeki bir fark, yinelenen etkinliklerde bir etkinliğin tüm oluşumlarının farklı kimliklere sahip olması ancak hepsinin aynı icalUID'leri paylaşmasıdır.
status

string

Etkinliğin durumu. İsteğe bağlı. Olası değerler:

  • confirmed: Etkinlik onaylandı. Bu, varsayılan durumdur.
  • tentative: Etkinlik geçici olarak onaylandı.
  • cancelled: Etkinlik iptal edildi (silindi). Liste yöntemi, iptal edilen etkinlikleri yalnızca artımlı senkronizasyonda (syncToken veya updatedMin belirtildiğinde) ya da showDeleted işareti doğru olarak ayarlanmışsa döndürür. get yöntemi her zaman bunları döndürür.

İptal edildi durumu, etkinlik türüne bağlı olarak iki farklı durumu ifade eder:

  1. İptal edilmemiş bir düzenli etkinliğin iptal edilen istisnaları, bu örneğin artık kullanıcıya sunulmaması gerektiğini gösterir. Müşteriler bu etkinlikleri, üst yinelenen etkinliğin kullanım ömrü boyunca saklamalıdır.İptal edilen istisnaların yalnızca id, recurringEventId ve originalStartTime alanları için değerler içerdiği garanti edilir. Diğer alanlar boş olabilir.
  2. Diğer tüm iptal edilen etkinlikler, silinen etkinlikleri gösterir. Müşteriler, yerel olarak senkronize edilmiş kopyalarını kaldırmalıdır. Bu tür iptal edilen etkinlikler zamanla kaybolur. Bu nedenle, süresiz olarak kullanılabilir olmalarına güvenmeyin. Silinen etkinliklerde yalnızca kimlik alanının doldurulacağı garanti edilir.

Düzenleyenin takviminde, iptal edilen etkinlikler, geri yüklenebilmeleri (silinmemiş) için etkinlik ayrıntılarını (özet, konum vb.) göstermeye devam eder. Benzer şekilde, kullanıcının davet edildiği ve manuel olarak kaldırdığı etkinlikler de ayrıntı sağlamaya devam eder. Ancak showDeleted parametresi false olarak ayarlanmış artımlı senkronizasyon istekleri bu ayrıntıları döndürmez.

Bir etkinliğin düzenleyeni değişirse (örneğin, taşıma işlemiyle) ve ilk düzenleyen katılımcı listesinde yer almıyorsa yalnızca kimlik alanının doldurulacağı iptal edilmiş bir etkinlik bırakılır.
htmlLink

string

Google Takvim web kullanıcı arayüzünde bu etkinliğe giden mutlak bağlantı. Salt okunur.
created

string

Etkinliğin oluşturulma zamanı (ISO 8601 biçimli zaman damgası olarak). Salt okunur.
updated

string

Ana etkinlik verilerinin son değiştirilme zamanı (ISO 8601 biçimli zaman damgası olarak). Etkinlik hatırlatıcılarını güncellemek bu durumu değiştirmez. Salt okunur.
summary

string

Etkinliğin adı.
description

string

Etkinliğin açıklaması. HTML içerebilir. İsteğe bağlı.
location

string

Etkinliğin coğrafi konumu (serbest biçimli metin olarak). İsteğe bağlı.
creator

object (Principal)

Etkinliği oluşturan kişi. Salt okunur.
organizer

object (Principal)

Etkinliğin düzenleyicisi. Düzenleyici aynı zamanda katılımcıysa bu durum, katılımcılar bölümünde ayrı bir girişle belirtilir ve düzenleyici alanı True olarak ayarlanır. Salt okunur.
start

object (DateOrDateTime)

Etkinliğin başlangıç zamanı (girilen tarihler dahil). Düzenli bir etkinlik için bu, ilk örneğin başlangıç zamanıdır.
end

object (DateOrDateTime)

Etkinliğin bitiş zamanı (girilen tarihler dahil değil). Düzenli etkinliklerde bu, ilk örneğin bitiş zamanıdır.
recurrence[]

string

Yinelenen bir etkinlik için RFC5545'te belirtildiği gibi RRULE, EXRULE, RDATE ve EXDATE satırlarının listesi. Bu alanda DTSTART ve DTEND satırlarına izin verilmediğini unutmayın. Etkinlik başlangıç ve bitiş zamanları, başlangıç ve bitiş alanlarında belirtilir. Bu alan, tek seferlik etkinlikler veya yinelenen etkinliklerin örnekleri için atlanır.
recurringEventId

string

Yinelenen bir etkinliğin örneği için bu, örneğin ait olduğu düzenli etkinliğin kimliğidir. Değişmez.
originalStartTime

object (DateOrDateTime)

Düzenli bir etkinliğin örneği için bu, recurringEventId ile tanımlanan düzenli etkinlikteki yinelenme verilerine göre bu etkinliğin başlayacağı zamandır. Örnek farklı bir zamana taşınmış olsa bile, düzenli etkinlik serisindeki örneği benzersiz şekilde tanımlar. Değişmez.
transparency

string

Etkinliğin takvimde zamanı engelleyip engellemediği. İsteğe bağlı. Olası değerler:

  • opaque - Varsayılan değer. Etkinlik, takvimde zamanı engeller. Bu, Takvim kullanıcı arayüzünde "Beni meşgul olarak göster" ayarını yapmaya eşdeğerdir.
  • transparent: Etkinlik, takvimde zamanı engellemez. Bu, Takvim kullanıcı arayüzünde "Beni şu şekilde göster" ayarını "Müsait" olarak ayarlamaya eşdeğerdir.
visibility

string

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

  • default: Takvimdeki etkinlikler için varsayılan görünürlüğü kullanır. Bu, varsayılan değerdir.
  • public: Etkinlik herkese açıktır ve etkinlik ayrıntıları takvimin tüm okuyucularına görünür.
  • private - Etkinlik özeldir ve etkinlik ayrıntılarını yalnızca etkinlik katılımcıları görüntüleyebilir.
  • confidential - Etkinlik gizlidir. Bu değer, uyumluluk nedeniyle sağlanır.
attendees[]

object (Attendee)

Etkinliğe katılanlar.
eventType

string

Etkinliğin türü. Bu ayar, etkinlik oluşturulduktan sonra değiştirilemez. Olası değerler:

  • birthday - Yıllık olarak tekrarlanan, tüm gün süren özel bir etkinlik.
  • default - Normal bir etkinlik veya daha fazla belirtilmemiş.
  • focusTime - Odaklanma zamanı etkinliği
  • fromGmail - Gmail'den bir etkinlik. Bu tür etkinlikler oluşturulamaz.
  • outOfOffice: Ofis dışında etkinliği.
  • workingLocation: Çalışma yeri etkinliği.
conferenceUrl

string

Etkinliğin Google Meet bağlantısı.
colorId

string

Etkinlik rengi kimliği (dize 1-11):

  • 1: Lavanta
  • 2: Sage
  • 3: Üzüm
  • 4: Flamingo
  • 5: Muz
  • 6: Mandalina
  • 7: Tavus kuşu
  • 8: Grafit
  • 9: Yaban mersini
  • 10: Fesleğen
  • 11: Domates.

Google Takvim'de etkinlik renkleri, etkinlik veya seri bazında ayarlanabilen kategoriler olarak işlev görür. Kullanıcılar, web kullanıcı arayüzünde renklere özel etiketler atayabilir (ör.1:1s, Break). Ancak API yalnızca sayısal kimlikleri kullanıma sunar, bu etiketleri kullanıma sunmaz. Yalnızca kendi takvim görünümünüzü etkiler. Her katılımcı kendi etkinlik rengini kontrol eder.
overrideReminders[]

object (Reminder)

Bu etkinlik için tanımlanan hatırlatıcılar, takvimin varsayılan hatırlatıcılarını geçersiz kılar. Ayarlanmazsa takvimdeki varsayılan hatırlatıcılar kullanılır.

Ana hesap

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

string

Asıl kullanıcının (takvim) e-posta adresi.
displayName

string

Varsa müdürün adı.
self

boolean

Bu asıl kullanıcının, etkinliğin bu kopyasının göründüğü takvime karşılık gelip gelmediği. Salt okunur. Varsayılan değer False'tur.

DateOrDateTime

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

string

UTC gece yarısı saatinde ISO 8601 biçiminde tarih (ör. 2019-11-20T00:00:00Z). Bu alan ayarlanırsa date_time ayarlanmamalıdır.
dateTime

string

2019-11-20T08:19:06-07:00 veya 2019-11-20T08:19:06Z gibi ISO 8601 biçimli bir zaman damgası. Bu alan ayarlanırsa date ayarlanmamalıdır.
timeZone

string

Varsa 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

string

Katılımcının profil kimliği (varsa)
email

string

Katılımcının e-posta adresi (varsa). Katılımcı eklerken bu alan bulunmalıdır. RFC5322'ye göre geçerli bir e-posta adresi olmalıdır. Katılımcı eklerken gereklidir.
displayName

string

Varsa katılımcının adı. İsteğe bağlı.
organizer

boolean

Katılımcının etkinliğin düzenleyicisi olup olmadığı. Salt okunur. Varsayılan değer False'tur.
self

boolean

Bu giriş, etkinliğin bu kopyasının göründüğü takvimi temsil edip etmediği. Salt okunur. Varsayılan değer False'tur.
resource

boolean

Katılımcının kaynak olup olmadığı. Yalnızca katılımcı etkinliğe ilk kez eklendiğinde ayarlanabilir. Sonraki değişiklikler yoksayılır. İsteğe bağlı. Varsayılan değer False'tur.
optionalAttendee

boolean

Bu katılımcının isteğe bağlı olup olmadığı. İsteğe bağlı. Varsayılan değer False'tur.
responseStatus

string

Katılımcının yanıt durumu. Olası değerler:

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

string

Katılımcının yanıt yorumu. İsteğe bağlı.
additionalGuests

integer

Ek davetli sayısı. İsteğe bağlı. Varsayılan değer 0'dır.

Araç Ek Açıklamaları

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