MCP Tools Reference: calendarmcp.googleapis.com

Инструмент: list_events

Возвращает события в заданном календаре, соответствующие всем указанным ограничениям. Временные ограничения указывать не следует, если это не запрошено пользователем. Для поиска по ключевым словам или темам в основном календаре следует использовать инструмент search_events.

В следующем примере показано, как использовать curl для вызова инструмента MCP list_events .

Запрос 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

Необязательно. Свободный поиск без учета регистра, соответствующий заголовку, описанию, местоположению или участникам. Сопоставляет события, содержащие все поисковые термины дословно (поиск с помощью оператора И).

Тип события

Тип события. Неизменяем после создания.

Перечисления
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 — напоминания отправляются через всплывающее окно пользовательского интерфейса.

Union field _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 : Павлин
  • 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 Не блокирует время.

Аннотации инструментов

Подсказка о разрушительном эффекте: ❌ | Подсказка об идемпотентности: ✅ | Подсказка только для чтения: ✅ | Подсказка об открытом мире: ❌