MCP Tools Reference: calendarmcp.googleapis.com

כלי: list_events

מחזירה אירועים ביומן הנתון שתואמים לכל האילוצים שצוינו. אין לציין מגבלות זמן אלא אם המשתמש ביקש זאת. לחיפושים פתוחים של מילות מפתח או חיפושים שמבוססים על נושאים ביומן הראשי, צריך להשתמש בכלי search_events.

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

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

סכימת הקלט

ListEventsRequest

ייצוג ב-JSON 
{
  "eventTypeFilter": [
    string
  ],
  "eventType": [
    enum (EventType)
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

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

string

אופציונלי. הוצא משימוש: במקומו צריך להשתמש ב-event_type.
eventType[]

enum (EventType)

אופציונלי. סוגי האירועים שיוחזרו. אם השדה ריק, מוחזרים רק סוגי האירועים הבאים: DEFAULT, OUT_OF_OFFICE, FOCUS_TIME, FROM_GMAIL

שדה איחוד _calendar_id.

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

string

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

שדה איחוד _page_size.

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

integer

אופציונלי. מספר האירועים המקסימלי בכל דף (ברירת המחדל היא 100, המקסימום הוא 250). מומלץ: 10.

שדה איחוד _page_token.

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

string

אופציונלי. טוקן של הדף הבא. משתמשים בערך מ-nextPageToken של הדף הקודם.

שדה איחוד _start_time.

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

string

אופציונלי. הגבול התחתון של טווח זמן. ההגדרה הזו חייבת להיות מוגדרת רק כשמשתמש מבקש פרק זמן ספציפי. הערך חייב להיות חותמת זמן בפורמט ISO 8601, קטן מ-end_time.

שדה איחוד _end_time.

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

string

אופציונלי. הגבול העליון של טווח הזמן. ההגדרה הזו צריכה להיקבע רק אם המשתמש מבקש פרק זמן ספציפי או זמן בעבר. חייב להיות חותמת זמן בפורמט ISO 8601 שגדולה מ-start_time.

שדה איחוד _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

אופציונלי. חיפוש חופשי לא תלוי רישיות שמתאים לכותרת, לתיאור, למיקום או למשתתפים. התאמה לאירועים שמכילים את כל מונחי השאילתה בדיוק כמו שהם (חיפוש AND).

EventType

סוג האירוע. אי אפשר לשנות אותו אחרי שהפרויקט נוצר.

טיפוסים בני מנייה (enum)
EVENT_TYPE_UNSPECIFIED הסיווג הוא DEFAULT.
DEFAULT אירוע רגיל. ערך ברירת המחדל.
OUT_OF_OFFICE אירוע מסוג 'לא בעבודה'.
FOCUS_TIME אירוע מסוג 'זמן לעצמי'.
WORKING_LOCATION אירוע בעבודה.
BIRTHDAY אירוע מיוחד שנמשך יום שלם וחוזר מדי שנה.
FROM_GMAIL אירוע מ-Gmail. אי אפשר ליצור אירועים מהסוג הזה.

סכימת הפלט

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 – גישת ניהול, כולל היכולת לשנות את הגדרות השיתוף של היומן.
חשוב: התפקיד owner שונה מבעלי הנתונים ביומן. לכל יומן יש בעלים אחד של הנתונים, אבל יכולים להיות לו כמה משתמשים עם תפקיד owner.
defaultReminders[]

object (Reminder)

תזכורות ברירת המחדל לאירועים ביומן.
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)
    }
  ],
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ],
  "attachments": [
    {
      object (Attachment)
    }
  ],
  "guestPermissions": {
    object (GuestPermissions)
  },
  "eventType": enum (EventType),
  "workingLocationProperties": {
    object (WorkingLocationProperties)
  },
  "availability": enum (Availability)
}
שדות
id

string

מזהה ייחודי.
status

string

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

  • ‫confirmed – האירוע אושר (ברירת מחדל).
  • tentative – האירוע אושר באופן זמני.
  • ‫cancelled – האירוע בוטל או נמחק.
htmlLink

string

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

string

פלט בלבד. זמן יצירה (ISO 8601).
updated

string

פלט בלבד. שעת השינוי האחרון (ISO 8601).
summary

string

שם.
description

string

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

string

אופציונלי. מיקום.
creator

object (Principal)

פלט בלבד. יוצר/ת.
organizer

object (Principal)

פלט בלבד. מארגן. המשתתפים מופיעים גם ברשימת המשתתפים אם הם משתתפים.
start

object (DateOrDateTime)

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

object (DateOrDateTime)

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

string

כללי חזרה בתור מחרוזות RRULE,‏ EXRULE,‏ RDATE או EXDATE (לפי RFC 5545). השדה הזה לא מאוכלס באירועים בודדים. צריך להגדיר את שעת ההתחלה ושעת הסיום בשדות start ו-end.
recurringEventId

string

מזהה האירוע החוזר הראשי של מופעים של אירועים חוזרים.
originalStartTime

object (DateOrDateTime)

זמן ההתחלה המקורי של מופעים חוזרים. זהו הזמן שבו המופע הזה יתחיל לפי נתוני החזרה.
transparency
(deprecated)

string

אופציונלי. הוצא משימוש: במקומו צריך להשתמש ב-availability.
visibility

string

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

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

attendees[]

object (Attendee)

משתתפים.
conferenceUrl

string

קישור לשיחת הוועידה בווידאו.
colorId

string

הצבע של האירוע. השינוי יתעדכן רק ביומן שלכם. מזהה שמפנה לרשומה בפלטת הצבעים של היומן (מחרוזת '1'-'11'):

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

overrideReminders[]

object (Reminder)

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

object (Attachment)

קבצים מצורפים.
guestPermissions

object (GuestPermissions)

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

enum (EventType)

סוג האירוע.
workingLocationProperties

object (WorkingLocationProperties)

מאפיינים של מיקום העבודה. השדה הזה מאוכלס רק אם הערך של event_type הוא WORKING_LOCATION.
availability

enum (Availability)

אופציונלי. הגדרת הזמינות.

חשבון משתמש

ייצוג ב-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').
dateTime

string

חותמת זמן בפורמט ISO 8601 (לדוגמה, '2019-11-20T08:19:06-07:00').
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.

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

string

פלט בלבד. מזהה הפרופיל.

שדה איחוד _email.

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

string

חובה. כתובת האימייל של המשתתף.

שדה איחוד _display_name.

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

string

אופציונלי. שם.

שדה איחוד _organizer.

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

boolean

פלט בלבד. האם המשתתף הוא המארגן. ברירת מחדל: false.

שדה איחוד _self.

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

boolean

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

שדה איחוד _resource.

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

boolean

אופציונלי. האם המשתתף הוא משאב (למשל חדר). אי אפשר לשנות את הערך שלו, ואפשר להגדיר אותו רק כשמוסיפים את המשתתף בפעם הראשונה. ברירת מחדל: false.

שדה איחוד _optional_attendee.

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

boolean

אופציונלי. אם המשתתף הוא אופציונלי. ברירת מחדל: false.

שדה איחוד _response_status.

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

string

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

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

שדה איחוד _comment.

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

string

פלט בלבד. תגובה לתשובה.

שדה איחוד _additional_guests.

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

integer

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

קובץ מצורף

ייצוג ב-JSON 
{

  "fileUrl": string

  "title": string
}
שדות

שדה איחוד _file_url.

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

string

חובה. כתובת URL לקישור לקובץ המצורף.

שדה איחוד _title.

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

string

אופציונלי. שם הקובץ המצורף.

GuestPermissions

ייצוג ב-JSON 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
שדות

שדה איחוד _guests_can_invite_others.

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

boolean

אופציונלי. האם המשתתפים יכולים להזמין אנשים אחרים.

שדה איחוד _guests_can_modify.

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

boolean

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

שדה איחוד _guests_can_see_guests.

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

boolean

אופציונלי. אם המשתתפים יכולים לראות את רשימת המוזמנים.

WorkingLocationProperties

ייצוג ב-JSON 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
שדות

שדה איחוד _type.

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

enum (WorkingLocationType)

אופציונלי. סוג מיקום העבודה.

שדה איחוד _custom_location_label.

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

string

אופציונלי. התווית של מיקום מותאם אישית. חובה אם סוג המבצע הוא CUSTOM_LOCATION.

EventType

סוג האירוע. אי אפשר לשנות אותו אחרי שהפרויקט נוצר.

טיפוסים בני מנייה (enum)
EVENT_TYPE_UNSPECIFIED הסיווג הוא DEFAULT.
DEFAULT אירוע רגיל. ערך ברירת המחדל.
OUT_OF_OFFICE אירוע מסוג 'לא בעבודה'.
FOCUS_TIME אירוע מסוג 'זמן לעצמי'.
WORKING_LOCATION אירוע בעבודה.
BIRTHDAY אירוע מיוחד שנמשך יום שלם וחוזר מדי שנה.
FROM_GMAIL אירוע מ-Gmail. אי אפשר ליצור אירועים מהסוג הזה.

WorkingLocationType

סוג מיקום העבודה.

טיפוסים בני מנייה (enum)
WORKING_LOCATION_TYPE_UNSPECIFIED סוג מיקום העבודה לא צוין. המערכת תתייחס אליו כאל HOME_OFFICE.
HOME_OFFICE משרד ביתי.
CUSTOM_LOCATION מיקום מותאם אישית.

זמינות

הגדרת הזמינות של אירוע.

טיפוסים בני מנייה (enum)
AVAILABILITY_UNSPECIFIED ברירת מחדל. הסיווג הוא BUSY.
AVAILABILITY_BUSY חסימת זמן ביומן.
AVAILABILITY_FREE לא חוסם זמן.

הערות על כלים

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • 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