MCP Tools Reference: calendarmcp.googleapis.com

ابزار: list_events

رویدادهای تقویم را در یک تقویم مشخص که شرایط داده شده را برآورده می‌کند، فهرست می‌کند.

ویژگی‌های کلیدی:

  • هر شناسه تقویم، که می‌تواند تقویم اصلی کاربر یا موارد دیگر باشد.
  • فیلتر کردن محدوده زمانی
  • تمام رویدادهایی را که با محدودیت‌های زمانی مطابقت دارند، بازیابی می‌کند.

در صورت وجود، از ابزار search_events برای جستجو در تقویم اصلی کاربر استفاده کنید اگر:

  • شما در حال جستجوی رویدادهایی هستید که با یک موضوع، دسته یا هدف خاص مطابقت دارند (مثلاً «جلسات ناهار»، «همگام‌سازی پروژه»).
  • شما باید (K رویداد برتر) مرتبط‌ترین آنها را پیدا کنید، نه اینکه تمام رویدادهایی را که محدودیت‌ها را برآورده می‌کنند، پیدا کنید.
  • شما به قابلیت‌های جستجوی کلمات کلیدی یا معنایی نیاز دارید.

از این ابزار برای سوالاتی مانند موارد زیر استفاده کنید:

  • فردا توی تقویمم چی دارم؟
  • چه برنامه‌ای برای ۱۴ جولای ۲۰۲۵ در تقویم من هست؟
  • جلسات هفته آینده من چیست؟
  • آیا امروز بعد از ظهر درگیری دارم؟

  • جان فردا چه جلساتی دارد؟

مثال:

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 --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
}'

طرحواره ورودی

درخواست رویدادها

نمایش 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 غیر خالی در پاسخ تشخیص داد. به طور پیش‌فرض، مقدار ۲۵۰ رویداد است. اندازه صفحه هرگز نمی‌تواند بزرگتر از ۲۵۰۰ رویداد باشد.

فیلد یونیون _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

اختیاری. جستجوی آزاد برای جستجو در عنوان، توضیحات، مکان و شرکت‌کنندگان.

طرحواره خروجی

پاسخ ListEvents

نمایش 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 استفاده می‌شوند، یعنی حروف کوچک av و ارقام 0-9، به بخش 3.1.2 در RFC2938 مراجعه کنید.
  • طول شناسه باید بین ۵ تا ۱۰۲۴ کاراکتر باشد
  • شناسه باید برای هر تقویم منحصر به فرد باشد

با توجه به ماهیت توزیع‌شده‌ی جهانی سیستم، نمی‌توانیم تضمین کنیم که برخوردهای شناسه در زمان ایجاد رویداد شناسایی شوند. برای به حداقل رساندن خطر برخورد، توصیه می‌کنیم از یک الگوریتم UUID تثبیت‌شده مانند الگوریتم شرح داده شده در RFC4122 استفاده کنید.

اگر شناسه‌ای مشخص نکنید، سرور به طور خودکار آن را ایجاد می‌کند.

توجه داشته باشید که icalUID و id یکسان نیستند و فقط یکی از آنها باید در زمان ایجاد رویداد ارائه شود. یک تفاوت در معنای آنها این است که در رویدادهای تکرارشونده، همه رویدادهای یک رویداد id های متفاوتی دارند در حالی که همه آنها icalUID های یکسانی دارند.

status

string

وضعیت رویداد. اختیاری. مقادیر ممکن عبارتند از:

  • confirmed - رویداد تایید شده است. این وضعیت پیش‌فرض است.
  • tentative - این رویداد به طور آزمایشی تأیید شده است.
  • cancelled - رویداد لغو شده (حذف شده) است. متد list رویدادهای لغو شده را فقط در صورت همگام‌سازی افزایشی (زمانی که syncToken یا updatedMin مشخص شده باشند) یا اگر پرچم showDeleted روی true تنظیم شده باشد، برمی‌گرداند. متد get همیشه آنها را برمی‌گرداند.

وضعیت لغو شده بسته به نوع رویداد، دو حالت مختلف را نشان می‌دهد:

  1. استثنائات لغو شده از یک رویداد تکرارشونده لغو نشده نشان می‌دهد که این نمونه دیگر نباید به کاربر ارائه شود. کلاینت‌ها باید این رویدادها را برای طول عمر رویداد تکرارشونده والد ذخیره کنند. استثنائات لغو شده فقط تضمین می‌کنند که مقادیر فیلدهای id، recurringEventId و originalStartTime پر شوند. سایر فیلدها ممکن است خالی باشند.
  2. تمام رویدادهای لغو شده دیگر، رویدادهای حذف شده را نشان می‌دهند. کلاینت‌ها باید کپی‌های همگام‌سازی شده محلی خود را حذف کنند. چنین رویدادهای لغو شده‌ای در نهایت ناپدید می‌شوند، بنابراین به در دسترس بودن آنها به طور نامحدود تکیه نکنید. رویدادهای حذف شده فقط تضمین می‌کنند که فیلد id را پر کنند.

در تقویم سازمان‌دهنده، رویدادهای لغو شده همچنان جزئیات رویداد (خلاصه، مکان و غیره) را نمایش می‌دهند تا بتوان آنها را بازیابی (حذف نشده) کرد. به طور مشابه، رویدادهایی که کاربر به آنها دعوت شده و به صورت دستی حذف کرده است، همچنان جزئیات را ارائه می‌دهند. با این حال، درخواست‌های همگام‌سازی افزایشی با مقدار نادرست showDeleted، این جزئیات را برنمی‌گردانند.

اگر یک رویداد، برگزارکننده خود را تغییر دهد (برای مثال از طریق عملیات جابجایی) و برگزارکننده اصلی در لیست شرکت‌کنندگان نباشد، یک رویداد لغو شده باقی می‌ماند که در آن فقط فیلد id تضمین می‌شود که پر شود.

htmlLink

string

یک پیوند مطلق به این رویداد در رابط کاربری وب تقویم گوگل. فقط خواندنی.

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 - مقدار پیش‌فرض. این رویداد زمان را در تقویم مسدود می‌کند. این معادل تنظیم «به من نشان بده به عنوان مشغول» در رابط کاربری تقویم است.
  • transparent - این رویداد زمان را در تقویم مسدود نمی‌کند. این معادل تنظیم «به من نشان بده» به عنوان «موجود» در رابط کاربری تقویم است.
visibility

string

قابلیت مشاهده رویداد. اختیاری. مقادیر ممکن عبارتند از:

  • default - از مقدار پیش‌فرض نمایش رویدادها در تقویم استفاده می‌کند. این مقدار پیش‌فرض است.
  • public - رویداد عمومی است و جزئیات رویداد برای همه خوانندگان تقویم قابل مشاهده است.
  • private - این رویداد خصوصی است و فقط شرکت‌کنندگان در رویداد می‌توانند جزئیات رویداد را مشاهده کنند.
  • confidential - رویداد خصوصی است. این مقدار به دلایل سازگاری ارائه شده است.
attendees[]

object ( Attendee )

شرکت‌کنندگان در این مراسم.

eventType

string

نوع خاصی از رویداد. این مورد پس از ایجاد رویداد قابل تغییر نیست. مقادیر ممکن عبارتند از:

  • birthday - یک رویداد ویژه تمام روز با تکرار سالانه.
  • default - یک رویداد منظم یا بیشتر مشخص نشده.
  • focusTime - یک رویداد زمان-تمرکز.
  • fromGmail - رویدادی از Gmail. این نوع رویداد قابل ایجاد نیست.
  • outOfOffice - یک رویداد خارج از دفتر.
  • workingLocation - یک رویداد مربوط به محل کار.
conferenceUrl

string

لینک گوگل میت برای این رویداد.

colorId

string

شناسه رنگ رویداد (رشته 1 - 11 ):

  • ۱: اسطوخودوس
  • ۲: مریم گلی
  • ۳: انگور
  • ۴: فلامینگو
  • ۵: موز
  • ۶: نارنگی
  • ۷: طاووس
  • ۸: گرافیت
  • ۹: بلوبری
  • ۱۰: ریحان
  • ۱۱: گوجه فرنگی.

در تقویم گوگل، رنگ رویدادها به عنوان دسته‌بندی عمل می‌کنند - قابل تنظیم برای هر رویداد یا هر سری. کاربران می‌توانند برچسب‌های سفارشی را به رنگ‌ها در رابط کاربری وب اختصاص دهند (مثلاً 1:1s ، Break )، اما API فقط شناسه‌های عددی را نمایش می‌دهد، نه آن برچسب‌ها را. فقط بر نمای تقویم شما تأثیر می‌گذارد - هر شرکت‌کننده رنگ رویداد خود را کنترل می‌کند.

overrideReminders[]

object ( Reminder )

یادآوری‌هایی برای این رویداد تعریف شده‌اند که جایگزین یادآوری‌های پیش‌فرض تقویم می‌شوند. در صورت عدم تنظیم، از یادآوری‌های پیش‌فرض تقویم استفاده می‌شود.

مدیر مدرسه

نمایش JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
فیلدها
email

string

آدرس ایمیل مدیر (تقویم).

displayName

string

نام مدیر، در صورت وجود.

self

boolean

آیا این اصل با تقویمی که این کپی از رویداد در آن نمایش داده می‌شود، مطابقت دارد یا خیر. فقط خواندنی. مقدار پیش‌فرض False است.

تاریخ یا تاریخ و زمان

نمایش 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

تعداد مهمانان اضافی. اختیاری. مقدار پیش‌فرض ۰ است.

حاشیه‌نویسی ابزار

راهنمایی مخرب: ❌ | راهنمایی بی‌اثر: ✅ | راهنمایی فقط خواندنی: ✅ | راهنمایی جهان باز: ❌