MCP Tools Reference: calendarmcp.googleapis.com

Herramienta: list_events

Enumera los eventos de calendario en un calendario determinado que satisfacen las condiciones especificadas.

Funciones clave:

  • Cualquier ID de calendario, que puede ser el calendario principal del usuario o cualquier otro.
  • Filtrado por intervalo de tiempo
  • Recupera TODOS los eventos que coinciden con las restricciones de tiempo.

Si está disponible, usa la herramienta search_events en lugar de las búsquedas en el calendario principal del usuario en los siguientes casos:

  • Estás buscando eventos que coincidan con un tema, una categoría o una intención específicos (p.ej., "reuniones de almuerzo", "sincronizaciones de proyectos").
  • Debes encontrar los eventos más relevantes (los K principales) en lugar de todos los eventos que satisfacen las restricciones.
  • Necesitas capacidades de búsqueda semántica o por palabra clave.

Usa esta herramienta para consultas como las siguientes:

  • ¿Qué tengo en mi calendario mañana?
  • ¿Qué eventos tengo en mi calendario el 14 de julio de 2025?
  • ¿Cuáles son mis reuniones de la próxima semana?
  • ¿Tengo algún conflicto esta tarde?

  • ¿Qué reuniones tiene John mañana?

Ejemplo:

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.

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' \
--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
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Campos
eventTypeFilter[]

string

Opcional. Son los tipos de eventos que se devolverán. Los valores posibles son:

  • default: Eventos regulares (predeterminado).
  • outOfOffice: Eventos fuera de la oficina.
  • focusTime: Eventos de tiempo dedicado
  • workingLocation: Eventos de ubicación de trabajo.
  • birthday: Eventos de cumpleaños
  • fromGmail: Eventos de Gmail.

Si está vacío, solo se devuelven los siguientes tipos de eventos: default, outOfOffice, focusTime, fromGmail

Campo de unión _calendar_id.

_calendar_id puede ser una de las siguientes opciones:
calendarId

string

Opcional. ID del calendario del que se enumerarán los eventos. El valor predeterminado es el calendario principal del usuario.

Campo de unión _page_size.

_page_size puede ser una de las siguientes opciones:
pageSize

integer

Opcional. Es la cantidad máxima de eventos que se muestran en una página de resultados. La cantidad de eventos en la página resultante puede ser menor que este valor, o no haber ninguno, incluso si hay más eventos que coinciden con la búsqueda. Las páginas incompletas se pueden detectar con un campo next_page_token no vacío en la respuesta. De forma predeterminada, el valor es de 250 eventos. El tamaño de la página nunca puede ser superior a 2,500 eventos.

Campo de unión _page_token.

_page_token puede ser una de las siguientes opciones:
pageToken

string

Opcional. Es un token que especifica qué página de resultados se debe devolver.

Campo de unión _start_time.

_start_time puede ser una de las siguientes opciones:
startTime

string

Opcional. Límite inferior (exclusivo) para la hora de finalización de un evento. Solo se muestran los eventos que finalizan estrictamente después de esta hora (es decir, el inicio del período para buscar). Si no se proporcionan start_time ni end_time, el valor predeterminado es la hora actual. Si se especifica, debe ser menor o igual que end_time. Debe ser una marca de tiempo ISO 8601. Por ejemplo, 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z o 2026-06-03T10:00:00. Se pueden proporcionar milisegundos, pero se ignorarán.

Campo de unión _end_time.

_end_time puede ser una de las siguientes opciones:
endTime

string

Opcional. Es el límite superior (exclusivo) para la hora de inicio de un evento. Solo se muestran los eventos que comienzan estrictamente antes de esta hora (es decir, el final del período para buscar). Si se especifica, debe ser mayor o igual que start_time. Debe ser una marca de tiempo ISO 8601. Por ejemplo, 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z o 2026-06-03T10:00:00. Se pueden proporcionar milisegundos, pero se ignorarán.

Campo de unión _time_zone.

_time_zone puede ser una de las siguientes opciones:
timeZone

string

Opcional. Zona horaria que se usa en la respuesta y para resolver las fechas sin zona horaria en la solicitud (con el formato de un nombre de la base de datos de zonas horarias de IANA, p.ej., Europe/Zurich). La predeterminada 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: Ordena por hora de inicio de forma ascendente.
  • startTimeDesc: Ordena por hora de inicio de forma descendente.
  • lastModified: Ordena por hora de la última modificación en orden ascendente.

Campo de unión _full_text.

_full_text puede ser una de las siguientes opciones:
fullText

string

Opcional. Es una búsqueda de formato libre para buscar en el título, la descripción, la ubicación y los asistentes.

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

Fecha y hora de la última modificación del calendario (como una marca de tiempo ISO 8601).
timeZone

string

Zona horaria del calendario.
accessRole

string

Es el rol de acceso del usuario para este calendario. Solo lectura. Los valores posibles son:

  • none: El usuario no tiene acceso.
  • freeBusyReader: El usuario tiene acceso de lectura a la información de disponibilidad.
  • reader: El usuario tiene acceso de lectura al calendario. Los eventos privados aparecerán a los usuarios con acceso de lector, pero se ocultarán los detalles del evento.
  • writer: El usuario tiene acceso de lectura y escritura al calendario. Los eventos privados aparecerán para los usuarios con acceso de escritura, y los detalles del evento serán visibles.
  • owner: El usuario tiene acceso de administrador al calendario. Este rol tiene todos los permisos del rol de escritor, además de la capacidad de ver y modificar los niveles de acceso de otros usuarios. Importante: El rol de propietario 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 propietario.
defaultReminders[]

object (Reminder)

Son los recordatorios predeterminados del calendario para el usuario autenticado. Estos recordatorios se aplican a todos los eventos de este calendario que no los anulan de forma explícita (es decir, no completan override_reminders).
events[]

object (Event)

Es la lista de eventos del calendario.

Campo de unión _next_page_token.

_next_page_token puede ser una de las siguientes opciones:
nextPageToken

string

Es el token que se usa para acceder a la siguiente página de este resultado. Se omite si no hay más resultados disponibles.

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 la forma en que se entrega el recordatorio al usuario. 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. Cantidad de minutos de anticipación con la que se debe enviar 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)
    }
  ],
  "eventType": string,
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ]
}
Campos
id

string

Es el identificador opaco del evento. Cuando creas eventos únicos o recurrentes nuevos, puedes especificar sus IDs. Los IDs proporcionados deben seguir estas reglas:

  • Los caracteres permitidos en el ID son los que se usan en la codificación base32hex, es decir, las letras en minúscula de la a a la v y los dígitos del 0 al 9.Consulta la sección 3. 1.2 en RFC2938.
  • La longitud del ID debe estar entre 5 y 1,024 caracteres.
  • El ID debe ser único por calendario.

Debido a la naturaleza distribuida a nivel global del sistema, no podemos garantizar que se detecten colisiones de ID en el momento de la creación del evento. Para minimizar el riesgo de colisiones, te recomendamos que uses un algoritmo de UUID establecido, como el que se describe en RFC4122.

Si no especificas un ID, el servidor lo generará automáticamente.

Ten en cuenta que icalUID y el ID no son idénticos, y solo se debe proporcionar uno de ellos en el momento de la creación del evento. Una diferencia en su semántica es que, en los eventos recurrentes, todas las ocurrencias de un evento tienen IDs diferentes, pero todas comparten el mismo icalUID.
status

string

Es el estado del evento. Opcional. Los valores posibles son:

  • confirmed: Se confirmó el evento. Este es el estado predeterminado.
  • tentative: El evento se confirmó de forma tentativa.
  • cancelled: Se canceló (borró) el evento. El método list muestra eventos cancelados solo en la sincronización incremental (cuando se especifican syncToken o updatedMin) o si la marca showDeleted se establece en verdadero. El método get siempre los devuelve.

El estado cancelado representa dos estados diferentes según el tipo de evento:

  1. Las excepciones canceladas de un evento recurrente no cancelado indican que esta instancia ya no se debe presentar al usuario. Los clientes deben almacenar estos eventos durante la vida útil del evento recurrente principal.Solo se garantiza que las excepciones de cancelación tengan valores para los campos id, recurringEventId y originalStartTime completados. Es posible que los otros campos estén vacíos.
  2. Todos los demás eventos cancelados representan eventos borrados. Los clientes deben quitar las copias sincronizadas de forma local. Estos eventos cancelados desaparecerán con el tiempo, por lo que no debes confiar en que estarán disponibles de forma indefinida. Solo se garantiza que los eventos borrados tengan el campo id completado.

En el calendario del organizador, los eventos cancelados siguen exponiendo los detalles del evento (resumen, ubicación, etcétera) para que se puedan restablecer (deshacer la eliminación). Del mismo modo, los eventos a los que se invitó al usuario y que quitó manualmente siguen proporcionando detalles. Sin embargo, las solicitudes de sincronización incrementales con showDeleted establecido como falso no devolverán estos detalles.

Si un evento cambia de organizador (por ejemplo, a través de la operación de movimiento) y el organizador original no está en la lista de asistentes, quedará un evento cancelado en el que solo se garantiza que se completará el campo id.
htmlLink

string

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

string

Es la fecha y hora de creación del evento (como una marca de tiempo con formato ISO 8601). Solo lectura.
updated

string

Es la fecha y hora de la última modificación de los datos del evento principal (como una marca de tiempo con formato ISO 8601). La actualización de los recordatorios de eventos no provocará este cambio. Solo lectura.
summary

string

Corresponde al título del evento.
description

string

Descripción del evento. Puede contener HTML. Opcional.
location

string

Ubicación geográfica del evento como texto de formato libre. Opcional.
creator

object (Principal)

Es el creador del evento. Solo lectura.
organizer

object (Principal)

Es el organizador del evento. Si el organizador también es asistente, esto se indica con una entrada separada en los asistentes con el campo del organizador establecido en verdadero. Solo lectura.
start

object (DateOrDateTime)

Es la hora de inicio (inclusive) del evento. En el caso de un evento recurrente, esta es la hora de inicio de la primera instancia.
end

object (DateOrDateTime)

Es la hora de finalización (exclusiva) del evento. En el caso de un evento recurrente, esta es la hora de finalización de la primera instancia.
recurrence[]

string

Lista de líneas RRULE, EXRULE, RDATE y EXDATE para un evento recurrente, como se especifica en RFC5545. Ten en cuenta que no se permiten las líneas DTSTART y DTEND en este campo. Las horas de inicio y finalización del evento se especifican en los campos de inicio y finalización. Este campo se omite para eventos únicos o instancias de eventos recurrentes.
recurringEventId

string

En el caso de una instancia de un evento recurrente, es el ID del evento recurrente al que pertenece esta instancia. Inmutable.
originalStartTime

object (DateOrDateTime)

En el caso de una instancia de un evento recurrente, es la hora a la que comenzaría este evento según los datos de recurrencia del evento recurrente identificado por recurringEventId. Identifica de forma única la instancia dentro de la serie de eventos recurrentes, incluso si la instancia se trasladó a otro horario. Inmutable.
transparency

string

Indica si el evento bloquea tiempo en el calendario. Opcional. Los valores posibles son:

  • opaque: Valor predeterminado. El evento bloquea tiempo en el calendario. Esto equivale a configurar Mostrarme como En ocupado en la IU del Calendario.
  • transparent: El evento no bloquea tiempo en el calendario. Esto equivale a configurar Mostrarme como Disponible en la IU del Calendario.
visibility

string

Visibilidad del evento. Opcional. Los valores posibles son:

  • default: Usa la visibilidad predeterminada para los eventos del calendario. Este es el valor predeterminado.
  • public: El evento es público y los detalles son visibles para todos los lectores del calendario.
  • private: El evento es privado y solo los asistentes pueden ver sus detalles.
  • confidential: El evento es privado. Este valor se proporciona por motivos de compatibilidad.
attendees[]

object (Attendee)

Son los asistentes al evento.
eventType

string

Es el tipo específico del evento. Este parámetro no se puede modificar después de crear el evento. Los valores posibles son:

  • birthday: Es un evento especial de todo el día con recurrencia anual.
  • default: Es un evento normal o no se especificó más.
  • focusTime: Es un evento de tiempo dedicado.
  • fromGmail: Es un evento de Gmail. No se puede crear este tipo de evento.
  • outOfOffice: Es un evento fuera de la oficina.
  • workingLocation: Es un evento de ubicación de trabajo.
conferenceUrl

string

Vínculo de Google Meet para el evento.
colorId

string

ID de color del evento (cadena 1-11):

  • 1: Lavanda
  • 2: Sage
  • 3: Uva
  • 4: Flamenco
  • 5: Banana
  • 6: Mandarina
  • 7: Peacock
  • 8: Grafito
  • 9: Índigo
  • 10: Albahaca
  • 11: Tomate

En el Calendario de Google, los colores de los eventos funcionan como categorías que se pueden configurar por evento o por serie. Los usuarios pueden asignar etiquetas personalizadas a los colores en la IU web (p.ej., 1:1s, Break), pero la API solo expone IDs numéricos, no esas etiquetas. Solo afecta tu vista del calendario. Cada asistente controla el color de su propio evento.
overrideReminders[]

object (Reminder)

Son los recordatorios definidos para este evento, que anulan los recordatorios predeterminados del calendario. Si no se establece, se usan los recordatorios predeterminados del calendario.

Principal

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

string

Dirección de correo electrónico del principal (calendario).
displayName

string

Nombre del director, si está disponible.
self

boolean

Indica si este principal corresponde al calendario en el que aparece esta copia del evento. Solo lectura. El valor predeterminado es False.

DateOrDateTime

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

string

Es una fecha con formato ISO 8601 a la medianoche (UTC), como 2019-11-20T00:00:00Z. Si se establece este campo, no se debe establecer date_time.
dateTime

string

Es una marca de tiempo con formato ISO 8601, como 2019-11-20T08:19:06-07:00 o 2019-11-20T08:19:06Z. Si se establece este campo, no se debe establecer date.
timeZone

string

Nombre de la zona horaria de TZDB, si está disponible.

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
id

string

ID del perfil del asistente, si está disponible.
email

string

Dirección de correo electrónico del asistente, si está disponible. Este campo debe estar presente cuando se agrega un asistente. Debe ser una dirección de correo electrónico válida según el RFC5322. Se requiere cuando se agrega un asistente.
displayName

string

Nombre del asistente, si está disponible. Opcional.
organizer

boolean

Indica si el asistente es el organizador del evento. Solo lectura. El valor predeterminado es False.
self

boolean

Indica si esta entrada representa el calendario en el que aparece esta copia del evento. Solo lectura. El valor predeterminado es False.
resource

boolean

Indica si el asistente es un recurso. Solo se puede configurar cuando se agrega el asistente al evento por primera vez. Se ignoran las modificaciones posteriores. Opcional. El valor predeterminado es False.
optionalAttendee

boolean

Indica si el asistente es opcional. Opcional. El valor predeterminado es False.
responseStatus

string

Es el estado de respuesta del asistente. Los valores posibles son:

  • needsAction: El asistente no respondió 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.
comment

string

Es el comentario de respuesta del asistente. Opcional.
additionalGuests

integer

Cantidad de huéspedes adicionales. Opcional. El valor predeterminado es 0.

Anotaciones de herramientas

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