MCP Tools Reference: calendarmcp.googleapis.com

כלי: list_events

מציג רשימה של אירועים ביומן מסוים שעומדים בתנאים שצוינו.

התכונות העיקריות:

  • כל מזהה יומן, שיכול להיות היומן הראשי של המשתמש או יומנים אחרים.
  • סינון לפי טווח זמן.
  • מאחזר את כל האירועים שתואמים למגבלות הזמן.

אם הכלי search_events זמין, כדאי להשתמש בו במקום זאת לחיפושים ביומן הראשי של המשתמש במקרים הבאים:

  • אתם מחפשים אירועים שתואמים לנושא, לקטגוריה או לכוונת חיפוש ספציפיים (לדוגמה, 'פגישות צהריים', 'עדכונים לגבי פרויקט').
  • אתם צריכים למצוא את האירועים הרלוונטיים ביותר (ה-K העליונים) ולא את כל האירועים שעומדים באילוצים.
  • אתם צריכים יכולות חיפוש לפי מילות מפתח או חיפוש סמנטי.

אפשר להשתמש בכלי הזה לשאילתות כמו:

  • מה האירועים ביומן שלי מחר?
  • מה האירועים שרשומים ביומן שלי ל-14 ביולי 2025?
  • מה הפגישות שלי בשבוע הבא?
  • יש לי פגישות שנקבעו בזמנים חופפים היום בצהריים?

  • What meetings does John have tomorrow?‎ (אילו פגישות יש לטל מחר?)

דוגמה:

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.

בדוגמה הבאה מוצג שימוש ב-curl כדי להפעיל את כלי ה-MCP‏ list_events.

בקשת 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
}'

סכימת הקלט

ListEventsRequest

ייצוג ב-JSON 
{
  "eventTypeFilter": [
    string
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
שדות
eventTypeFilter[]

string

אופציונלי. סוגי האירועים שיוחזרו. הערכים האפשריים הם:

  • ‫default – אירועים רגילים (ברירת מחדל).
  • ‫outOfOffice – אירועים מסוג 'לא בעבודה'.
  • ‫focusTime – אירועים מסוג 'זמן לעצמי'.
  • ‫workingLocation – אירועים שקשורים למיקום העבודה.
  • birthday – אירועים של ימי הולדת.
  • ‫fromGmail – אירועים מ-Gmail.

אם השדה ריק, מוחזרים רק סוגי האירועים הבאים: default, outOfOffice, focusTime, fromGmail

שדה איחוד _calendar_id.

הערך _calendar_id יכול להיות רק אחד מהבאים:
calendarId

string

אופציונלי. מזהה היומן שממנו רוצים להציג את האירועים. ברירת המחדל היא היומן הראשי של המשתמש.

שדה איחוד _page_size.

הערך _page_size יכול להיות רק אחד מהבאים:
pageSize

integer

אופציונלי. המספר המקסימלי של אירועים שמוחזרים בדף תוצאות אחד. יכול להיות שמספר האירועים בדף שיתקבל יהיה קטן מהערך הזה, או אפילו אפס, גם אם יש עוד אירועים שתואמים לשאילתה. אפשר לזהות דפים לא שלמים באמצעות השדה next_page_token בתגובה, שלא ריק. כברירת מחדל, הערך הוא 250 אירועים. גודל הדף לא יכול להיות גדול מ-2,500 אירועים.

שדה איחוד _page_token.

הערך _page_token יכול להיות רק אחד מהבאים:
pageToken

string

אופציונלי. אסימון שמציין איזה דף תוצאות להציג.

שדה איחוד _start_time.

הערך _start_time יכול להיות רק אחד מהבאים:
startTime

string

אופציונלי. הגבול התחתון (לא כולל) של שעת הסיום של אירוע. רק אירועים שמסתיימים אחרי השעה הזו יוחזרו (כלומר, תחילת חלון הזמן לחיפוש). אם לא מציינים ערך לפרמטר start_time או לפרמטר end_time, ערך ברירת המחדל הוא השעה הנוכחית. אם מציינים ערך, הוא חייב להיות קטן מ-end_time או שווה לו. חייב להיות חותמת זמן בפורמט ISO 8601. לדוגמה: 2026-06-03T10:00:00-07:00,‏ 2026-06-03T10:00:00Z או 2026-06-03T10:00:00. אפשר לציין אלפיות השנייה, אבל המערכת מתעלמת מהן.

שדה איחוד _end_time.

הערך _end_time יכול להיות רק אחד מהבאים:
endTime

string

אופציונלי. הגבול העליון (לא כולל) של שעת ההתחלה של אירוע. יוחזרו רק אירועים שהתחילו לפני השעה הזו (כלומר, לפני סוף חלון הזמן לחיפוש). אם מציינים ערך, הוא חייב להיות גדול מ-start_time או שווה לו. חייב להיות חותמת זמן בפורמט ISO 8601. לדוגמה: 2026-06-03T10:00:00-07:00,‏ 2026-06-03T10:00:00Z או 2026-06-03T10:00:00. אפשר לציין אלפיות השנייה, אבל המערכת מתעלמת מהן.

שדה איחוד _time_zone.

הערך _time_zone יכול להיות רק אחד מהבאים:
timeZone

string

אופציונלי. אזור הזמן שבו נעשה שימוש בתגובה כדי לפתור תאריכים ללא אזור זמן בשאילתה (בפורמט של שם מסד הנתונים של אזור זמן IANA, למשל Europe/Zurich). ברירת המחדל היא אזור הזמן של היומן.

שדה איחוד _order_by.

הערך _order_by יכול להיות רק אחד מהבאים:
orderBy

string

אופציונלי. הסדר שבו צריך להחזיר את האירועים. הערכים האפשריים הם:

  • ‫default – לא צוין, אבל הסדר נקבע (ברירת מחדל).
  • ‫startTime – מיון לפי שעת התחלה בסדר עולה.
  • ‫startTimeDesc – מיון לפי שעת התחלה בסדר יורד.
  • ‫lastModified – מיון לפי תאריך השינוי האחרון בסדר עולה.

שדה איחוד _full_text.

הערך _full_text יכול להיות רק אחד מהבאים:
fullText

string

אופציונלי. שאילתת חיפוש חופשית לחיפוש בכותרת, בתיאור, במיקום ובמשתתפים.

סכימת פלט

ListEventsResponse

ייצוג ב-JSON 
{
  "summary": string,
  "description": string,
  "updated": string,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      object (Reminder)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],

  "nextPageToken": string
}
שדות
summary

string

השם של היומן.
description

string

תיאור היומן.
updated

string

השעה שבה בוצע השינוי האחרון ביומן (כחותמת זמן בפורמט ISO 8601).
timeZone

string

אזור הזמן של היומן.
accessRole

string

תפקיד הגישה של המשתמש ליומן הזה. קריאה בלבד. הערכים האפשריים הם:

  • ‫none – למשתמש אין גישה.
  • ‫freeBusyReader – למשתמש יש הרשאת קריאה של מידע על מצב הזמינות (פנוי/עסוק).
  • ‫reader – למשתמש יש גישת קריאה ליומן. אירועים פרטיים יוצגו למשתמשים עם גישת קריאה, אבל פרטי האירועים יוסתרו.
  • ‫writer – למשתמש יש גישת קריאה וכתיבה ליומן. אירועים פרטיים יופיעו למשתמשים עם גישת כתיבה, ופרטי האירוע יהיו גלויים.
  • ‫owner – למשתמש יש גישת ניהול ליומן. לתפקיד הזה יש את כל ההרשאות של תפקיד הכותב, עם היכולת הנוספת לראות ולשנות את רמות הגישה של משתמשים אחרים. חשוב לדעת: התפקיד 'בעלים' שונה מבעלי הנתונים ביומן. ליומן יש בעלים אחד של הנתונים, אבל יכולים להיות בו כמה משתמשים עם תפקיד בעלים.
defaultReminders[]

object (Reminder)

תזכורות ברירת המחדל ביומן של המשתמש המאומת. התזכורות האלה חלות על כל האירועים ביומן שלא מוגדרות להם תזכורות אחרות (כלומר, לא מוגדרים להם ערכים ב-override_reminders).
events[]

object (Event)

רשימת האירועים ביומן.

שדה איחוד _next_page_token.

הערך _next_page_token יכול להיות רק אחד מהבאים:
nextPageToken

string

אסימון שמשמש לגישה לדף הבא של התוצאה הזו. השדה מושמט אם אין תוצאות נוספות.

תזכורת

ייצוג ב-JSON 
{

  "method": string

  "minutes": integer
}
שדות

שדה איחוד _method.

הערך _method יכול להיות רק אחד מהבאים:
method

string

חובה. איך התזכורת מועברת למשתמש. הערכים האפשריים הם:

  • email – התזכורות נשלחות באימייל.
  • ‫popup – התזכורות נשלחות באמצעות חלון קופץ בממשק המשתמש.

שדה איחוד _minutes.

הערך _minutes יכול להיות רק אחד מהבאים:
minutes

integer

חובה. מספר הדקות לפני האירוע שבהן התזכורת צריכה להישלח.

אירוע

ייצוג ב-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)
    }
  ]
}
שדות
id

string

מזהה אטום של האירוע. כשיוצרים אירועים חדשים, חד-פעמיים או חוזרים, אפשר לציין את המזהים שלהם. המזהים שאתם מספקים חייבים לעמוד בכללים הבאים:

  • התווים שמותרים במזהה הם אלה שמשמשים בקידוד base32hex, כלומר אותיות קטנות a-v וספרות 0-9.אפשר לעיין בסעיף 3. 1.2 ב-RFC2938.
  • אורך המזהה צריך להיות בין 5 ל-1,024 תווים
  • המזהה חייב להיות ייחודי לכל לוח שנה

בגלל האופי המבוזר של המערכת, אנחנו לא יכולים להבטיח שיתגלו התנגשויות של מזהים בזמן יצירת האירוע. כדי לצמצם את הסיכון להתנגשויות, מומלץ להשתמש באלגוריתם UUID מבוסס, כמו זה שמתואר ב-RFC4122.

אם לא מציינים מזהה, השרת יוצר אותו באופן אוטומטי.

שימו לב: הערכים של icalUID ו-id לא זהים, וצריך לספק רק אחד מהם בזמן יצירת האירוע. הבדל אחד בסמנטיקה שלהם הוא שבאירועים חוזרים, לכל המופעים של אירוע אחד יש מזהים שונים, אבל לכולם יש את אותם מזהי icalUID.
status

string

הסטטוס של האירוע. אופציונלי. הערכים האפשריים הם:

  • ‫confirmed – האירוע אושר. זהו סטטוס ברירת המחדל.
  • ‫tentative – האירוע אושר באופן זמני.
  • ‫cancelled – האירוע בוטל (נמחק). השיטה list מחזירה אירועים שבוטלו רק בסנכרון מצטבר (כשמציינים syncToken או updatedMin) או אם הדגל showDeleted מוגדר כ-True. השיטה get תמיד מחזירה אותם.

הסטטוס 'בוטל' מייצג שני מצבים שונים, בהתאם לסוג האירוע:

  1. מקרים חריגים שבוטלו של אירוע חוזר שלא בוטל מציינים שהמופע הזה לא צריך להיות מוצג יותר למשתמש. הלקוחות צריכים לאחסן את האירועים האלה למשך משך החיים של אירוע האב החוזר.מובטח שרק בשדות id, ‏ recurringEventId ו-originalStartTime של חריגים שבוטלו יאוכלסו ערכים. יכול להיות ששאר השדות יהיו ריקים.
  2. כל שאר האירועים שבוטלו מייצגים אירועים שנמחקו. הלקוחות צריכים להסיר את העותקים שסונכרנו באופן מקומי. אירועים שבוטלו ייעלמו בסופו של דבר, לכן לא כדאי להסתמך על כך שהם יהיו זמינים ללא הגבלת זמן. השדה id מאוכלס בוודאות רק באירועים שנמחקו.

ביומן של מארגן האירוע, פרטי האירוע (סיכום, מיקום וכו') ממשיכים להיות גלויים גם אחרי ביטול האירוע, כדי שאפשר יהיה לשחזר אותו (לבטל את המחיקה). באופן דומה, האירועים שהמשתמש הוזמן אליהם והוסרו על ידו באופן ידני ממשיכים לספק פרטים. עם זאת, בקשות לסנכרון מצטבר עם הערך false בהגדרה showDeleted לא יחזירו את הפרטים האלה.

אם המארגן של אירוע משתנה (לדוגמה, באמצעות פעולת ההעברה) והמארגן המקורי לא נמצא ברשימת המשתתפים, יישאר אירוע מבוטל שרק השדה id שלו יאוכלס בוודאות.
htmlLink

string

קישור מוחלט לאירוע הזה בממשק המשתמש האינטרנטי של יומן Google. קריאה בלבד.
created

string

זמן היצירה של האירוע (חותמת זמן בפורמט ISO 8601). קריאה בלבד.
updated

string

השעה שבה בוצע השינוי האחרון בנתוני האירוע הראשי (חותמת זמן בפורמט ISO 8601). העדכון של התזכורות לאירועים לא ישנה את זה. קריאה בלבד.
summary

string

שם האירוע.
description

string

תיאור האירוע. יכול להכיל HTML. אופציונלי.
location

string

המיקום הגיאוגרפי של האירוע כטקסט חופשי. אופציונלי.
creator

object (Principal)

מי שיצר את האירוע. קריאה בלבד.
organizer

object (Principal)

מארגן האירוע. אם המארגן הוא גם משתתף, זה מצוין ברשומה נפרדת ברשימת המשתתפים, כשהשדה 'מארגן' מוגדר כ-True. קריאה בלבד.
start

object (DateOrDateTime)

שעת ההתחלה (כולל) של האירוע. באירוע חוזר, זו שעת ההתחלה של המופע הראשון.
end

object (DateOrDateTime)

שעת הסיום (לא כולל) של האירוע. באירוע חוזר, זו שעת הסיום של המופע הראשון.
recurrence[]

string

רשימה של שורות RRULE, ‏ EXRULE, ‏ RDATE ו-EXDATE לאירוע חוזר, כפי שמצוין ב-RFC5545. שימו לב שאסור להשתמש בשורות DTSTART ו-DTEND בשדה הזה. שעות ההתחלה והסיום של האירוע מצוינות בשדות ההתחלה והסיום. השדה הזה לא מופיע באירועים בודדים או במופעים של אירועים חוזרים.
recurringEventId

string

במקרה של מופע של אירוע חוזר, זהו המזהה של האירוע החוזר שאליו שייך המופע הזה. אי אפשר לשנות.
originalStartTime

object (DateOrDateTime)

במקרה של מופע של אירוע חוזר, זהו הזמן שבו האירוע הזה יתחיל בהתאם לנתוני החזרה באירוע החוזר שמזוהה על ידי recurringEventId. המזהה הזה מזהה באופן ייחודי את המופע בסדרת האירועים החוזרים, גם אם המופע הועבר לשעה אחרת. אי אפשר לשנות.
transparency

string

האם האירוע חוסם זמן ביומן. אופציונלי. הערכים האפשריים הם:

  • ‫opaque – ערך ברירת המחדל. האירוע חוסם זמן ביומן. ההגדרה הזו שוות ערך להגדרה 'הצגת הזמינות שלי' כ'תפוס/ה' בממשק המשתמש של יומן Google.
  • ‫transparent – האירוע לא חוסם זמן ביומן. ההגדרה הזו שוות ערך להגדרה 'הצגת הסטטוס שלי' כ'זמין/ה' בממשק המשתמש של היומן.
visibility

string

הרשאות הגישה לאירוע. אופציונלי. הערכים האפשריים הם:

  • ‫default – משתמש בהרשאות הגישה שמוגדרות כברירת מחדל לאירועים ביומן. זה ערך ברירת המחדל.
  • ‫public - האירוע גלוי לכולם וכל מי שיש לו גישה ליומן יכול לראות את פרטי האירוע.
  • ‫private – האירוע פרטי ורק המשתתפים יכולים לראות את הפרטים שלו.
  • ‫confidential – האירוע פרטי. הערך הזה מסופק מטעמי תאימות.
attendees[]

object (Attendee)

המשתתפים באירוע.
eventType

string

סוג ספציפי של האירוע. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את האירוע. הערכים האפשריים הם:

  • ‫birthday – אירוע מיוחד של יום שלם שחוזר מדי שנה.
  • ‫default – אירוע רגיל או אירוע שלא צוין לגביו פרטים נוספים.
  • ‫focusTime – אירוע מסוג 'זמן לעצמי'.
  • ‫fromGmail – אירוע מ-Gmail. אי אפשר ליצור אירועים מהסוג הזה.
  • ‫outOfOffice – אירוע מסוג 'לא בעבודה'.
  • ‫workingLocation – אירוע של מיקום עבודה.
conferenceUrl

string

הקישור לפגישה ב-Meet של האירוע.
colorId

string

מזהה צבע האירוע (מחרוזת 1-11):

  • ‫1: לבנדר
  • ‫2: Sage
  • ‫3: ענבים
  • ‫4: פלמינגו
  • ‫5: בננה
  • ‫6: קלמנטינה
  • ‫7: Peacock
  • ‫8: גרפיט
  • ‫9: אוכמנית
  • ‫10: בזיליקום
  • ‫11: עגבנייה.

ביומן Google, צבעי האירועים משמשים כקטגוריות שאפשר להגדיר לכל אירוע או לכל סדרה. משתמשים יכולים להקצות תוויות בהתאמה אישית לצבעים בממשק המשתמש באינטרנט (לדוגמה, 1:1s, Break), אבל ה-API חושף רק מזהים מספריים, ולא את התוויות האלה. השינוי משפיע רק על התצוגה שלכם ביומן – כל משתתף שולט בצבע של האירוע ביומן שלו.
overrideReminders[]

object (Reminder)

תזכורות שהוגדרו לאירוע הזה, שדוחפות את ברירת המחדל של התזכורות ביומן. אם לא מגדירים את המדיניות, המערכת משתמשת בתזכורות שמוגדרות כברירת מחדל ביומן.

חשבון משתמש

ייצוג ב-JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
שדות
email

string

כתובת האימייל של החשבון הראשי (היומן).
displayName

string

השם של המנהל/ת, אם יש כזה.
self

boolean

האם הגורם הזה תואם ליומן שבו מופיעה העותק הזה של האירוע. קריאה בלבד. ברירת המחדל היא False.

DateOrDateTime

ייצוג ב-JSON 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
שדות
date

string

תאריך בפורמט ISO 8601 בחצות UTC, כמו 2019-11-20T00:00:00Z. אם השדה הזה מוגדר, אסור להגדיר את date_time.
dateTime

string

חותמת זמן בפורמט ISO 8601, כמו 2019-11-20T08:19:06-07:00 או 2019-11-20T08:19:06Z. אם השדה הזה מוגדר, אסור להגדיר את date.
timeZone

string

השם של אזור הזמן ב-TZDB, אם יש כזה.

משתתף/ת

ייצוג ב-JSON 
{
  "id": string,
  "email": string,
  "displayName": string,
  "organizer": boolean,
  "self": boolean,
  "resource": boolean,
  "optionalAttendee": boolean,
  "responseStatus": string,
  "comment": string,
  "additionalGuests": integer
}
שדות
id

string

מזהה הפרופיל של המשתתף, אם הוא זמין.
email

string

כתובת האימייל של המשתתף, אם היא זמינה. חובה לציין את השדה הזה כשמוסיפים משתתף. היא חייבת להיות כתובת אימייל תקינה לפי RFC5322. חובה כשמוסיפים משתתף.
displayName

string

השם של המשתתף, אם הוא זמין. אופציונלי.
organizer

boolean

האם המשתתף הוא מארגן האירוע. קריאה בלבד. ברירת המחדל היא False.
self

boolean

האם הרשומה הזו מייצגת את היומן שבו מופיעה העותק הזה של האירוע. קריאה בלבד. ברירת המחדל היא False.
resource

boolean

האם המשתתף הוא משאב. אפשר להגדיר את ההרשאה הזו רק כשמוסיפים את המשתתף לאירוע בפעם הראשונה. המערכת מתעלמת משינויים נוספים. אופציונלי. ברירת המחדל היא False.
optionalAttendee

boolean

אם המשתתף הזה הוא אופציונלי. אופציונלי. ברירת המחדל היא False.
responseStatus

string

סטטוס התשובה של המשתתף. הערכים האפשריים הם:

  • ‫needsAction – המשתתף לא הגיב להזמנה (מומלץ לאירועים חדשים).
  • ‫declined – המשתתף דחה את ההזמנה.
  • ‫tentative – המשתתף אישר את ההזמנה באופן זמני.
  • ‫accepted – המשתתף אישר את ההזמנה.
comment

string

התגובה של המשתתף. אופציונלי.
additionalGuests

integer

מספר האורחים הנוספים. אופציונלי. ערך ברירת המחדל הוא 0.

הערות על כלי

רמז הרסני: ❌ | רמז אידמפוטנטי: ✅ | רמז לקריאה בלבד: ✅ | רמז לעולם פתוח: ❌