MCP Tools Reference: calendarmcp.googleapis.com

Strumento: list_events

Restituisce gli eventi nel calendario specificato che corrispondono a tutti i vincoli specificati. I vincoli di tempo non devono essere specificati, a meno che non siano richiesti dall'utente. Per le ricerche basate su parole chiave o argomenti a tempo indeterminato nel calendario principale, è necessario utilizzare lo strumento search_events.

Il seguente esempio mostra come utilizzare curl per richiamare lo strumento MCP list_events.

Richiesta 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
}'

Schema di input

ListEventsRequest

Rappresentazione JSON 
{
  "eventTypeFilter": [
    string
  ],
  "eventType": [
    enum (EventType)
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

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

string

Facoltativo. Deprecato: utilizza event_type.
eventType[]

enum (EventType)

Facoltativo. I tipi di eventi da restituire. Se è vuoto, vengono restituiti solo i seguenti tipi di eventi: DEFAULT, OUT_OF_OFFICE, FOCUS_TIME, FROM_GMAIL

Campo unione _calendar_id.

_calendar_id può essere solo uno dei seguenti tipi:
calendarId

string

Facoltativo. L'ID del calendario contenente gli eventi. Indirizzo email: può essere risolto utilizzando list_calendars. Valore predefinito: calendario principale.

Campo unione _page_size.

_page_size può essere solo uno dei seguenti tipi:
pageSize

integer

Facoltativo. Numero massimo di eventi per pagina (valore predefinito 100, massimo 250). Consigliato: 10.

Campo unione _page_token.

_page_token può essere solo uno dei seguenti tipi:
pageToken

string

Facoltativo. Token di pagina successiva. Utilizza il valore di nextPageToken della pagina precedente.

Campo unione _start_time.

_start_time può essere solo uno dei seguenti tipi:
startTime

string

Facoltativo. Il limite inferiore di un intervallo di tempo. Deve essere impostato solo quando l'utente richiede un periodo di tempo specifico. Deve essere un timestamp ISO 8601 inferiore a end_time.

Campo unione _end_time.

_end_time può essere solo uno dei seguenti tipi:
endTime

string

Facoltativo. Il limite superiore di un intervallo di tempo. Deve essere impostato solo quando l'utente richiede un periodo di tempo specifico o un'ora nel passato. Deve essere un timestamp ISO 8601 maggiore di start_time.

Campo unione _time_zone.

_time_zone può essere solo uno dei seguenti tipi:
timeZone

string

Facoltativo. Fuso orario (ID IANA, ad esempio Europe/Zurich) utilizzato per risolvere le date senza fuso orario. Predefinito: il fuso orario del calendario.

Campo unione _order_by.

_order_by può essere solo uno dei seguenti tipi:
orderBy

string

Facoltativo. L'ordine in cui devono essere restituiti gli eventi. I valori possibili sono:

  • default - Non specificato, ma ordinamento deterministico (impostazione predefinita).
  • startTime - Ordina per ora di inizio in ordine crescente.
  • startTimeDesc - Ordina per ora di inizio in ordine decrescente.
  • lastModified: ordina per data/ora ultima modifica in ordine crescente.

Campo unione _full_text.

_full_text può essere solo uno dei seguenti tipi:
fullText

string

Facoltativo. Ricerca senza distinzione tra maiuscole e minuscole in formato libero che corrisponde a titolo, descrizione, luogo o partecipanti. Corrisponde agli eventi che contengono tutti i termini della query letteralmente (ricerca AND).

EventType

Tipo di evento. Immutabile dopo la creazione.

Enum
EVENT_TYPE_UNSPECIFIED Considerato come DEFAULT.
DEFAULT Evento regolare. Valore predefinito.
OUT_OF_OFFICE Evento fuori sede.
FOCUS_TIME Evento di momento di concentrazione.
WORKING_LOCATION Evento riguardante il luogo di lavoro.
BIRTHDAY Evento speciale che dura tutto il giorno con una ricorrenza annuale.
FROM_GMAIL Evento da Gmail. Non è possibile creare questo tipo di evento.

Schema di output

ListEventsResponse

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

  "nextPageToken": string
}
Campi
summary

string

Il titolo del calendario.
description

string

Descrizione del calendario.
updated

string

Ora dell'ultimo aggiornamento (ISO 8601) del calendario.
timeZone

string

Il fuso orario del calendario.
accessRole

string

Solo output. Ruolo di accesso dell'utente per il calendario. I valori possibili sono:

  • none - Nessun accesso.
  • freeBusyReader - Accesso in lettura alle informazioni sullo stato libero/occupato.
  • reader - Accesso in lettura al calendario. Gli eventi privati verranno visualizzati, ma i dettagli degli eventi sono nascosti.
  • writer - Accesso in lettura e scrittura. Vengono visualizzati gli eventi privati e i relativi dettagli.
  • owner: accesso con autorizzazioni di gestione, inclusa la possibilità di modificare le impostazioni di condivisione del calendario.
Importante: il ruolo owner è diverso dal proprietario dei dati del calendario. Un calendario ha un solo proprietario dei dati, ma può avere più utenti con il ruolo owner.
defaultReminders[]

object (Reminder)

Promemoria predefiniti per gli eventi nel calendario.
events[]

object (Event)

Elenco degli eventi.

Campo unione _next_page_token.

_next_page_token può essere solo uno dei seguenti tipi:
nextPageToken

string

Token di pagina successiva. Omesso se non esiste una pagina successiva.

Promemoria

Rappresentazione JSON 
{

  "method": string

  "minutes": integer
}
Campi

Campo unione _method.

_method può essere solo uno dei seguenti tipi:
method

string

Obbligatorio. Metodo di pubblicazione. I valori possibili sono:

  • email - I promemoria vengono inviati via email.
  • popup: i promemoria vengono inviati tramite un popup dell'interfaccia utente.

Campo unione _minutes.

_minutes può essere solo uno dei seguenti tipi:
minutes

integer

Obbligatorio. Minuti di anticipo con cui viene attivato il promemoria.

Evento

Rappresentazione 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)
}
Campi
id

string

Identificatore univoco.
status

string

Facoltativo. Stato. I valori possibili sono:

  • confirmed - Evento confermato (impostazione predefinita).
  • tentative - Evento confermato provvisoriamente.
  • cancelled - L'evento è annullato o eliminato.
htmlLink

string

Solo output. Un link assoluto a questo evento nell'interfaccia utente web di Google Calendar.
created

string

Solo output. Data/ora di creazione (ISO 8601).
updated

string

Solo output. Data/ora ultima modifica (ISO 8601).
summary

string

Titolo.
description

string

Facoltativo. Descrizione. Può contenere HTML.
location

string

Facoltativo. Posizione.
creator

object (Principal)

Solo output. Creator.
organizer

object (Principal)

Solo output. Organizzatore. Se partecipa, è elencato anche tra i partecipanti.
start

object (DateOrDateTime)

Ora di inizio (inclusa). Per gli eventi ricorrenti viene utilizzata la prima istanza.
end

object (DateOrDateTime)

Ora di fine (esclusa). Per gli eventi ricorrenti viene utilizzata la prima istanza.
recurrence[]

string

Regole di ricorrenza come stringhe RRULE, EXRULE, RDATE o EXDATE (in base a RFC 5545). Omesso per i singoli eventi. Le ore di inizio/fine devono essere impostate nei campi start/end.
recurringEventId

string

ID evento ricorrente principale per le istanze di eventi ricorrenti.
originalStartTime

object (DateOrDateTime)

Ora di inizio originale delle istanze ricorrenti. Questa è l'ora in cui questa istanza dovrebbe iniziare in base ai dati di ricorrenza.
transparency
(deprecated)

string

Facoltativo. Deprecato: utilizza availability.
visibility

string

Facoltativo. Visibilità dell'evento. I valori possibili sono:

  • default: utilizza la visibilità predefinita per gli eventi nel calendario. Questo è il valore predefinito.
  • public: i dettagli dell'evento sono visibili a tutti i lettori del calendario.
  • private: solo i partecipanti all'evento possono visualizzare i dettagli dell'evento.

attendees[]

object (Attendee)

Partecipanti.
conferenceUrl

string

Link alla videoconferenza.
colorId

string

Il colore dell'evento. Influisce solo sulla visualizzazione del tuo calendario. Si tratta di un ID che fa riferimento a una voce nella tavolozza dei colori del calendario (stringa '1'-'11'):

  • 1: Lavanda
  • 2: Verde salvia
  • 3: Uva
  • 4: Fenicottero
  • 5: Banana
  • 6: Mandarino
  • 7: Blu pavone
  • 8: Grafite
  • 9: Mirtillo
  • 10: Basilico
  • 11: Pomodoro.

overrideReminders[]

object (Reminder)

Promemoria. Se non impostato, vengono ripristinate le impostazioni predefinite del calendario.
attachments[]

object (Attachment)

Allegati dei file.
guestPermissions

object (GuestPermissions)

Autorizzazioni per gli invitati.
eventType

enum (EventType)

Tipo di evento.
workingLocationProperties

object (WorkingLocationProperties)

Proprietà del luogo di lavoro. Compilato solo quando event_type è WORKING_LOCATION.
availability

enum (Availability)

Facoltativo. Impostazione di disponibilità.

Entità

Rappresentazione JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Campi
email

string

le email,
displayName

string

Nome
self

boolean

Solo output. Indica se questo principal corrisponde al calendario in cui viene visualizzata questa copia dell'evento. Valore predefinito: false.

DateOrDateTime

Rappresentazione JSON 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Campi
date

string

Data ISO 8601 a mezzanotte UTC (ad esempio, '2019-11-20T00:00:00Z').
dateTime

string

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

string

Nome del fuso orario TZDB.

Partecipante

Rappresentazione JSON 
{

  "id": string

  "email": string

  "displayName": string

  "organizer": boolean

  "self": boolean

  "resource": boolean

  "optionalAttendee": boolean

  "responseStatus": string

  "comment": string

  "additionalGuests": integer
}
Campi

Campo unione _id.

_id può essere solo uno dei seguenti tipi:
id

string

Solo output. ID profilo.

Campo unione _email.

_email può essere solo uno dei seguenti tipi:
email

string

Obbligatorio. L'indirizzo email del partecipante.

Campo unione _display_name.

_display_name può essere solo uno dei seguenti tipi:
displayName

string

Facoltativo. Nome

Campo unione _organizer.

_organizer può essere solo uno dei seguenti tipi:
organizer

boolean

Solo output. Indica se il partecipante è l'organizzatore. Valore predefinito: false.

Campo unione _self.

_self può essere solo uno dei seguenti tipi:
self

boolean

Solo output. Indica se questa voce rappresenta il calendario in cui viene visualizzata questa copia dell'evento. Valore predefinito: false.

Campo unione _resource.

_resource può essere solo uno dei seguenti tipi:
resource

boolean

Facoltativo. Indica se il partecipante è una risorsa (ad esempio una stanza). Immutabile, può essere impostato solo quando il partecipante viene aggiunto inizialmente. Valore predefinito: false.

Campo unione _optional_attendee.

_optional_attendee può essere solo uno dei seguenti tipi:
optionalAttendee

boolean

Facoltativo. Indica se il partecipante è facoltativo. Valore predefinito: false.

Campo unione _response_status.

_response_status può essere solo uno dei seguenti tipi:
responseStatus

string

Facoltativo. Stato della risposta. I valori possibili sono:

  • needsAction - Il partecipante non ha risposto all'invito (opzione consigliata per i nuovi eventi).
  • declined: il partecipante ha rifiutato l'invito.
  • tentative: il partecipante ha accettato provvisoriamente l'invito.
  • accepted: il partecipante ha accettato l'invito.

Campo unione _comment.

_comment può essere solo uno dei seguenti tipi:
comment

string

Solo output. Commento alla risposta.

Campo unione _additional_guests.

_additional_guests può essere solo uno dei seguenti tipi:
additionalGuests

integer

Facoltativo. Numero di ospiti aggiuntivi. Valore predefinito: 0.

Allegato

Rappresentazione JSON 
{

  "fileUrl": string

  "title": string
}
Campi

Campo unione _file_url.

_file_url può essere solo uno dei seguenti tipi:
fileUrl

string

Obbligatorio. Link URL all'allegato.

Campo unione _title.

_title può essere solo uno dei seguenti tipi:
title

string

Facoltativo. Titolo dell'allegato.

GuestPermissions

Rappresentazione JSON 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
Campi

Campo unione _guests_can_invite_others.

_guests_can_invite_others può essere solo uno dei seguenti tipi:
guestsCanInviteOthers

boolean

Facoltativo. Se gli invitati possono invitare altre persone.

Campo unione _guests_can_modify.

_guests_can_modify può essere solo uno dei seguenti tipi:
guestsCanModify

boolean

Facoltativo. Indica se gli invitati possono modificare l'evento.

Campo unione _guests_can_see_guests.

_guests_can_see_guests può essere solo uno dei seguenti tipi:
guestsCanSeeGuests

boolean

Facoltativo. Se gli invitati possono vedere gli altri invitati.

WorkingLocationProperties

Rappresentazione JSON 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
Campi

Campo unione _type.

_type può essere solo uno dei seguenti tipi:
type

enum (WorkingLocationType)

Facoltativo. Tipo di luogo di lavoro.

Campo unione _custom_location_label.

_custom_location_label può essere solo uno dei seguenti tipi:
customLocationLabel

string

Facoltativo. L'etichetta di una località personalizzata. Obbligatorio se il tipo è CUSTOM_LOCATION.

EventType

Tipo di evento. Immutabile dopo la creazione.

Enum
EVENT_TYPE_UNSPECIFIED Considerato come DEFAULT.
DEFAULT Evento regolare. Valore predefinito.
OUT_OF_OFFICE Evento fuori sede.
FOCUS_TIME Evento di momento di concentrazione.
WORKING_LOCATION Evento riguardante il luogo di lavoro.
BIRTHDAY Evento speciale che dura tutto il giorno con una ricorrenza annuale.
FROM_GMAIL Evento da Gmail. Non è possibile creare questo tipo di evento.

WorkingLocationType

Tipo di luogo di lavoro.

Enum
WORKING_LOCATION_TYPE_UNSPECIFIED Tipo di luogo di lavoro non specificato. Verrà considerato come HOME_OFFICE.
HOME_OFFICE Ufficio domestico.
CUSTOM_LOCATION Località personalizzata.

Disponibilità

Impostazione della disponibilità per un evento.

Enum
AVAILABILITY_UNSPECIFIED Predefinita. Considerato come BUSY.
AVAILABILITY_BUSY Blocca l'ora nel calendario.
AVAILABILITY_FREE Non blocca il tempo.

Annotazioni dello strumento

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ✅ | Suggerimento di sola lettura: ✅ | Suggerimento open world: ❌

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti 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