MCP Tools Reference: calendarmcp.googleapis.com

الأداة: list_events

تعرض هذه الطريقة أحداث التقويم في تقويم معيّن يستوفي الشروط المحدّدة.

الميزات الأساسية:

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

إذا كانت أداة search_events متاحة، استخدِمها بدلاً من ذلك لإجراء عمليات البحث في التقويم الأساسي للمستخدم في الحالات التالية:

  • أنت تبحث عن أحداث تتطابق مع موضوع أو فئة أو نية معيّنة (مثل "اجتماعات غداء" أو "مزامنة المشاريع").
  • عليك العثور على الأحداث الأكثر صلةً (أعلى K) بدلاً من جميع الأحداث التي تستوفي القيود.
  • تحتاج إلى إمكانات البحث عن الكلمات الرئيسية أو البحث الدلالي.

استخدِم هذه الأداة للاستعلامات مثل:

  • ماذا يتضمّن تقويمي ليوم غد؟
  • ماذا يتضمّن تقويمي ليوم 14 يوليو 2025؟
  • ما هي اجتماعاتي الأسبوع القادم؟
  • هل لديّ أي مواعيد متعارضة بعد ظهر اليوم؟

  • ما هي الاجتماعات التي سيحضرها عصام غدًا؟

مثال:

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 لاستدعاء أداة 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
  ],

  "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 حدثًا. لا يمكن أن يتجاوز حجم الصفحة 2500 حدث.

حقل الربط _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 و1024 حرفًا
  • يجب أن يكون المعرّف فريدًا لكل تقويم

نظرًا إلى طبيعة النظام الموزّعة على مستوى العالم، لا يمكننا ضمان رصد تعارضات أرقام التعريف عند إنشاء الحدث. للحدّ من خطر حدوث تعارضات، ننصحك باستخدام خوارزمية UUID ثابتة، مثل تلك الموضّحة في RFC4122.

إذا لم تحدّد معرّفًا، سيتم إنشاؤه تلقائيًا بواسطة الخادم.

يُرجى العِلم أنّ icalUID والمعرّف ليسا متطابقَين ويجب توفير أحدهما فقط عند إنشاء الحدث. أحد الاختلافات في دلالاتها هو أنّه في الأحداث المتكرّرة، يكون لكل تكرار لحدث واحد معرّفات مختلفة، بينما تشترك جميعها في معرّفات icalUID نفسها.
status

string

تمثّل هذه السمة حالة الحدث. اختياريّ. القيم المحتملة هي:

  • ‫confirmed: تم تأكيد الحدث. هذه هي الحالة التلقائية.
  • tentative: تم تأكيد الحدث بشكل مبدئي.
  • cancelled: تم إلغاء الحدث (حذفه). لا تعرض طريقة القائمة الأحداث الملغاة إلا عند المزامنة التدريجية (عند تحديد syncToken أو updatedMin) أو إذا تم ضبط العلامة showDeleted على "صحيح". تعرض الطريقة get هذه القيم دائمًا.

تمثّل الحالة "تم إلغاؤه" حالتين مختلفتين حسب نوع الحدث:

  1. تشير الاستثناءات الملغاة لحدث متكرّر غير ملغى إلى أنّه يجب ألا يتم عرض هذه النسخة للمستخدم بعد الآن. على العملاء تخزين هذه الأحداث طوال مدة الحدث المتكرّر الرئيسي.ولا يُضمن أن تحتوي الاستثناءات الملغاة على قيم إلا للحقول id وrecurringEventId وoriginalStartTime. قد تكون الحقول الأخرى فارغة.
  2. تمثّل جميع الأحداث الملغاة الأخرى الأحداث المحذوفة. على العملاء إزالة النُسخ التي تمت مزامنتها على أجهزتهم. وستختفي هذه الأحداث الملغاة في النهاية، لذا لا تعتمد على توفّرها إلى أجل غير مسمى. يتم ضمان تعبئة حقل المعرّف فقط للأحداث المحذوفة.

في تقويم المنظِّم، تواصل الأحداث الملغاة عرض تفاصيل الحدث (الملخّص والموقع الجغرافي وما إلى ذلك) حتى يمكن استعادتها (إلغاء حذفها). وبالمثل، تستمر الأحداث التي تمت دعوة المستخدم إليها وأزالها يدويًا في تقديم التفاصيل. ومع ذلك، لن تعرض طلبات المزامنة التدريجية التي تم ضبط showDeleted فيها على "خطأ" هذه التفاصيل.

إذا غيّر حدث ما منظّمه (على سبيل المثال، من خلال عملية النقل) ولم يكن المنظّم الأصلي في قائمة المشاركين، سيؤدي ذلك إلى ترك حدث تم إلغاؤه حيث يكون حقل المعرّف فقط مضمونًا أنّه سيتم ملؤه.
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 لحدث متكرّر، كما هو محدّد في RFC5545. يُرجى العِلم أنّه لا يُسمح باستخدام سطرَي DTSTART وDTEND في هذا الحقل، بل يتم تحديد وقتَي بدء الحدث وانتهائه في حقلَي البدء والانتهاء. يتم حذف هذا الحقل للأحداث الفردية أو مثيلات الأحداث المتكررة.
recurringEventId

string

بالنسبة إلى مثيل لحدث متكرّر، هذا هو معرّف الحدث المتكرّر الذي ينتمي إليه هذا المثيل. غير قابل للتغيير
originalStartTime

object (DateOrDateTime)

بالنسبة إلى نسخة من حدث متكرّر، هذا هو الوقت الذي سيبدأ فيه هذا الحدث وفقًا لبيانات التكرار في الحدث المتكرّر الذي تم تحديده بواسطة recurringEventId. يحدّد هذا المعرّف بشكل فريد الموعد ضمن سلسلة الأحداث المتكرّرة حتى إذا تم نقل الموعد إلى وقت مختلف. غير قابل للتغيير
transparency

string

تحديد ما إذا كان الحدث يحظر وقتًا في التقويم اختياريّ. القيم المحتملة هي:

  • ‫opaque - القيمة التلقائية يؤدي الحدث إلى حظر الوقت في التقويم. هذا الإعداد يعادل ضبط "الحالة" على "مشغول" في واجهة مستخدم "تقويم Google".
  • transparent: لا يحجز الحدث وقتًا في التقويم. هذا الإعداد يعادل ضبط خيار "الحالة" على "متاح" في واجهة مستخدم "تقويم Google".
visibility

string

تمثّل هذه السمة مستوى رؤية الحدث. اختياريّ. القيم المحتملة هي:

  • default - يستخدم مستوى الظهور التلقائي للأحداث في التقويم. هذه هي القيمة التلقائية.
  • public: الحدث علني وتفاصيله مرئية لجميع قارئي التقويم.
  • private - الحدث خاص ويمكن للمدعوين فقط الاطّلاع على تفاصيله.
  • confidential: الحدث خاص. يتم توفير هذه القيمة لأسباب تتعلّق بالتوافق.
attendees[]

object (Attendee)

تمثّل هذه السمة المشاركين في الفعالية.
eventType

string

نوع الحدث المحدّد. لا يمكن تعديل هذا الخيار بعد إنشاء الحدث. القيم المحتملة هي:

  • birthday: حدث خاص يستمر طوال اليوم ويتكرر سنويًا.
  • default: حدث عادي أو لم يتم تحديد نوعه بشكل أكبر.
  • focusTime: حدث لوقت التركيز
  • fromGmail: حدث من Gmail لا يمكن إنشاء هذا النوع من الأحداث.
  • outOfOffice: حدث بأنّك خارج المكتب
  • ‫workingLocation: حدث مكان العمل
conferenceUrl

string

رابط Google Meet الخاص بالحدث
colorId

string

رقم تعريف لون الحدث (السلسلة 1-11):

  • ‫1: الخزامى
  • ‫2: Sage
  • ‫3: عنب
  • ‫4: Flamingo
  • ‫5: موز
  • ‫6: برتقالي محمرّ
  • ‫7: طاووس
  • ‫8: غرافيت
  • ‫9: أزرق توتي
  • ‫10: الريحان
  • ‫11: طماطم

في "تقويم Google"، تعمل ألوان الأحداث كفئات يمكن ضبطها لكل حدث أو لكل سلسلة أحداث. يمكن للمستخدمين تعيين تصنيفات مخصّصة للألوان في واجهة المستخدم على الويب (مثل 1:1s وBreak)، ولكن لا تعرض واجهة برمجة التطبيقات سوى المعرّفات الرقمية، وليس هذه التصنيفات. يؤثّر ذلك فقط على طريقة عرض تقويمك، إذ يتحكّم كل مشارِك في لون الحدث الخاص به.
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 في منتصف الليل بالتوقيت العالمي المنسّق، مثل 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.

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

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