MCP Tools Reference: calendarmcp.googleapis.com

ابزار: list_events

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

نمونه زیر نحوه استفاده از 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
  ],
  "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

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

نوع رویداد

نوع رویداد: پس از ایجاد، تغییرناپذیر.

انوم‌ها
EVENT_TYPE_UNSPECIFIED به عنوان DEFAULT در نظر گرفته می‌شود.
DEFAULT رویداد منظم. مقدار پیش‌فرض.
OUT_OF_OFFICE رویداد خارج از دفتر.
FOCUS_TIME رویداد زمان تمرکز.
WORKING_LOCATION رویداد محل کار.
BIRTHDAY رویداد ویژه تمام روز با تکرار سالانه.
FROM_GMAIL رویداد از Gmail. این نوع رویداد قابل ایجاد نیست.

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

پاسخ 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 - دسترسی مدیر، شامل امکان تغییر تنظیمات اشتراک‌گذاری تقویم.
مهم: نقش 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

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

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 : طاووس
  • 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 .

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

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

الزامی. لینک به پیوست.

فیلد اتحادیه _title .

_title فقط می‌تواند یکی از موارد زیر باشد:

title

string

اختیاری. عنوان پیوست.

مجوزهای مهمان

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

اختیاری. اینکه آیا مهمانان می‌توانند مهمانان دیگر را ببینند یا خیر.

ویژگی‌های موقعیت مکانی کاری

نمایش JSON 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
فیلدها

فیلد یونیون _type .

_type فقط می‌تواند یکی از موارد زیر باشد:

type

enum ( WorkingLocationType )

اختیاری. نوع محل کار.

فیلد یونیون _custom_location_label .

_custom_location_label فقط می‌تواند یکی از موارد زیر باشد:

customLocationLabel

string

اختیاری. برچسب برای یک مکان سفارشی. در صورتی که نوع CUSTOM_LOCATION باشد، الزامی است.

نوع رویداد

نوع رویداد: پس از ایجاد، تغییرناپذیر.

انوم‌ها
EVENT_TYPE_UNSPECIFIED به عنوان DEFAULT در نظر گرفته می‌شود.
DEFAULT رویداد منظم. مقدار پیش‌فرض.
OUT_OF_OFFICE رویداد خارج از دفتر.
FOCUS_TIME رویداد زمان تمرکز.
WORKING_LOCATION رویداد محل کار.
BIRTHDAY رویداد ویژه تمام روز با تکرار سالانه.
FROM_GMAIL رویداد از Gmail. این نوع رویداد قابل ایجاد نیست.

نوع محل کار

نوع محل کار.

انوم‌ها
WORKING_LOCATION_TYPE_UNSPECIFIED نوع محل کار نامشخص. به عنوان HOME_OFFICE در نظر گرفته خواهد شد.
HOME_OFFICE دفتر کار خانگی.
CUSTOM_LOCATION مکان سفارشی.

در دسترس بودن

تنظیم در دسترس بودن برای یک رویداد.

انوم‌ها
AVAILABILITY_UNSPECIFIED پیش‌فرض. به عنوان BUSY در نظر گرفته می‌شود.
AVAILABILITY_BUSY زمان را در تقویم مسدود می‌کند.
AVAILABILITY_FREE زمان را مسدود نمی‌کند.

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

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