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 для вызова инструмента 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
  ],

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

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)
    }
  ],
  "eventType": string,
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ]
}
Поля
id

string

Непрозрачный идентификатор события. При создании новых разовых или повторяющихся событий можно указать их идентификаторы. Указанные идентификаторы должны соответствовать следующим правилам:

  • В идентификаторе допускаются символы, используемые в кодировке base32hex, а именно строчные буквы av и цифры 0-9 (см. раздел 3.1.2 в RFC2938).
  • Длина идентификатора должна составлять от 5 до 1024 символов.
  • Идентификатор должен быть уникальным для каждого календаря.

Ввиду глобальной распределенности системы мы не можем гарантировать обнаружение коллизий идентификаторов во время создания события. Для минимизации риска коллизий мы рекомендуем использовать проверенный алгоритм UUID, например, описанный в RFC4122.

Если вы не укажете идентификатор, он будет сгенерирован сервером автоматически.

Обратите внимание, что icalUID и id не идентичны, и при создании события следует указывать только один из них. Одно из различий в их семантике заключается в том, что в повторяющихся событиях все экземпляры одного события имеют разные id, но при этом все они используют один и тот же icalUID.

status

string

Статус события. Необязательный параметр. Возможные значения:

  • confirmed — Событие подтверждено. Это статус по умолчанию.
  • tentative - Событие предварительно подтверждено.
  • cancelled — событие отменено (удалено). Метод `list` возвращает отмененные события только при инкрементальной синхронизации (если указаны `syncToken` или `updatedMin`) или если флаг `showDeleted` установлен в `true`. Метод `get` всегда возвращает их.

Статус «отменено» обозначает два разных состояния в зависимости от типа события:

  1. Исключения, связанные с отменой неотмененного повторяющегося события, указывают на то, что этот экземпляр больше не должен отображаться пользователю. Клиенты должны хранить эти события в течение всего времени существования родительского повторяющегося события. Гарантируется, что значения полей id, recurringEventId и originalStartTime будут заполнены только для исключений, связанных с отменой. Остальные поля могут быть пустыми.
  2. Все остальные отмененные события представляют собой удаленные события. Клиентам следует удалить свои локально синхронизированные копии. Такие отмененные события со временем исчезнут, поэтому не следует рассчитывать на их постоянную доступность. Для удаленных событий гарантируется заполнение только поля id.

В календаре организатора отмененные события продолжают отображать подробную информацию о них (краткое описание, место проведения и т. д.), что позволяет их восстановить (восстановить в удаленном виде). ​​Аналогично, события, на которые пользователь был приглашен и которые он удалил вручную, также продолжают предоставлять подробную информацию. Однако запросы на инкрементальную синхронизацию с параметром showDeleted, установленным в значение false, не будут возвращать эти данные.

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

htmlLink

string

Абсолютная ссылка на это событие в веб-интерфейсе Google Календаря. Только для чтения.

created

string

Время создания события (в формате метки времени ISO 8601). Только для чтения.

updated

string

Время последнего изменения основных данных события (в формате метки времени ISO 8601). Обновление напоминаний о событиях не приведет к изменению этого параметра. Только для чтения.

summary

string

Название мероприятия.

description

string

Описание мероприятия. Может содержать HTML-код. Необязательно.

location

string

Географическое местоположение мероприятия в виде произвольного текста. Необязательно.

creator

object ( Principal )

Создатель мероприятия. Только для чтения.

organizer

object ( Principal )

Организатор мероприятия. Если организатор также является участником, это указывается отдельной записью в списке участников, где для поля «Организатор» установлено значение «True». Только для чтения.

start

object ( DateOrDateTime )

Время начала события (включительно). Для повторяющегося события это время начала первого события.

end

object ( DateOrDateTime )

Время окончания события (исключая указанное время). Для повторяющегося события это время окончания первого его экземпляра.

recurrence[]

string

Список строк RRULE, EXRULE, RDATE и EXDATE для повторяющегося события, как указано в RFC5545. Обратите внимание, что строки DTSTART и DTEND не допускаются в этом поле; время начала и окончания события указывается в полях start и end. Это поле опускается для единичных событий или случаев повторяющихся событий.

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

Ссылка на мероприятие в Google Meet.

colorId

string

Идентификатор цвета события ( 11 1 ):

  • 1: Лаванда
  • 2: Мудрец
  • 3: Виноград
  • 4: Фламинго
  • 5: Банан
  • 6: Мандарин
  • 7: Павлин
  • 8: Графит
  • 9: Черника
  • 10: Базилик
  • 11: Помидор.

В Google Календаре цвета событий функционируют как категории — их можно устанавливать для каждого события или серии событий. Пользователи могут назначать пользовательские метки цветам в веб-интерфейсе (например, 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

Количество дополнительных гостей. Необязательно. По умолчанию — 0.

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

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