MCP Tools Reference: calendarmcp.googleapis.com

Strumento: create_event

Crea un evento nel calendario.

Utilizza questo strumento per query come:

  • Crea un evento sul mio calendario per domani alle 14:00 chiamato "Riunione con Jane".
  • Pianifica una riunione con john.doe@google.com lunedì prossimo dalle 10:00 alle 11:00.

Esempio:

create_event(
            summary='Meeting with Jane',
            startTime='2024-09-17T14:00:00',
            endTime='2024-09-17T15:00:00'
        )
        # Creates an event on the primary calendar for September 17, 2024 from 2pm to 3pm called 'Meeting with Jane'.

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

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": "create_event",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schema di input

Messaggio di richiesta per CreateEvent.

CreateEventRequest

Rappresentazione JSON 
{
  "summary": string,
  "startTime": string,
  "endTime": string,
  "attendeeEmails": [
    string
  ],
  "recurrenceData": [
    string
  ],
  "overrideReminders": [
    {
      object (Reminder)
    }
  ],

  "calendarId": string

  "description": string

  "location": string

  "allDay": boolean

  "timeZone": string

  "notificationLevel": enum (NotificationLevel)

  "addGoogleMeetUrl": boolean

  "visibility": string

  "colorId": string

  "googleMeetUrl": string
}
Campi
summary

string

Obbligatorio. Titolo dell'evento.
startTime

string

Obbligatorio. L'ora di inizio dell'evento formattata in base allo standard ISO 8601.
endTime

string

Obbligatorio. L'ora di fine dell'evento formattata secondo lo standard ISO 8601.
attendeeEmails[]

string

Facoltativo. I partecipanti aggiuntivi all'evento, come indirizzi email. Per gli eventi creati nel calendario principale dell'utente con almeno un altro partecipante, l'utente corrente verrà aggiunto automaticamente come partecipante se non è già incluso in questo elenco.
recurrenceData[]

string

Facoltativo. I dati di ricorrenza dell'evento come RRULE, RDATE o EXDATE in base alla RFC 5545. Utilizza questo campo per creare un evento ricorrente.
overrideReminders[]

object (Reminder)

Facoltativo. Promemoria definiti per questo evento, che sostituiscono i promemoria predefiniti per il calendario. Se non viene impostato, l'evento utilizzerà i promemoria predefiniti del calendario.

Campo unione _calendar_id.

_calendar_id può essere solo uno dei seguenti tipi:
calendarId

string

Facoltativo. L'ID del calendario in cui creare l'evento. Il valore predefinito è il calendario principale dell'utente.

Campo unione _description.

_description può essere solo uno dei seguenti tipi:
description

string

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

Campo unione _location.

_location può essere solo uno dei seguenti tipi:
location

string

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

Campo unione _all_day.

_all_day può essere solo uno dei seguenti tipi:
allDay

boolean

Facoltativo. Specifica se l'evento dura tutto il giorno. Il valore predefinito è False. Se il valore è true, l'ora di inizio e di fine deve essere impostata su mezzanotte UTC.

Campo unione _time_zone.

_time_zone può essere solo uno dei seguenti tipi:
timeZone

string

Facoltativo. Il fuso orario dell'evento (formattato come nome del database dei fusi orari IANA, ad es. "Europe/Zurich"). Facoltativo, ma consigliato. Viene utilizzato anche per risolvere le date senza fuso orario nella richiesta. Il valore predefinito è il fuso orario del calendario.

Campo unione _notification_level.

_notification_level può essere solo uno dei seguenti tipi:
notificationLevel

enum (NotificationLevel)

Facoltativo. Quale notifica email deve essere inviata per questo aggiornamento dell'evento. I valori possibili sono:

  • NONE: non vengono inviate notifiche via email (impostazione predefinita).
  • EXTERNAL_ONLY: solo i partecipanti esterni (non di Calendar) ricevono notifiche via email.
  • ALL: tutti i partecipanti all'evento ricevono notifiche via email.

Campo unione _add_google_meet_url.

_add_google_meet_url può essere solo uno dei seguenti tipi:
addGoogleMeetUrl

boolean

Facoltativo. Consente di creare un URL di Google Meet per l'evento. Per impostazione predefinita, non viene creato alcun URL Google Meet. Se Meet è disattivato per l'utente, non viene creato alcun URL di Google Meet, ma la creazione dell'evento andrà a buon fine.

Campo unione _visibility.

_visibility può essere solo uno dei seguenti tipi:
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: 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.

Campo unione _color_id.

_color_id può essere solo uno dei seguenti tipi:
colorId

string

Facoltativo. Il colore dell'evento. Si tratta di un ID che fa riferimento a una voce nella tavolozza dei colori del calendario. 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.

Campo unione _google_meet_url.

_google_meet_url può essere solo uno dei seguenti tipi:
googleMeetUrl

string

Facoltativo. Consente di allegare all'evento un URL o un ID riunione di Google Meet esistente. Se impostato, questo URL verrà allegato all'evento anziché generare una nuova sala Google Meet, anche se add_google_meet_url è impostato su true.

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.

Schema di output

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.

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.

Annotazioni dello strumento

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