MCP Tools Reference: calendarmcp.googleapis.com

Strumento: list_events

Elenca gli eventi del calendario in un determinato calendario che soddisfano le condizioni specificate.

Funzionalità principali:

  • Qualsiasi ID calendario, che può essere il calendario principale dell'utente o altri.
  • Filtro dell'intervallo di tempo.
  • Recupera TUTTI gli eventi che corrispondono ai vincoli temporali.

Se disponibile, utilizza lo strumento search_events per le ricerche nel calendario principale dell'utente se:

  • Stai eseguendo una query per eventi che corrispondono a un argomento, una categoria o un intento specifico (ad es. "pranzi di lavoro", "aggiornamenti di progetto").
  • Devi trovare i primi K eventi più pertinenti anziché tutti gli eventi che soddisfano i vincoli.
  • Devi disporre delle funzionalità di ricerca semantica o per parola chiave.

Utilizza questo strumento per query come:

  • Cosa c'è nel mio calendario domani?
  • Cosa è segnato sul mio calendario per il 14 luglio 2025?
  • Quali sono le mie riunioni della prossima settimana?
  • Ho qualche conflitto questo pomeriggio?

  • Quali riunioni ha Giovanni domani?

Esempio:

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.

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

Curl Request 
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
}'

Schema di input

ListEventsRequest

Rappresentazione JSON 
{
  "eventTypeFilter": [
    string
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Campi
eventTypeFilter[]

string

Facoltativo. I tipi di eventi da restituire. I valori possibili sono:

  • default - Eventi regolari (impostazione predefinita).
  • outOfOffice - Eventi fuori sede.
  • focusTime - Eventi di momento di concentrazione.
  • workingLocation - Eventi relativi al luogo di lavoro.
  • birthday - Eventi di compleanno.
  • fromGmail - Eventi da Gmail.

Se è vuoto, vengono restituiti solo i seguenti tipi di eventi: default, outOfOffice, focusTime, fromGmail

Campo unione _calendar_id.

_calendar_id può essere solo uno dei seguenti tipi:
calendarId

string

Facoltativo. L'ID del calendario da cui elencare gli eventi. Il valore predefinito è il calendario principale dell'utente.

Campo unione _page_size.

_page_size può essere solo uno dei seguenti tipi:
pageSize

integer

Facoltativo. Numero massimo di eventi restituiti in una pagina dei risultati. Il numero di eventi nella pagina risultante potrebbe essere inferiore a questo valore o pari a zero, anche se ci sono più eventi che corrispondono alla query. Le pagine incomplete possono essere rilevate da un campo next_page_token non vuoto nella risposta. Per impostazione predefinita, il valore è 250 eventi. Le dimensioni della pagina non possono mai superare i 2500 eventi.

Campo unione _page_token.

_page_token può essere solo uno dei seguenti tipi:
pageToken

string

Facoltativo. Token che specifica quale pagina dei risultati restituire.

Campo unione _start_time.

_start_time può essere solo uno dei seguenti tipi:
startTime

string

Facoltativo. Limite inferiore (esclusivo) per l'ora di fine di un evento. Vengono restituiti solo gli eventi che terminano rigorosamente dopo questo orario (ovvero l'inizio della finestra temporale in cui eseguire la ricerca). Se non vengono forniti né start_time né end_time, il valore predefinito è l'ora attuale. Se specificato, deve essere inferiore o uguale a end_time. Deve essere un timestamp ISO 8601. Ad esempio, 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z o 2026-06-03T10:00:00. I millisecondi possono essere forniti, ma vengono ignorati.

Campo unione _end_time.

_end_time può essere solo uno dei seguenti tipi:
endTime

string

Facoltativo. Limite superiore (esclusivo) per l'ora di inizio di un evento. Vengono restituiti solo gli eventi che iniziano prima di questo orario (ovvero la fine della finestra temporale di ricerca). Se specificato, deve essere maggiore o uguale a start_time. Deve essere un timestamp ISO 8601. Ad esempio, 2026-06-03T10:00:00-07:00, 2026-06-03T10:00:00Z o 2026-06-03T10:00:00. I millisecondi possono essere forniti, ma vengono ignorati.

Campo unione _time_zone.

_time_zone può essere solo uno dei seguenti tipi:
timeZone

string

Facoltativo. Il fuso orario utilizzato nella risposta e per risolvere le date senza fuso orario nella richiesta (formattato come nome del database dei fusi orari IANA, ad es. Europe/Zurich). Il valore 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. Query di ricerca in formato libero per cercare in titolo, descrizione, posizione e partecipanti.

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

L'ora dell'ultima modifica del calendario (come timestamp ISO 8601).
timeZone

string

Il fuso orario del calendario.
accessRole

string

Il ruolo di accesso dell'utente per questo calendario. Sola lettura. I valori possibili sono:

  • none: l'utente non ha accesso.
  • freeBusyReader: l'utente dispone dell'accesso in lettura alle informazioni sul servizio libero/occupato.
  • reader: l'utente ha accesso in lettura al calendario. Gli eventi privati verranno visualizzati dagli utenti con accesso in lettura, ma i dettagli degli eventi verranno nascosti.
  • writer: l'utente ha accesso in lettura e scrittura al calendario. Gli eventi privati verranno visualizzati dagli utenti con accesso di scrittura e i dettagli dell'evento saranno visibili.
  • owner: l'utente dispone dell'accesso amministratore al calendario. Questo ruolo ha tutte le autorizzazioni del ruolo Autore, con la possibilità aggiuntiva di visualizzare e modificare i livelli di accesso di altri utenti. Importante: il ruolo di proprietario è diverso da quello di proprietario dei dati del calendario. Un calendario ha un solo proprietario dei dati, ma può avere più utenti con il ruolo di proprietario.
defaultReminders[]

object (Reminder)

I promemoria predefiniti sul calendario per l'utente autenticato. Questi promemoria si applicano a tutti gli eventi di questo calendario che non li sostituiscono esplicitamente (ovvero non compilano override_reminders).
events[]

object (Event)

Elenco degli eventi nel calendario.

Campo unione _next_page_token.

_next_page_token può essere solo uno dei seguenti tipi:
nextPageToken

string

Token utilizzato per accedere alla pagina successiva di questo risultato. Omesso se non sono disponibili altri risultati.

Promemoria

Rappresentazione JSON 
{

  "method": string

  "minutes": integer
}
Campi

Campo unione _method.

_method può essere solo uno dei seguenti tipi:
method

string

Obbligatorio. Come viene recapitato il promemoria all'utente. 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. Numero di minuti di anticipo con cui deve essere inviato 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)
    }
  ],
  "eventType": string,
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ]
}
Campi
id

string

Identificatore opaco dell'evento. Quando crei eventi singoli o ricorrenti, puoi specificarne gli ID. Gli ID forniti devono rispettare le seguenti regole:

  • I caratteri consentiti nell'ID sono quelli utilizzati nella codifica base32hex, ovvero le lettere minuscole a-v e le cifre 0-9.Vedi la sezione 3. 1.2 della RFC2938.
  • La lunghezza dell'ID deve essere compresa tra 5 e 1024 caratteri
  • l'ID deve essere univoco per ogni calendario

A causa della natura distribuita a livello globale del sistema, non possiamo garantire che le collisioni di ID vengano rilevate al momento della creazione dell'evento. Per ridurre al minimo il rischio di collisioni, ti consigliamo di utilizzare un algoritmo UUID consolidato, ad esempio quello descritto in RFC4122.

Se non specifichi un ID, questo verrà generato automaticamente dal server.

Tieni presente che icalUID e id non sono identici e solo uno dei due deve essere fornito al momento della creazione dell'evento. Una differenza nella loro semantica è che negli eventi ricorrenti tutte le occorrenze di un evento hanno ID diversi, mentre condividono tutti gli stessi icalUID.
status

string

Stato dell'evento. Facoltativo. I valori possibili sono:

  • confirmed - L'evento è confermato. Questo è lo stato predefinito.
  • tentative - L'evento è confermato provvisoriamente.
  • cancelled - L'evento è annullato (eliminato). Il metodo list restituisce gli eventi annullati solo nella sincronizzazione incrementale (quando vengono specificati syncToken o updatedMin) o se il flag showDeleted è impostato su true. Il metodo get li restituisce sempre.

Lo stato Annullato rappresenta due stati diversi a seconda del tipo di evento:

  1. Le eccezioni annullate di un evento ricorrente non annullato indicano che questa istanza non deve più essere presentata all'utente. I client devono archiviare questi eventi per la durata dell'evento ricorrente principale.Le eccezioni annullate hanno la garanzia di avere valori solo per i campi id, recurringEventId e originalStartTime. Gli altri campi potrebbero essere vuoti.
  2. Tutti gli altri eventi annullati rappresentano eventi eliminati. I clienti devono rimuovere le copie sincronizzate localmente. Gli eventi annullati alla fine scompariranno, quindi non fare affidamento sulla loro disponibilità a tempo indeterminato. È garantito che gli eventi eliminati abbiano compilato solo il campo ID.

Nel calendario dell'organizzatore, gli eventi annullati continuano a mostrare i dettagli (riepilogo, posizione e così via) in modo che possano essere ripristinati (recuperati). Allo stesso modo, gli eventi a cui l'utente è stato invitato e che ha rimosso manualmente continuano a fornire dettagli. Tuttavia, le richieste di sincronizzazione incrementale con showDeleted impostato su false non restituiranno questi dettagli.

Se un evento cambia organizzatore (ad esempio tramite l'operazione di spostamento) e l'organizzatore originale non è presente nell'elenco dei partecipanti, verrà lasciato un evento annullato in cui è garantito il popolamento solo del campo ID.
htmlLink

string

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

string

Ora di creazione dell'evento (come timestamp formattato ISO 8601). Sola lettura.
updated

string

Ora dell'ultima modifica dei dati sugli eventi principali (come timestamp formattato ISO 8601). L'aggiornamento dei promemoria degli eventi non comporterà questa modifica. Sola lettura.
summary

string

Titolo dell'evento.
description

string

Descrizione dell'evento. Può contenere HTML. Facoltativo.
location

string

La posizione geografica dell'evento come testo in formato libero. Facoltativo.
creator

object (Principal)

Il creatore dell'evento. Sola lettura.
organizer

object (Principal)

L'organizzatore dell'evento. Se l'organizzatore è anche un partecipante, questo viene indicato con una voce separata nei partecipanti con il campo dell'organizzatore impostato su True. Sola lettura.
start

object (DateOrDateTime)

L'ora di inizio (inclusa) dell'evento. Per un evento ricorrente, si tratta dell'ora di inizio della prima istanza.
end

object (DateOrDateTime)

L'ora di fine dell'evento (esclusa). Per un evento ricorrente, si tratta dell'ora di fine della prima istanza.
recurrence[]

string

Elenco di righe RRULE, EXRULE, RDATE ed EXDATE per un evento ricorrente, come specificato in RFC5545. Tieni presente che le righe DTSTART e DTEND non sono consentite in questo campo; l'ora di inizio e di fine dell'evento sono specificate nei campi Inizio e Fine. Questo campo viene omesso per i singoli eventi o le istanze di eventi ricorrenti.
recurringEventId

string

Per un'istanza di un evento ricorrente, questo è l'ID dell'evento ricorrente a cui appartiene l'istanza. Immutabile.
originalStartTime

object (DateOrDateTime)

Per un'istanza di un evento ricorrente, questo è l'orario in cui l'evento dovrebbe iniziare in base ai dati di ricorrenza nell'evento ricorrente identificato da recurringEventId. Identifica in modo univoco l'istanza all'interno della serie di eventi ricorrenti, anche se l'istanza è stata spostata a un altro orario. Immutabile.
transparency

string

Indica se l'evento blocca del tempo nel calendario. Facoltativo. I valori possibili sono:

  • opaque - Valore predefinito. L'evento blocca l'ora nel calendario. Questa impostazione equivale a impostare lo stato su Occupato nell'interfaccia utente di Calendar.
  • transparent: l'evento non blocca l'ora nel calendario. Ciò equivale a impostare Mostrami come Disponibile nell'interfaccia utente di Calendar.
visibility

string

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

  • default: utilizza la visibilità predefinita per gli eventi nel calendario. Questo è il valore predefinito.
  • public: l'evento è pubblico e i dettagli sono visibili a tutti i lettori del calendario.
  • private - L'evento è privato e solo i partecipanti possono visualizzarne i dettagli.
  • confidential: l'evento è privato. Questo valore viene fornito per motivi di compatibilità.
attendees[]

object (Attendee)

I partecipanti all'evento.
eventType

string

Tipo specifico di evento. Questo valore non può essere modificato dopo la creazione dell'evento. I valori possibili sono:

  • birthday: un evento speciale che dura tutto il giorno e si ripete ogni anno.
  • default: un evento normale o non specificato ulteriormente.
  • focusTime: un evento di momento di concentrazione.
  • fromGmail: un evento da Gmail. Non è possibile creare questo tipo di evento.
  • outOfOffice: un evento fuori sede.
  • workingLocation: un evento del luogo di lavoro.
conferenceUrl

string

Il link di Google Meet per l'evento.
colorId

string

ID colore evento (stringa 1-11):

  • 1. Lavanda
  • 2: Salvia
  • 3. Uva
  • 4: Fenicottero
  • 5: Banana
  • 6: Mandarino
  • 7. Pavone
  • 8: Grafite
  • 9: Mirtillo
  • 10: Basilico
  • 11: Pomodoro.

In Google Calendar, i colori degli eventi funzionano come categorie, impostabili per evento o per serie. Gli utenti possono assegnare etichette personalizzate ai colori nell'interfaccia utente web (ad es. 1:1s, Break), ma l'API espone solo ID numerici, non queste etichette. Influisce solo sulla visualizzazione del tuo calendario. Ogni partecipante controlla il colore del proprio evento.
overrideReminders[]

object (Reminder)

Promemoria definiti per questo evento, che sostituiscono i promemoria predefiniti per il calendario. Se non viene impostato, vengono utilizzati i promemoria predefiniti del calendario.

Entità

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

string

Indirizzo email dell'entità (calendario).
displayName

string

Il nome dell'entità, se disponibile.
self

boolean

Indica se questo principal corrisponde al calendario in cui viene visualizzata questa copia dell'evento. Sola lettura. Il valore predefinito è False.

DateOrDateTime

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

string

Una data in formato ISO 8601 a mezzanotte UTC, ad esempio 2019-11-20T00:00:00Z. Se questo campo è impostato, date_time non deve essere impostato.
dateTime

string

Un timestamp in formato ISO 8601, ad esempio 2019-11-20T08:19:06-07:00 o 2019-11-20T08:19:06Z. Se questo campo è impostato, date non deve essere impostato.
timeZone

string

Nome del fuso orario TZDB, se disponibile.

Partecipante

Rappresentazione JSON 
{
  "id": string,
  "email": string,
  "displayName": string,
  "organizer": boolean,
  "self": boolean,
  "resource": boolean,
  "optionalAttendee": boolean,
  "responseStatus": string,
  "comment": string,
  "additionalGuests": integer
}
Campi
id

string

L'ID profilo del partecipante, se disponibile.
email

string

L'indirizzo email del partecipante, se disponibile. Questo campo deve essere presente quando viene aggiunto un partecipante. Deve essere un indirizzo email valido secondo RFC5322. Obbligatorio quando viene aggiunto un partecipante.
displayName

string

Il nome del partecipante, se disponibile. Facoltativo.
organizer

boolean

Se il partecipante è l'organizzatore dell'evento. Sola lettura. Il valore predefinito è False.
self

boolean

Indica se questa voce rappresenta il calendario in cui viene visualizzata questa copia dell'evento. Sola lettura. Il valore predefinito è False.
resource

boolean

Indica se il partecipante è una risorsa. Può essere impostato solo quando il partecipante viene aggiunto all'evento per la prima volta. Le modifiche successive vengono ignorate. Facoltativo. Il valore predefinito è False.
optionalAttendee

boolean

Indica se si tratta di un partecipante facoltativo. Facoltativo. Il valore predefinito è False.
responseStatus

string

Lo stato della risposta del partecipante. 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.
comment

string

Il commento di risposta del partecipante. Facoltativo.
additionalGuests

integer

Numero di ospiti aggiuntivi. Facoltativo. Il valore predefinito è 0.

Annotazioni dello strumento

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