MCP Tools Reference: calendarmcp.googleapis.com

Ferramenta: list_events

Retorna eventos na agenda especificada que correspondem a todas as restrições especificadas. As restrições de tempo não devem ser especificadas, a menos que o usuário solicite. Para pesquisas abertas por palavra-chave ou com base em temas no calendário principal, use a ferramenta search_events.

O exemplo a seguir demonstra como usar curl para invocar a ferramenta list_events MCP.

Solicitação curl 
curl --location 'https://calendarmcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--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
}'

Esquema de entrada

ListEventsRequest

Representação JSON 
{
  "eventTypeFilter": [
    string
  ],
  "eventType": [
    enum (EventType)
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Campos
eventTypeFilter[]
(deprecated)

string

Opcional. Descontinuado: use event_type.
eventType[]

enum (EventType)

Opcional. Os tipos de evento a serem retornados. Se estiver vazio, somente os seguintes tipos de eventos serão retornados: DEFAULT, OUT_OF_OFFICE, FOCUS_TIME, FROM_GMAIL

Campo de união _calendar_id.

_calendar_id pode ser apenas de um dos tipos a seguir:
calendarId

string

Opcional. ID da agenda que contém os eventos. Endereço de e-mail: pode ser resolvido usando list_calendars. Padrão: agenda principal.

Campo de união _page_size.

_page_size pode ser apenas de um dos tipos a seguir:
pageSize

integer

Opcional. Máximo de eventos por página (padrão 100, máximo 250). Recomendado: 10.

Campo de união _page_token.

_page_token pode ser apenas de um dos tipos a seguir:
pageToken

string

Opcional. Token da próxima página. Use o valor de nextPageToken da página anterior.

Campo de união _start_time.

_start_time pode ser apenas de um dos tipos a seguir:
startTime

string

Opcional. O limite inferior de um período. Só pode ser definido quando um período específico é solicitado pelo usuário. Precisa ser uma data e hora ISO 8601 menor que end_time.

Campo de união _end_time.

_end_time pode ser apenas de um dos tipos a seguir:
endTime

string

Opcional. O limite superior de um período. Só pode ser definido quando o usuário solicita um período específico ou um momento no passado. Precisa ser um carimbo de data/hora ISO 8601 maior que start_time.

Campo de união _time_zone.

_time_zone pode ser apenas de um dos tipos a seguir:
timeZone

string

Opcional. Fuso horário (ID da IANA, por exemplo, Europe/Zurich) usado para resolver datas sem fuso horário. Padrão: fuso horário da agenda.

Campo de união _order_by.

_order_by pode ser apenas de um dos tipos a seguir:
orderBy

string

Opcional. A ordem em que os eventos devem ser retornados. Os valores possíveis são:

  • default: não especificado, mas com ordenação determinística (padrão).
  • startTime: ordena por horário de início em ordem crescente.
  • startTimeDesc: ordena por horário de início em ordem decrescente.
  • lastModified: ordena pelo horário da última modificação em ordem crescente.

Campo de união _full_text.

_full_text pode ser apenas de um dos tipos a seguir:
fullText

string

Opcional. Pesquisa livre e sem diferenciação de maiúsculas e minúsculas que corresponde ao título, à descrição, ao local ou aos participantes. Corresponde a eventos que contêm todos os termos da consulta exatamente como foram digitados (pesquisa AND).

EventType

Tipo de evento. Imutável após a criação.

Tipos enumerados
EVENT_TYPE_UNSPECIFIED Tratado como DEFAULT.
DEFAULT Evento regular. Valor padrão.
OUT_OF_OFFICE Evento fora do escritório.
FOCUS_TIME Evento "Horário de concentração".
WORKING_LOCATION Evento de local de trabalho.
BIRTHDAY Evento especial de dia inteiro com recorrência anual.
FROM_GMAIL Evento do Gmail. Não é possível criar esse tipo de evento.

Esquema de saída

ListEventsResponse

Representação JSON 
{
  "summary": string,
  "description": string,
  "updated": string,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      object (Reminder)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],

  "nextPageToken": string
}
Campos
summary

string

Título da agenda.
description

string

Descrição da agenda.
updated

string

Horário da última atualização (ISO 8601) da agenda.
timeZone

string

Fuso horário da agenda.
accessRole

string

Apenas saída. Função de acesso do usuário para a agenda. Os valores possíveis são:

  • none: sem acesso.
  • freeBusyReader: acesso de leitura às informações de disponibilidade/ocupação.
  • reader: acesso de leitura à agenda. Os eventos particulares vão aparecer, mas os detalhes deles vão ficar ocultos.
  • writer: acesso de leitura e gravação. Os eventos particulares vão aparecer, e os detalhes deles vão ficar visíveis.
  • owner: acesso de administrador, incluindo a capacidade de modificar as configurações de compartilhamento da agenda.
Importante: a função owner é diferente do proprietário dos dados da agenda. Uma agenda tem um único proprietário de dados, mas pode ter vários usuários com a função owner.
defaultReminders[]

object (Reminder)

Lembretes padrão para eventos na agenda.
events[]

object (Event)

Lista de eventos.

Campo de união _next_page_token.

_next_page_token pode ser apenas de um dos tipos a seguir:
nextPageToken

string

Token da próxima página. Omitido se não houver uma próxima página.

Lembrete

Representação JSON 
{

  "method": string

  "minutes": integer
}
Campos

Campo de união _method.

_method pode ser apenas de um dos tipos a seguir:
method

string

Obrigatório. Método de exibição. Os valores possíveis são:

  • email: os lembretes são enviados por e-mail.
  • popup: os lembretes são enviados por um pop-up da interface.

Campo de união _minutes.

_minutes pode ser apenas de um dos tipos a seguir:
minutes

integer

Obrigatório. Minutos antes do acionamento do lembrete.

Evento

Representação 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)
}
Campos
id

string

Identificador exclusivo.
status

string

Opcional. Status. Os valores possíveis são:

  • confirmed: o evento está confirmado (padrão).
  • tentative: o evento está provisoriamente confirmado.
  • cancelled: o evento foi cancelado ou excluído.
htmlLink

string

Apenas saída. Um link absoluto para esse evento na interface da Web do Google Agenda.
created

string

Apenas saída. Horário da criação (ISO 8601).
updated

string

Apenas saída. Horário da última modificação (ISO 8601).
summary

string

Título.
description

string

Opcional. Descrição. Pode conter HTML.
location

string

Opcional. Local.
creator

object (Principal)

Apenas saída. Criador de conteúdo.
organizer

object (Principal)

Apenas saída. Organizador. Também listado em "Participantes" se estiver participando.
start

object (DateOrDateTime)

Horário de início (incluído). Para eventos recorrentes, a primeira instância é usada.
end

object (DateOrDateTime)

Horário de término (exclusivo). Para eventos recorrentes, a primeira instância é usada.
recurrence[]

string

Regras de recorrência como strings RRULE, EXRULE, RDATE ou EXDATE (de acordo com a RFC 5545). Omitido para eventos únicos. Os horários de início/término precisam ser definidos nos campos start/end.
recurringEventId

string

ID do evento recorrente principal para instâncias de eventos recorrentes.
originalStartTime

object (DateOrDateTime)

Horário de início original das instâncias recorrentes. É o horário em que essa instância começaria de acordo com os dados de recorrência.
transparency
(deprecated)

string

Opcional. Descontinuado: use availability.
visibility

string

Opcional. Visibilidade do evento. Os valores possíveis são:

  • default: usa a visibilidade padrão para eventos na agenda. Esse é o valor padrão.
  • public: os detalhes do evento ficam visíveis para todos os leitores da agenda.
  • private: somente os participantes do evento podem ver os detalhes dele.

attendees[]

object (Attendee)

Participantes.
conferenceUrl

string

Link da videoconferência.
colorId

string

A cor do evento. Afeta apenas a visualização da sua agenda. É um ID que se refere a uma entrada na paleta de cores da agenda (string '1'-'11'):

  • 1: lavanda
  • 2: Sage
  • 3: uva
  • 4: Flamingo
  • 5: Banana
  • 6: Tangerina
  • 7: Peacock
  • 8: Graphite
  • 9: Blueberry
  • 10: manjericão
  • 11: tomate.

overrideReminders[]

object (Reminder)

Lembretes. Se não for definido, volta para os padrões da agenda.
attachments[]

object (Attachment)

Anexos de arquivos.
guestPermissions

object (GuestPermissions)

Permissões de convidados.
eventType

enum (EventType)

Tipo de evento.
workingLocationProperties

object (WorkingLocationProperties)

Propriedades do local de trabalho. Preenchido apenas quando event_type é WORKING_LOCATION.
availability

enum (Availability)

Opcional. Configuração de disponibilidade.

Principal

Representação JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Campos
email

string

E-mail.
displayName

string

Nome
self

boolean

Apenas saída. Se esse principal corresponde à agenda em que essa cópia do evento aparece. Padrão: false.

DateOrDateTime

Representação JSON 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Campos
date

string

Data ISO 8601 à meia-noite UTC (por exemplo, '2019-11-20T00:00:00Z').
dateTime

string

Timestamp ISO 8601 (por exemplo, '2019-11-20T08:19:06-07:00').
timeZone

string

Nome do fuso horário TZDB.

Participante

Representação JSON 
{

  "id": string

  "email": string

  "displayName": string

  "organizer": boolean

  "self": boolean

  "resource": boolean

  "optionalAttendee": boolean

  "responseStatus": string

  "comment": string

  "additionalGuests": integer
}
Campos

Campo de união _id.

_id pode ser apenas de um dos tipos a seguir:
id

string

Apenas saída. ID do perfil.

Campo de união _email.

_email pode ser apenas de um dos tipos a seguir:
email

string

Obrigatório. Endereço de e-mail do participante.

Campo de união _display_name.

_display_name pode ser apenas de um dos tipos a seguir:
displayName

string

Opcional. Nome

Campo de união _organizer.

_organizer pode ser apenas de um dos tipos a seguir:
organizer

boolean

Apenas saída. Se o participante é o organizador. Padrão: false.

Campo de união _self.

_self pode ser apenas de um dos tipos a seguir:
self

boolean

Apenas saída. Se esta entrada representa a agenda em que esta cópia do evento aparece. Padrão: false.

Campo de união _resource.

_resource pode ser apenas de um dos tipos a seguir:
resource

boolean

Opcional. Indica se o participante é um recurso (por exemplo, uma sala). Imutável, só pode ser definido quando o participante é adicionado inicialmente. Padrão: false.

Campo de união _optional_attendee.

_optional_attendee pode ser apenas de um dos tipos a seguir:
optionalAttendee

boolean

Opcional. Se o participante é opcional. Padrão: false.

Campo de união _response_status.

_response_status pode ser apenas de um dos tipos a seguir:
responseStatus

string

Opcional. Status da resposta. Os valores possíveis são:

  • needsAction - O participante não respondeu ao convite (recomendado para novos eventos).
  • declined: o convidado recusou o convite.
  • tentative: o participante aceitou o convite provisoriamente.
  • accepted: o participante aceitou o convite.

Campo de união _comment.

_comment pode ser apenas de um dos tipos a seguir:
comment

string

Apenas saída. Comentário da resposta.

Campo de união _additional_guests.

_additional_guests pode ser apenas de um dos tipos a seguir:
additionalGuests

integer

Opcional. Número de hóspedes extras. Padrão: 0.

Anexo

Representação JSON 
{

  "fileUrl": string

  "title": string
}
Campos

Campo de união _file_url.

_file_url pode ser apenas de um dos tipos a seguir:
fileUrl

string

Obrigatório. Link do URL para o anexo.

Campo de união _title.

_title pode ser apenas de um dos tipos a seguir:
title

string

Opcional. Título do anexo.

GuestPermissions

Representação JSON 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
Campos

Campo de união _guests_can_invite_others.

_guests_can_invite_others pode ser apenas de um dos tipos a seguir:
guestsCanInviteOthers

boolean

Opcional. Se os convidados podem convidar outras pessoas.

Campo de união _guests_can_modify.

_guests_can_modify pode ser apenas de um dos tipos a seguir:
guestsCanModify

boolean

Opcional. Se os convidados podem modificar o evento.

Campo de união _guests_can_see_guests.

_guests_can_see_guests pode ser apenas de um dos tipos a seguir:
guestsCanSeeGuests

boolean

Opcional. Se os convidados podem ver outras pessoas.

WorkingLocationProperties

Representação JSON 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
Campos

Campo de união _type.

_type pode ser apenas de um dos tipos a seguir:
type

enum (WorkingLocationType)

Opcional. Tipo de local de trabalho.

Campo de união _custom_location_label.

_custom_location_label pode ser apenas de um dos tipos a seguir:
customLocationLabel

string

Opcional. O rótulo de um local personalizado. Obrigatório se o tipo for CUSTOM_LOCATION.

EventType

Tipo de evento. Imutável após a criação.

Tipos enumerados
EVENT_TYPE_UNSPECIFIED Tratado como DEFAULT.
DEFAULT Evento regular. Valor padrão.
OUT_OF_OFFICE Evento fora do escritório.
FOCUS_TIME Evento "Horário de concentração".
WORKING_LOCATION Evento de local de trabalho.
BIRTHDAY Evento especial de dia inteiro com recorrência anual.
FROM_GMAIL Evento do Gmail. Não é possível criar esse tipo de evento.

WorkingLocationType

Tipo de local de trabalho.

Tipos enumerados
WORKING_LOCATION_TYPE_UNSPECIFIED Tipo de local de trabalho não especificado. Será tratado como HOME_OFFICE.
HOME_OFFICE Home office.
CUSTOM_LOCATION Localização personalizada.

Disponibilidade

Configuração de disponibilidade para um evento.

Tipos enumerados
AVAILABILITY_UNSPECIFIED Padrão. Tratado como BUSY.
AVAILABILITY_BUSY Bloqueia horários na agenda.
AVAILABILITY_FREE Não bloqueia o tempo.

Anotações de ferramentas

Dica destrutiva: ❌ | Dica idempotente: ✅ | Dica somente leitura: ✅ | Dica de mundo aberto: ❌

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/calendar
  • https://www.googleapis.com/auth/calendar.events
  • https://www.googleapis.com/auth/calendar.events.readonly
  • https://www.googleapis.com/auth/calendar.readonly