Corso
Introduction to Google Workspace with Gemini
30 min
2.6K
Gli agenti AI sono incredibilmente potenti, ma spesso soffrono di un difetto fondamentale: sono scollegati dai luoghi in cui si svolge davvero il nostro lavoro quotidiano, cioè email, calendari e documenti. Senza accesso ai tuoi dati live, un LLM è solo un ottimo generatore di idee.
In questo tutorial ti mostrerò come colmare il divario tra modelli di AI e dati aziendali configurando il server MCP di Google Workspace, comprendendo i più recenti controlli di sicurezza e costruendo un assistente automatizzato.
Alla fine sarai in grado di:
- Comprendere l’architettura del Model Context Protocol (MCP) applicato a Google Workspace.
- Configurare i necessari controlli OAuth e l’accesso alle API in Google Cloud.
- Testare la connettività usando la CLI di Gemini e Google Antigravity.
- Creare un Enterprise AI Assistant in Python con Google ADK capace di leggere email, controllare il calendario e redigere documenti in un unico ciclo di ragionamento.
Prerequisiti
- Un progetto Google Cloud con fatturazione abilitata.
- Conoscenze di base di Python e delle REST API.
- Un account Google Workspace.
Che cos’è il server MCP di Google Workspace?
Il server MCP di Google Workspace è un’implementazione standardizzata del Model Context Protocol (MCP) che permette a qualsiasi client AI compatibile (come Claude Desktop, la CLI di Gemini o agenti personalizzati) di interagire in modo sicuro con le app di Google Workspace.
Invece di scrivere wrapper REST API personalizzati per Gmail, Google Docs, Drive e Calendar per ogni nuovo progetto AI, il server MCP espone queste funzionalità come “strumenti” standardizzati che l’LLM comprende nativamente.
Ti consiglio di dare un’occhiata al corso Introduction to Model Context Protocol (MCP) per fare un po’ di pratica.
Di norma, creare un workflow tra app diverse significa scrivere codice di integrazione fragile. Con MCP, consegni semplicemente gli strumenti all’LLM. L’agente può leggere una conversazione email, individuare un conflitto di orario controllando il tuo calendario e redigere un riepilogo in Google Docs, tutto in autonomia.
Sicurezza e controlli dell’amministratore di Workspace
Quando si concede ai modelli di AI l’accesso a email e file aziendali, la sicurezza dei dati è l’ostacolo principale all’adozione dell’AI.
Il server MCP di Workspace è stato progettato da zero per affrontare questo problema.
Gestisce l’autenticazione affidandosi interamente a OAuth 2.0 e a rigorosi criteri IAM di Google Cloud.
Non esistono “chiavi master” generiche. L’agente agisce sempre e solo per conto dell’utente esplicitamente autenticato, rispettando rigorosamente tutte le autorizzazioni di condivisione di Google Workspace e le ACL dei documenti esistenti.
Inoltre, introduce solidi controlli per gli amministratori.
Gli amministratori di Workspace possono inserire in allowlist strumenti MCP specifici, monitorare l’uso delle API in tutta l’organizzazione e applicare regole di Data Loss Prevention (DLP) per evitare che gli agenti diffondano accidentalmente documenti o email sensibili di Drive a domini esterni non autorizzati.
Configurare l’accesso al server MCP di Workspace
Prima di scrivere codice, “configurazione” qui significa impostare le autorizzazioni di Google Cloud per accedere al server remoto.
Configurare il progetto Google Cloud
Per prima cosa, devi abilitare sia le API standard di Workspace sia i servizi MCP dedicati nel tuo progetto Google Cloud.
- Vai alla Google Cloud Console.
- Abilita le API di Workspace richieste: Gmail API, Google Drive API, Google Docs API e Google Calendar API.
- Abilita i servizi MCP: gmailmcp.googleapis.com, drivemcp.googleapis.com e calendarmcp.googleapis.com.
- Vai su API e servizi > Schermata di consenso OAuth. Configura la schermata di consenso per un pubblico Interno. In Accesso ai dati > Aggiungi o rimuovi ambiti, aggiungi manualmente i seguenti scope per i server che prevedi di usare:
- Google Calendar: https://www.googleapis.com/auth/calendar.calendarlist.readonly, https://www.googleapis.com/auth/calendar.events.freebusy, https://www.googleapis.com/auth/calendar.events.readonly
- Google Chat: https://www.googleapis.com/auth/chat.spaces.readonly, https://www.googleapis.com/auth/chat.memberships.readonly, https://www.googleapis.com/auth/chat.messages.readonly, https://www.googleapis.com/auth/chat.users.readstate.readonly
- Google Drive: https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/drive.file
- Gmail: https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.compose
- People API: https://www.googleapis.com/auth/directory.readonly, https://www.googleapis.com/auth/userinfo.profile, https://www.googleapis.com/auth/contacts.readonly
Generare le credenziali utente
Poiché i dati di Workspace sono specifici dell’utente, l’endpoint MCP remoto richiede un’intestazione Authorization: Bearer <TOKEN> che rappresenti l’utente umano.
Vai su API e servizi > Credenziali e crea un ID client OAuth 2.0 (tipo Applicazione desktop).
Scarica il file JSON delle credenziali. Verrà usato per ottenere il token di accesso OAuth 2.0 necessario tramite un flusso di login nel browser.
Fai clic su Create e copia Client ID e Client Secret. Ti serviranno nel passaggio successivo.
Test della connessione (CLI di Gemini e Antigravity)
Prima di scrivere qualsiasi codice complesso per l’agente Python, è fortemente consigliato eseguire un test “Hello World” per verificare le credenziali e assicurarsi che gli endpoint MCP remoti siano raggiungibili.
Testare la connessione in un ambiente semplificato aiuta a isolare i problemi di autenticazione dalla logica dell’applicazione.
Possiamo testare la connessione sia con la CLI di Gemini sia con l’interfaccia Google Antigravity, ma per ora ci concentreremo sulla CLI di Gemini.
Connessione tramite CLI di Gemini
Il modo più rapido per testare la connettività è usare la CLI di Gemini.
Poiché Workspace richiede un’autenticazione rigorosa, devi configurare l’endpoint e le tue credenziali OAuth nel file ~/.gemini/settings.json:
{
"mcpServers": {
"calendar": {
"httpUrl": "https://calendarmcp.googleapis.com/mcp/v1",
"oauth": {
"enabled": true,
"clientId": "<YOUR_CLIENT_ID>",
"clientSecret": "<YOUR_CLIENT_SECRET>",
"scopes": [
"https://www.googleapis.com/auth/calendar.calendarlist.readonly",
"https://www.googleapis.com/auth/calendar.events.freebusy",
"https://www.googleapis.com/auth/calendar.events.readonly"
]
}
},
"drive": {
"httpUrl": "https://drivemcp.googleapis.com/mcp/v1",
"oauth": {
"enabled": true,
"clientId": "<YOUR_CLIENT_ID>",
"clientSecret": "<YOUR_CLIENT_SECRET>",
"scopes": [
"https://www.googleapis.com/auth/drive.readonly",
"https://www.googleapis.com/auth/drive.file"
]
}
},
"gmail": {
"httpUrl": "https://gmailmcp.googleapis.com/mcp/v1",
"oauth": {
"enabled": true,
"clientId": "<YOUR_CLIENT_ID>",
"clientSecret": "<YOUR_CLIENT_SECRET>",
"scopes": [
"https://www.googleapis.com/auth/gmail.readonly",
"https://www.googleapis.com/auth/gmail.compose"
]
}
}
}
}
Una volta aggiornato il file delle impostazioni, puoi avviare la CLI di Gemini ed eseguire il comando /mcp list.
Vedrai i server di Workspace appena configurati elencati come "Ready" ma con la dicitura "(OAuth not authenticated)".
Questo conferma che la CLI ha letto correttamente la configurazione ed è a conoscenza degli strumenti remoti.
Esecuzione di test di base su Workspace
Ora che i server sono riconosciuti, devi autenticarti prima di poterli usare. Inizia eseguendo il comando di autenticazione per il tuo endpoint Gmail:
/mcp auth gmailQuesto avvierà un flusso OAuth 2.0 basato su browser.
La CLI proverà ad aprire automaticamente il browser predefinito, chiedendoti di accedere con il tuo account Google Workspace e concedere le autorizzazioni richieste.
Se il browser non si apre automaticamente, la CLI fornirà un URL sicuro che puoi copiare e incollare manualmente. Una volta completato l’accesso, la CLI confermerà l’autenticazione riuscita e ricaricherà gli strumenti per quel server.
Completata l’autenticazione, puoi ora testare la connessione con un prompt in linguaggio naturale:
my email for any messages containing the word 'Invoice'.La CLI eseguirà lo strumento dietro le quinte, recupererà i dati dalla tua casella di posta e l’agente li formatterà in una risposta utile:
Progetto demo: creare un agente Workspace con Google ADK
Costruiamo un agente Workspace che si collega a tutti e cinque i servizi (Calendar, Chat, Drive, Gmail, People) e gestisce l’autenticazione in modo sicuro.
Generare le Application Default Credentials (auth.py)
Prima che l’agente possa essere eseguito, ha bisogno di un token OAuth da passare agli endpoint MCP.
La CLI di Gemini lo gestisce automaticamente con /mcp auth, ma per un’applicazione Python dobbiamo generare il nostro token e salvarlo come Application Default Credentials (ADC).
Crea un file chiamato auth.py nella root del progetto. Assicurati di avere il tuo client_secret.json scaricato nella stessa directory.
Questo script usa la libreria ufficiale google-auth-oauthlib per generare un URL di autenticazione, scambiare il codice con un refresh token e scriverlo nel percorso standard ~/.config/gcloud/application_default_credentials.json, dove l’ADK può trovarlo.
import json
import os
from urllib.parse import urlparse, parse_qs
import google.auth
from google_auth_oauthlib.flow import InstalledAppFlow
CLIENT_SECRET_FILE = 'client_secret.json'
SCOPES = [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/calendar",
"https://www.googleapis.com/auth/chat.spaces.readonly",
"https://www.googleapis.com/auth/chat.messages",
"https://www.googleapis.com/auth/drive.readonly",
"https://www.googleapis.com/auth/gmail.readonly",
"https://www.googleapis.com/auth/gmail.compose",
"https://www.googleapis.com/auth/directory.readonly",
"https://www.googleapis.com/auth/contacts.readonly"
]
# Initialize the flow
flow = InstalledAppFlow.from_client_secrets_file(
CLIENT_SECRET_FILE,
scopes=SCOPES,
redirect_uri='http://localhost:8085/'
)
# Generate Auth URL
auth_url, expected_state = flow.authorization_url(prompt='consent', access_type='offline')
print("Copy this link and paste it into your browser:\\n", auth_url)
redirected_url = input("\\nPaste the full localhost URL here: ").strip()
# Exchange code for tokens
parsed_url = urlparse(redirected_url)
code = parse_qs(parsed_url.query).get('code', [None])[0]
flow.fetch_token(code=code)
# Save ADC
adc_data = {
"client_id": flow.credentials.client_id,
"client_secret": flow.credentials.client_secret,
"refresh_token": flow.credentials.refresh_token,
"type": "authorized_user"
}
adc_path = os.path.expanduser("~/.config/gcloud/application_default_credentials.json")
os.makedirs(os.path.dirname(adc_path), exist_ok=True)
with open(adc_path, "w") as f:
json.dump(adc_data, f, indent=2)
print(f"Success! ADC saved to: {adc_path}")Esegui lo script nel terminale: python3 auth.py
Quando lo esegui, dovrai completare un flusso di autenticazione manuale:
- Lo script stamperà un lungo URL OAuth di Google che inizia con https://accounts.google.com/o/oauth2/auth?...
- Copia tutto l’URL dal terminale e incollalo nel browser.
- Seleziona il tuo account Google Workspace e fai clic su Consenti per autorizzare l’applicazione.
- Il browser ti reindirizzerà poi a una pagina localhost. Nota: è del tutto normale e previsto che il browser mostri un errore “Sito non raggiungibile” per questa pagina.
- Copia l’intero URL dalla barra degli indirizzi del browser (inizierà con http://localhost:8085/?state=...&code=...).
- Incolla l’URL completo nel prompt del terminale dove è scritto Paste the full localhost URL here: e premi Invio.
Lo script scambierà il codice con un token OAuth, lo salverà in ~/.config/gcloud/application_default_credentials.json e genererà un file .env nella directory workspace_agent contenente le impostazioni del tuo progetto Google Cloud.
Il tuo ambiente locale è ora completamente autenticato!
Creare l’agente (agent.py)
Ora crea un file chiamato agent.py.
Poiché i dati di Workspace sono altamente sensibili, i server MCP richiedono che il token di accesso appena generato venga inserito nelle intestazioni HTTP per ogni richiesta.
Dobbiamo anche configurare in modo sicuro l’ambiente ADK.
Passiamo in rassegna il codice:
1. Ambiente e caching del token (TokenRelay)
Per prima cosa carichiamo le Application Default Credentials (ADC) dell’utente generate nel passaggio precedente.
Una parte fondamentale negli agenti enterprise è il caching efficiente dei token. Se eseguiamo il refresh del token a ogni singola esecuzione dello strumento, potremmo raggiungere i limiti delle API o innescare loop di refresh infiniti durante i retry.
La classe TokenRelay memorizza in cache il token in memoria e lo aggiorna solo quando mancano meno di 5 minuti alla scadenza.
import os
import datetime
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
# Enable graceful error handling so timeouts return as tool outputs
os.environ["ADK_ENABLE_MCP_GRACEFUL_ERROR_HANDLING"] = "1"
# Inject User ADC path globally
_adc_path = os.path.expanduser("~/.config/gcloud/application_default_credentials.json")
if not os.path.exists(_adc_path):
raise FileNotFoundError("Please run 'python3 auth.py' first to generate credentials.")
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = _adc_path
creds, _ = google.auth.default()
class TokenRelay:
"""Manages in-memory caching of Google OAuth access tokens."""
def __init__(self, credentials):
self._creds = credentials
self._cached_token = None
self._expiry = None
def get_token(self) -> str:
now = datetime.datetime.now()
if (self._cached_token is None or self._expiry is None
or now >= (self._expiry - datetime.timedelta(minutes=5))):
self._creds.refresh(Request())
self._cached_token = self._creds.token
self._expiry = now + datetime.timedelta(minutes=50)
return self._cached_token or ""
token_relay = TokenRelay(creds)
token_relay.get_token()
def auth_header_provider(tool_context=None) -> dict[str, str]:
return {"Authorization": f"Bearer {token_relay.get_token()}"}
2. Configurare i toolset MCP
Con il nostro cache del token pronto, configuriamo 5 connessioni MCP. Usiamo StreamableHTTPConnectionParams per connetterci agli endpoint SSE (Server-Sent Events).
Ciò che rende così potente il McpToolset è che interroga dinamicamente l’endpoint remoto. Recupera automaticamente gli strumenti disponibili e gli schemi JSON. Non devi codificarli a mano!
# Initialize the 5 GWS MCP servers with dynamic runtime provider
calendar_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://calendarmcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
chat_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://chatmcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
drive_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://drivemcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://gmailmcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
people_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://people.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)3. Inizializzare l’agente
Infine, istanziamo il nostro LlmAgent. Usiamo il modello gemini-2.5-flash, inseriamo dinamicamente la data corrente nel prompt di sistema così che l’LLM comprenda il tempo relativo ("questa settimana", "oggi") e gli passiamo i 5 toolset.
current_date = datetime.datetime.now().strftime("%Y-%m-%d")
root_agent = LlmAgent(
model="gemini-2.5-flash",
name='gws_adk_agent',
instruction=f"""You are a helpful assistant grounded in the user's Google Workspace data.
Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
Use the provided MCP tools to answer questions about their Calendar, Chat, Drive, Gmail, and Contacts.
If a tool returns an error indicating a timeout, inform the user that the service took too long to respond.""",
tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)Esecuzione con ADK Web
Invece di scrivere un loop Python personalizzato, possiamo testare ed eseguire subito questo agente usando l’interfaccia integrata ADK Web. Dal terminale, avvia il server web:
adk web Questo avvia un server di sviluppo locale. Vai su http://localhost:8080 nel browser.
Vedrai il tuo agente caricato e pronto.
Da questa UI puoi chattare nativamente con l’agente e osservarlo passare senza soluzione di continuità tra Gmail, Calendar e Drive per soddisfare le tue richieste!
Testare l’agente nel mondo reale
Ora che l’agente è in esecuzione, prova a porgli domande complesse e trasversali che normalmente richiederebbero di aprire tre schede diverse.
Per esempio:
Prompt 1: Controlla il mio calendario per domani e riassumi gli argomenti delle riunioni. Ci sono documenti rilevanti nel mio Drive per queste riunioni?
Cosa succede sotto il cofano:
- L’agente capisce che prima gli servono i dati del calendario, quindi esegue lo strumento list_events, calcolando dinamicamente la data di domani in base al prompt di sistema.
- Analizza la risposta JSON per trovare i titoli delle riunioni.
- Riconoscendo che servono documenti correlati, estrae parole chiave dai titoli delle riunioni e le passa senza soluzione di continuità a una seconda chiamata allo strumento: search_files.
- Infine, sintetizza gli output dei server MCP di Calendar e Drive in un unico briefing altamente leggibile.
Invece di scrivere wrapper API personalizzati e logica di integrazione, hai semplicemente posto una domanda e l’LLM ha capito come orchestrare i passaggi multipli.
Prompt 2: Trova tutte le email inviate da [Inserisci Email] negli ultimi 7 giorni.
Cosa succede sotto il cofano:
- L’agente interpreta la tua richiesta in linguaggio naturale e la traduce automaticamente nella sintassi di query esatta richiesta dalla Gmail API.
- Chiama lo strumento search_threads, passando la stringa di query generata dinamicamente.
- Recupera i thread recenti, estrae i metadati rilevanti e ti presenta gli oggetti e le date in formato ordinato.
Altri prompt da provare
Le possibilità sono infinite quando colleghi tutti i tuoi dati aziendali a un motore di ragionamento.
Prova alcuni di questi prompt nel tuo ambiente locale:
- "Trova l’ultima email che ho ricevuto dal mio responsabile. Mi ha chiesto di fare qualcosa?"
- "Trova il deck di slide di avvio progetto nel mio Drive, leggi i contenuti e dimmi quali sono gli obiettivi del Q3."
- "Ci sono conflitti di pianificazione nel mio calendario per la prossima settimana?"
E adesso? Sbloccare l’automazione enterprise
Combinando l’Agent Development Kit di Google con i server MCP standardizzati di Workspace, hai appena creato un assistente di livello enterprise in meno di cento righe di codice.
Ma questo è solo l’inizio.
Ecco cosa apre questa architettura per sviluppatori e aziende:
- Sistemi multi-agente: invece di un unico agente monolitico, puoi usare l’ADK per costruire una flotta di sotto-agenti specializzati. Un agente gestisce nello specifico il tuo calendario e risolve i conflitti di pianificazione, mentre un altro monitora rigorosamente una casella di posta condivisa del team e categorizza le richieste in arrivo.
- Strumenti enterprise personalizzati: poiché MCP è uno standard, non sei limitato a Workspace. Puoi aggiungere facilmente altri strumenti MCP al tuo agente, come un server MCP Postgres per interrogare il database vendite della tua azienda o un server MCP Jira per creare automaticamente ticket in base ai messaggi su Chat.
- Workflow automatizzati: puoi portare questo agente fuori dall’interfaccia ADK Web e distribuirlo in headless. Immagina un job CRON pianificato che sveglia l’agente ogni mattina alle 8, analizza casella di posta e calendario e ti invia un briefing riassuntivo su Google Chat.
Conclusione
Il server MCP di Google Workspace elimina il “collante” di codice necessario per collegare l’AI alle app di produttività aziendale. Fornendo un endpoint remoto sicuro e completamente gestito, permette agli sviluppatori di creare workflow agentici profondamente integrati che rispettano le autorizzazioni utente e gli standard di sicurezza aziendale out of the box.
Promemoria di best practice: applica sempre il principio del privilegio minimo.
Quando assegni gli scope OAuth ai tuoi agenti AI, non concedere mai accesso in scrittura (ad esempio https://www.googleapis.com/auth/drive.file) se l’agente ha solo bisogno di leggere i dati.
Pronto a costruire?
Continua il tuo percorso di apprendimento con i nostri corsi guidati su DataCamp:
