MCP Tools Reference: calendarmcp.googleapis.com

الأداة: list_events

تعرض هذه الطريقة الأحداث في التقويم المحدّد التي تتطابق مع جميع القيود المحدّدة. يجب عدم تحديد قيود زمنية ما لم يطلب المستخدم ذلك. بالنسبة إلى عمليات البحث المفتوحة حسب الكلمات الرئيسية أو المواضيع في التقويم الأساسي، يجب استخدام أداة search_events بدلاً من ذلك.

يوضّح المثال التالي كيفية استخدام curl لاستدعاء أداة list_events MCP.

طلب 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
  ],
  "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

نوع الحدث. لا يمكن تغييره بعد الإنشاء.

عمليات التعداد
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 في منتصف الليل بالتوقيت العالمي المنسّق (على سبيل المثال، '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

نوع الحدث. لا يمكن تغييره بعد الإنشاء.

عمليات التعداد
EVENT_TYPE_UNSPECIFIED يتم التعامل معها على أنّها DEFAULT.
DEFAULT حدث منتظم القيمة التلقائية
OUT_OF_OFFICE حدث بأنّك خارج المكتب
FOCUS_TIME حدث "وقت التركيز"
WORKING_LOCATION حدث عن مكان العمل
BIRTHDAY حدث خاص يستمر ليوم كامل ويتكرر سنويًا.
FROM_GMAIL حدث من Gmail لا يمكن إنشاء هذا النوع من الأحداث.

WorkingLocationType

تمثّل هذه السمة نوع مكان العمل.

عمليات التعداد
WORKING_LOCATION_TYPE_UNSPECIFIED نوع موقع العمل غير محدَّد. سيتم التعامل معها على أنّها HOME_OFFICE.
HOME_OFFICE المكتب المنزلي
CUSTOM_LOCATION موقع جغرافي مخصّص

مدى التوفّر

إعدادات مدى التوفّر لحدث معيّن

عمليات التعداد
AVAILABILITY_UNSPECIFIED تلقائي: يتم التعامل معها على أنّها BUSY.
AVAILABILITY_BUSY يحظر الوقت في التقويم.
AVAILABILITY_FREE لا يحظر الوقت.

تعليقات توضيحية للأدوات

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌