MCP Tools Reference: calendarmcp.googleapis.com

Herramienta: list_events

Devuelve los eventos del calendario determinado que coinciden con todas las restricciones especificadas. No se deben especificar restricciones de tiempo, a menos que el usuario lo solicite. En el caso de las búsquedas de palabras clave o temas abiertos en el calendario principal, se debe usar la herramienta search_events.

En el siguiente ejemplo, se muestra cómo usar curl para invocar la herramienta de MCP list_events.

Solicitud de 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

Representación 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. Obsoleto: Usa event_type en su lugar.
eventType[]

enum (EventType)

Opcional. Son los tipos de eventos que se devolverán. Si está vacío, solo se devuelven los siguientes tipos de eventos: DEFAULT, OUT_OF_OFFICE, FOCUS_TIME, FROM_GMAIL

Campo de unión _calendar_id.

_calendar_id puede ser una de las siguientes opciones:
calendarId

string

Opcional. ID del calendario que contiene los eventos. Dirección de correo electrónico: Se puede resolver con list_calendars. El valor predeterminado es el calendario principal.

Campo de unión _page_size.

_page_size puede ser una de las siguientes opciones:
pageSize

integer

Opcional. Cantidad máxima de eventos por página (el valor predeterminado es 100 y el máximo es 250). Se recomienda 10.

Campo de unión _page_token.

_page_token puede ser una de las siguientes opciones:
pageToken

string

Opcional. Token de página siguiente Usa el valor de nextPageToken de la página anterior.

Campo de unión _start_time.

_start_time puede ser una de las siguientes opciones:
startTime

string

Opcional. Es el límite inferior de un período. Solo se debe configurar cuando el usuario solicita un período específico. Debe ser una marca de tiempo en formato ISO 8601 inferior a end_time.

Campo de unión _end_time.

_end_time puede ser una de las siguientes opciones:
endTime

string

Opcional. Es el límite superior de un período. Solo se debe establecer cuando el usuario solicita un período específico o un momento en el pasado. Debe ser una marca de tiempo en formato ISO 8601 posterior a start_time.

Campo de unión _time_zone.

_time_zone puede ser una de las siguientes opciones:
timeZone

string

Opcional. Zona horaria (ID de IANA, por ejemplo, Europe/Zurich) que se usa para resolver fechas sin zona horaria. El valor predeterminado es la zona horaria del calendario.

Campo de unión _order_by.

_order_by puede ser una de las siguientes opciones:
orderBy

string

Opcional. Es el orden en el que se deben devolver los eventos. Los valores posibles son:

  • default: Sin especificar, pero con orden determinístico (predeterminado).
  • startTime: Ordenar por hora de inicio de forma ascendente.
  • startTimeDesc: Ordena por hora de inicio de forma descendente.
  • lastModified: Ordenar por hora de última modificación en orden ascendente

Campo de unión _full_text.

_full_text puede ser una de las siguientes opciones:
fullText

string

Opcional. Búsqueda de formato libre que no distingue mayúsculas de minúsculas y que coincide con el título, la descripción, la ubicación o los asistentes. Coincide con los eventos que contienen todos los términos de la búsqueda de forma literal (búsqueda AND).

EventType

Es el tipo de evento. Es inmutable después de la creación.

Enums
EVENT_TYPE_UNSPECIFIED Se trata como DEFAULT.
DEFAULT Evento normal. Valor predeterminado
OUT_OF_OFFICE Evento fuera de la oficina.
FOCUS_TIME Es un evento de tiempo dedicado.
WORKING_LOCATION Es un evento de ubicación de trabajo.
BIRTHDAY Evento especial de todo el día con recurrencia anual.
FROM_GMAIL Evento de Gmail. No se puede crear este tipo de evento.

Esquema de salida

ListEventsResponse

Representación JSON 
{
  "summary": string,
  "description": string,
  "updated": string,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      object (Reminder)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],

  "nextPageToken": string
}
Campos
summary

string

Es el título del calendario.
description

string

Es la descripción del calendario.
updated

string

Es la fecha y hora de la última actualización (ISO 8601) del calendario.
timeZone

string

Zona horaria del calendario.
accessRole

string

Solo salida. Rol de acceso del usuario al calendario. Los valores posibles son:

  • none: Sin acceso.
  • freeBusyReader: Acceso de lectura a la información de disponibilidad.
  • reader: Acceso de lectura al calendario. Aparecerán los eventos privados, pero se ocultarán los detalles.
  • writer: Acceso de lectura y escritura. Aparecerán los eventos privados y se mostrarán los detalles de los eventos.
  • owner: Acceso de administrador, incluida la capacidad de modificar la configuración de uso compartido del calendario.
Importante: El rol de owner es diferente del propietario de los datos del calendario. Un calendario tiene un solo propietario de los datos, pero puede tener varios usuarios con el rol de owner.
defaultReminders[]

object (Reminder)

Son los recordatorios predeterminados para los eventos del calendario.
events[]

object (Event)

Es la lista de eventos.

Campo de unión _next_page_token.

_next_page_token puede ser una de las siguientes opciones:
nextPageToken

string

Token de página siguiente Se omite si no existe una página siguiente.

Recordatorio

Representación JSON 
{

  "method": string

  "minutes": integer
}
Campos

Campo de unión _method.

_method puede ser una de las siguientes opciones:
method

string

Obligatorio. Es el método de publicación. Los valores posibles son:

  • email: Los recordatorios se envían por correo electrónico.
  • popup: Los recordatorios se envían a través de una ventana emergente de la IU.

Campo de unión _minutes.

_minutes puede ser una de las siguientes opciones:
minutes

integer

Obligatorio. Minutos de antelación con los que se activa el recordatorio.

Evento

Representación 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

Es un identificador único.
status

string

Opcional. Estado. Los valores posibles son:

  • confirmed: El evento está confirmado (valor predeterminado).
  • tentative: El evento se confirmó de forma tentativa.
  • cancelled: Se canceló o borró el evento.
htmlLink

string

Solo salida. Es un vínculo absoluto a este evento en la IU web del Calendario de Google.
created

string

Solo salida. Hora de creación (ISO 8601).
updated

string

Solo salida. Hora de la última modificación (ISO 8601).
summary

string

Título.
description

string

Opcional. Descripción. Puede contener HTML.
location

string

Opcional. Ubicación.
creator

object (Principal)

Solo salida. Creador.
organizer

object (Principal)

Solo salida. Organizador. También se muestra en la lista de asistentes si asistes.
start

object (DateOrDateTime)

Hora de inicio (inclusive). En el caso de los eventos recurrentes, se usa la primera instancia.
end

object (DateOrDateTime)

Hora de finalización (no incluida). En el caso de los eventos recurrentes, se usa la primera instancia.
recurrence[]

string

Reglas de recurrencia como cadenas RRULE, EXRULE, RDATE o EXDATE (según RFC 5545) Se omite para eventos únicos. Las horas de inicio y finalización deben establecerse en los campos start y end.
recurringEventId

string

Es el ID del evento recurrente principal para las instancias de eventos recurrentes.
originalStartTime

object (DateOrDateTime)

Es la hora de inicio original de las instancias recurrentes. Es la fecha y hora en la que comenzaría esta instancia según los datos de recurrencia.
transparency
(deprecated)

string

Opcional. Obsoleto: Usa availability en su lugar.
visibility

string

Opcional. Visibilidad del evento. Los valores posibles son:

  • default: Usa la visibilidad predeterminada para los eventos del calendario. Este es el valor predeterminado.
  • public: Los detalles del evento son visibles para todos los lectores del calendario.
  • private: Solo los asistentes al evento pueden ver los detalles del evento.

attendees[]

object (Attendee)

Asistentes
conferenceUrl

string

Vínculo de la videoconferencia.
colorId

string

Color del evento. Solo afecta tu vista del calendario. Es un ID que hace referencia a una entrada en la paleta de colores del calendario (cadena '1'-'11'):

  • 1: Lavanda
  • 2: Sage
  • 3: Uva
  • 4: Flamenco
  • 5: Plátano
  • 6: Mandarina
  • 7: Peacock
  • 8: Grafito
  • 9: Mora azul
  • 10: Albahaca
  • 11: Tomato.

overrideReminders[]

object (Reminder)

Recordatorios. Si no se establece, se recurre a los valores predeterminados del calendario.
attachments[]

object (Attachment)

Archivos adjuntos
guestPermissions

object (GuestPermissions)

Permisos de invitados
eventType

enum (EventType)

Es el tipo de evento.
workingLocationProperties

object (WorkingLocationProperties)

Son las propiedades de la ubicación de trabajo. Se propaga solo cuando event_type es WORKING_LOCATION.
availability

enum (Availability)

Opcional. Es el parámetro de configuración de disponibilidad.

Principal

Representación JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Campos
email

string

el correo electrónico,
displayName

string

Nombre
self

boolean

Solo salida. Indica si este principal corresponde al calendario en el que aparece esta copia del evento. Valor predeterminado: false.

DateOrDateTime

Representación JSON 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Campos
date

string

Fecha ISO 8601 a la medianoche (UTC; por ejemplo, '2019-11-20T00:00:00Z').
dateTime

string

Marca de tiempo ISO 8601 (por ejemplo, '2019-11-20T08:19:06-07:00').
timeZone

string

Nombre de la zona horaria de TZDB.

Asistente

Representación 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ón _id.

_id puede ser una de las siguientes opciones:
id

string

Solo salida. Es el ID del perfil.

Campo de unión _email.

_email puede ser una de las siguientes opciones:
email

string

Obligatorio. Es la dirección de correo electrónico del asistente.

Campo de unión _display_name.

_display_name puede ser una de las siguientes opciones:
displayName

string

Opcional. Nombre

Campo de unión _organizer.

_organizer puede ser una de las siguientes opciones:
organizer

boolean

Solo salida. Indica si el asistente es el organizador. Valor predeterminado: false.

Campo de unión _self.

_self puede ser una de las siguientes opciones:
self

boolean

Solo salida. Indica si esta entrada representa el calendario en el que aparece esta copia del evento. Valor predeterminado: false.

Campo de unión _resource.

_resource puede ser una de las siguientes opciones:
resource

boolean

Opcional. Indica si el asistente es un recurso (por ejemplo, una sala). Es inmutable y solo se puede configurar cuando se agrega inicialmente el asistente. Valor predeterminado: false.

Campo de unión _optional_attendee.

_optional_attendee puede ser una de las siguientes opciones:
optionalAttendee

boolean

Opcional. Indica si el asistente es opcional. Valor predeterminado: false.

Campo de unión _response_status.

_response_status puede ser una de las siguientes opciones:
responseStatus

string

Opcional. Es el estado de la respuesta. Los valores posibles son:

  • needsAction: El asistente no respondió a la invitación (se recomienda para eventos nuevos).
  • declined: El asistente rechazó la invitación.
  • tentative: El asistente aceptó la invitación de forma provisoria.
  • accepted: El asistente aceptó la invitación.

Campo de unión _comment.

_comment puede ser una de las siguientes opciones:
comment

string

Solo salida. Comentario de la respuesta.

Campo de unión _additional_guests.

_additional_guests puede ser una de las siguientes opciones:
additionalGuests

integer

Opcional. Cantidad de huéspedes adicionales. Valor predeterminado: 0.

Archivo adjunto

Representación JSON 
{

  "fileUrl": string

  "title": string
}
Campos

Campo de unión _file_url.

_file_url puede ser una de las siguientes opciones:
fileUrl

string

Obligatorio. Es el vínculo URL al archivo adjunto.

Campo de unión _title.

_title puede ser una de las siguientes opciones:
title

string

Opcional. Título del archivo adjunto.

GuestPermissions

Representación JSON 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
Campos

Campo de unión _guests_can_invite_others.

_guests_can_invite_others puede ser una de las siguientes opciones:
guestsCanInviteOthers

boolean

Opcional. Indica si los invitados pueden invitar a otras personas.

Campo de unión _guests_can_modify.

_guests_can_modify puede ser una de las siguientes opciones:
guestsCanModify

boolean

Opcional. Indica si los invitados pueden modificar el evento.

Campo de unión _guests_can_see_guests.

_guests_can_see_guests puede ser una de las siguientes opciones:
guestsCanSeeGuests

boolean

Opcional. Indica si los invitados pueden ver a otros invitados.

WorkingLocationProperties

Representación JSON 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
Campos

Campo de unión _type.

_type puede ser una de las siguientes opciones:
type

enum (WorkingLocationType)

Opcional. Es el tipo de ubicación de trabajo.

Campo de unión _custom_location_label.

_custom_location_label puede ser una de las siguientes opciones:
customLocationLabel

string

Opcional. Es la etiqueta de una ubicación personalizada. Es obligatorio si el tipo es CUSTOM_LOCATION.

EventType

Es el tipo de evento. Es inmutable después de la creación.

Enums
EVENT_TYPE_UNSPECIFIED Se trata como DEFAULT.
DEFAULT Evento normal. Valor predeterminado
OUT_OF_OFFICE Evento fuera de la oficina.
FOCUS_TIME Es un evento de tiempo dedicado.
WORKING_LOCATION Es un evento de ubicación de trabajo.
BIRTHDAY Evento especial de todo el día con recurrencia anual.
FROM_GMAIL Evento de Gmail. No se puede crear este tipo de evento.

WorkingLocationType

Es el tipo de ubicación de trabajo.

Enums
WORKING_LOCATION_TYPE_UNSPECIFIED No se especificó el tipo de ubicación de trabajo. Se tratará como HOME_OFFICE.
HOME_OFFICE Oficina en casa
CUSTOM_LOCATION Ubicación personalizada

Disponibilidad

Es el parámetro de configuración de disponibilidad de un evento.

Enums
AVAILABILITY_UNSPECIFIED Predeterminado. Se trata como BUSY.
AVAILABILITY_BUSY Bloquea tiempo en el calendario.
AVAILABILITY_FREE No bloquea el tiempo.

Anotaciones de herramientas

Sugerencia destructiva: ❌ | Sugerencia idempotente: ✅ | Sugerencia de solo lectura: ✅ | Sugerencia de mundo abierto: ❌

Alcances de la autorización

Se necesita uno de los siguientes alcances de 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