Curso
Introduction to Google Workspace with Gemini
30 min
2.6K
Los agentes de IA son potentísimos, pero a menudo tienen un fallo de base: están desconectados de donde sucede nuestro trabajo diario —el correo, el calendario y los documentos. Sin acceso a tus datos en vivo, un LLM no pasa de ser un generador de ideas muy elocuente.
En este tutorial, te enseño a cerrar la brecha entre los modelos de IA y tus datos corporativos configurando el servidor MCP de Google Workspace, entendiendo los últimos controles de seguridad y creando un asistente automatizado.
Al final, serás capaz de:
- Entender la arquitectura del Model Context Protocol (MCP) aplicado a Google Workspace.
- Configurar los controles de OAuth y el acceso a las API necesarios en Google Cloud.
- Probar la conectividad con Gemini CLI y Google Antigravity.
- Crear un asistente de IA para empresas en Python con Google ADK que lea correos, consulte tu calendario y redacte documentos en un único bucle de razonamiento.
Requisitos previos
- Un proyecto de Google Cloud con la facturación activada.
- Conocimientos básicos de Python y APIs REST.
- Una cuenta de Google Workspace.
¿Qué es el servidor MCP de Google Workspace?
El servidor MCP de Google Workspace es una implementación estandarizada del Model Context Protocol (MCP) que permite que cualquier cliente de IA compatible (como Claude Desktop, Gemini CLI o agentes personalizados) interactúe de forma segura con las apps de Google Workspace.
En lugar de que los desarrolladores creen envoltorios REST a medida para Gmail, Google Docs, Drive y Calendar en cada proyecto de IA, el servidor MCP expone estas capacidades como "herramientas" estandarizadas que el LLM entiende de forma nativa.
Te recomiendo echar un vistazo al curso Introduction to Model Context Protocol (MCP) para practicar con él.
Normalmente, crear flujos entre apps implica escribir integraciones frágiles. Con MCP, solo entregas las herramientas al LLM. El agente puede leer un hilo de correo, detectar un conflicto de agenda comprobando tu calendario y redactar un resumen en Google Docs por su cuenta.
Seguridad y controles de administración en Workspace
Al dar a los modelos de IA acceso al correo y a los archivos corporativos, la seguridad de los datos es el mayor obstáculo para su adopción empresarial.
El servidor MCP de Workspace se diseñó desde cero para abordar este problema.
Gestiona la autenticación basándose por completo en OAuth 2.0 y un IAM estricto de Google Cloud.
No hay "llaves maestras" genéricas. El agente solo actúa en nombre del usuario autenticado explícitamente, respetando estrictamente todos los permisos de uso compartido de Google Workspace y las ACL de los documentos.
Además, introduce sólidos controles de administración.
Las personas administradoras de Workspace pueden incluir en una lista de permitidos herramientas MCP específicas, monitorizar el uso de API en toda la organización y aplicar reglas de prevención de pérdida de datos (DLP) para evitar que los agentes filtren por accidente documentos sensibles de Drive o correos a dominios externos no autorizados.
Configurar el acceso al servidor MCP de Workspace
Antes de escribir código, aquí "configuración" significa preparar los permisos de Google Cloud para acceder al servidor remoto.
Configurar el proyecto de Google Cloud
Primero, debes activar tanto las APIs estándar de Workspace como los servicios MCP dedicados en tu proyecto de Google Cloud.
- Ve a Google Cloud Console.
- Activa las APIs de Workspace necesarias: Gmail API, Google Drive API, Google Docs API y Google Calendar API.
- Activa los servicios MCP: gmailmcp.googleapis.com, drivemcp.googleapis.com y calendarmcp.googleapis.com.
- Ve a APIs & Services > OAuth consent screen. Configura la pantalla de consentimiento para audiencia interna. En Data Access > Add or Remove Scopes, añade manualmente los siguientes ámbitos (scopes) para los servidores que vayas a usar:
- 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
Generar credenciales de usuario
Como los datos de Workspace son específicos de cada usuario, el endpoint MCP remoto exige una cabecera Authorization: Bearer <TOKEN> que represente al usuario humano.
Ve a APIs & Services > Credentials y crea un OAuth 2.0 Client ID (tipo Desktop Application).
Descarga el archivo JSON de credenciales. Lo usarás para obtener el token de acceso OAuth 2.0 mediante un flujo de inicio de sesión en el navegador.
Haz clic en Create y copia el Client ID y el Client Secret. Los necesitarás en el siguiente paso.
Probar la conexión (Gemini CLI y Antigravity)
Antes de escribir código complejo para el agente en Python, es muy recomendable hacer una prueba "Hello World" para validar tus credenciales y asegurarte de que los endpoints MCP remotos son accesibles.
Probar la conexión en un entorno simplificado ayuda a aislar problemas de autenticación de la lógica de tu aplicación.
Aunque se puede probar con Gemini CLI y con la interfaz Google Antigravity, ahora nos centraremos en Gemini CLI.
Conectar con Gemini CLI
La forma más rápida de probar la conectividad es usando Gemini CLI.
Como Workspace exige autenticación estricta, debes configurar el endpoint y tus credenciales OAuth en tu archivo ~/.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"
]
}
}
}
}
Cuando actualices el archivo de configuración, lanza Gemini CLI y ejecuta el comando /mcp list.
Verás tus servidores de Workspace recién configurados como "Ready", pero con el aviso "(OAuth not authenticated)".
Esto confirma que la CLI ha leído correctamente tu configuración y reconoce las herramientas remotas.
Ejecutar pruebas básicas de Workspace
Ahora que los servidores se reconocen, debes autenticarte antes de usarlos. Empieza ejecutando el comando de autenticación para tu endpoint de Gmail:
/mcp auth gmailEsto iniciará un flujo OAuth 2.0 basado en el navegador.
La CLI intentará abrir automáticamente tu navegador predeterminado, solicitándote iniciar sesión con tu cuenta de Google Workspace y conceder los permisos requeridos.
Si el navegador no se abre automáticamente, la CLI te dará una URL segura para copiar y pegar. Una vez completes el inicio de sesión, la CLI confirmará la autenticación correcta y recargará las herramientas de ese servidor.
Con la autenticación completa, ya puedes probar la conexión con un prompt en lenguaje natural:
my email for any messages containing the word 'Invoice'.La CLI ejecutará la herramienta en segundo plano, recuperará los datos de tu bandeja de entrada y el agente los presentará en una respuesta útil:
Proyecto demo: crear un agente de Workspace con Google ADK
Vamos a crear un agente de Workspace que conecte con cinco servicios (Calendar, Chat, Drive, Gmail, People) y gestione la autenticación de forma segura.
Generar Application Default Credentials (auth.py)
Antes de ejecutar el agente, necesita un token OAuth para pasarlo a los endpoints MCP.
Gemini CLI lo maneja automáticamente con /mcp auth, pero para una aplicación en Python debemos generar nuestro propio token y guardarlo como Application Default Credentials (ADC).
Crea un archivo llamado auth.py en la raíz del proyecto. Asegúrate de tener tu client_secret.json descargado en el mismo directorio.
Este script usa la librería oficial google-auth-oauthlib para generar una URL de autenticación, canjear el código por un token de actualización y escribirlo en la ruta estándar ~/.config/gcloud/application_default_credentials.json, donde el ADK puede encontrarlo.
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}")Ejecuta el script en tu terminal: python3 auth.py
Al ejecutarlo, tendrás que completar un flujo de autenticación manual:
- El script imprimirá una URL larga de OAuth de Google que empieza por https://accounts.google.com/o/oauth2/auth?...
- Copia la URL completa desde tu terminal y pégala en tu navegador.
- Selecciona tu cuenta de Google Workspace y haz clic en Allow para autorizar la aplicación.
- El navegador te redirigirá a una página de localhost. Nota: es totalmente normal que el navegador muestre un error tipo "Site can't be reached" en esa página.
- Copia la URL completa de la barra de direcciones (empezará por http://localhost:8085/?state=...&code=...).
- Pega esa URL completa en el prompt de la terminal donde dice Paste the full localhost URL here: y pulsa Enter.
El script canjeará el código por un token OAuth, lo guardará en ~/.config/gcloud/application_default_credentials.json y generará un archivo .env en tu directorio workspace_agent con la configuración de tu proyecto de Google Cloud.
¡Tu entorno local ya está autenticado!
Crear el agente (agent.py)
Ahora crea un archivo llamado agent.py.
Dado que los datos de Workspace son muy sensibles, los servidores MCP exigen inyectar el token de acceso que acabamos de generar en las cabeceras HTTP de cada petición.
También necesitamos configurar el entorno del ADK de forma segura.
Vamos a desglosar el código:
1. Entorno y caché de tokens (TokenRelay)
Primero cargamos las Application Default Credentials (ADC) generadas en el paso anterior.
Un aspecto clave en agentes empresariales es cachear tokens de forma eficiente. Si los refrescamos en cada ejecución de herramienta, podríamos topar con límites de API o provocar bucles de refresco durante reintentos.
TokenRelay mantiene el token en memoria y solo lo refresca cuando faltan menos de 5 minutos para que caduque.
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. Configurar los conjuntos de herramientas MCP
Con la caché de tokens lista, configuramos 5 conexiones MCP. Usamos StreamableHTTPConnectionParams para conectarnos a endpoints de Server-Sent Events (SSE).
Lo potente de McpToolset es que interroga dinámicamente al endpoint remoto: obtiene automáticamente las herramientas disponibles y los esquemas JSON. ¡No tienes que codificarlos 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. Inicializar el agente
Por último, instanciamos nuestro LlmAgent. Usamos el modelo gemini-2.5-flash, inyectamos dinámicamente la fecha actual en el prompt del sistema para que el LLM entienda el tiempo relativo ("esta semana", "hoy") y le pasamos los 5 conjuntos de herramientas.
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]
)Ejecutar con ADK Web
En lugar de escribir un bucle en Python a medida, podemos probar y ejecutar este agente al instante con la interfaz integrada de ADK Web. Desde la terminal, lanza el servidor web:
adk web Esto inicia un servidor local de desarrollo. En tu navegador, ve a http://localhost:8080.
Verás tu agente cargado y listo.
Desde esta interfaz, puedes chatear con el agente y verlo saltar sin esfuerzo entre Gmail, Calendar y Drive para cumplir tus peticiones.
Probar el agente en el mundo real
Ahora que el agente está en marcha, prueba a hacerle preguntas complejas y transversales que normalmente te obligarían a abrir tres pestañas.
Por ejemplo:
Prompt 1: Revisa mi calendario de mañana y resume los temas de mis reuniones. ¿Hay documentos relevantes en mi Drive para ellas?
Qué ocurre por debajo:
- El agente entiende que primero necesita datos del calendario, así que ejecuta la herramienta list_events, calculando dinámicamente la fecha de mañana a partir del prompt del sistema.
- Analiza la respuesta JSON para encontrar los títulos de las reuniones.
- Al ver que necesita documentos relacionados, extrae palabras clave de esos títulos y las pasa sin fricción a una segunda llamada de herramienta: search_files.
- Por último, sintetiza las salidas de los servidores MCP de Calendar y Drive en un único briefing muy legible.
En lugar de escribir envoltorios de API y lógica de integración, tú solo hiciste una pregunta y el LLM resolvió la orquestación multietapa.
Prompt 2: Encuentra todos los correos enviados por [Insert Email] en los últimos 7 días.
Qué ocurre por debajo:
- El agente toma tu petición en lenguaje natural y la traduce automáticamente a la sintaxis exacta de consulta que exige la API de Gmail.
- Llama a la herramienta search_threads pasando la cadena de consulta generada dinámicamente.
- Recupera los hilos recientes, extrae los metadatos relevantes y te presenta los asuntos y fechas bien formateados.
Otros prompts que puedes probar
Las posibilidades se multiplican cuando conectas todos tus datos corporativos a un motor de razonamiento.
Prueba estos prompts en tu entorno local:
- "Encuentra el último correo que recibí de mi manager. ¿Me pidió hacer algo?"
- "Busca en mi Drive la presentación de arranque del proyecto, lee el contenido y dime cuáles son los objetivos de Q3."
- "¿Hay conflictos de agenda en mi calendario para la semana que viene?"
¿Y ahora qué? Automatización empresarial a tu alcance
Al combinar el Agent Development Kit de Google con los servidores MCP estandarizados de Workspace, acabas de crear un asistente de nivel empresarial en menos de cien líneas de código.
Pero esto es solo el principio.
Esta arquitectura abre la puerta a desarrolladores y empresas a:
- Sistemas multiagente: en lugar de un agente monolítico, puedes usar ADK para crear una flota de subagentes especializados. Uno gestiona tu calendario y resuelve conflictos; otro monitoriza una bandeja compartida del equipo y categoriza solicitudes entrantes.
- Herramientas empresariales personalizadas: como MCP es un estándar, no te limitas a Workspace. Puedes añadir fácilmente más herramientas MCP a tu agente —por ejemplo, un servidor MCP de Postgres para consultar tu base de datos de ventas, o un servidor MCP de Jira para crear tickets automáticamente a partir de mensajes de Chat.
- Flujos automatizados: puedes sacar este agente de la UI de ADK Web y desplegarlo sin interfaz. Imagina un CRON diario que despierta a tu agente a las 8:00, analiza tu bandeja y calendario y te envía un briefing resumido por Google Chat.
Conclusión
El servidor MCP de Google Workspace elimina el "código pegamento" necesario para conectar la IA con las apps de productividad empresarial. Al ofrecer un endpoint remoto seguro y totalmente gestionado, permite a los desarrolladores crear flujos agentivos profundamente integrados que respetan los permisos del usuario y los estándares de seguridad empresarial desde el primer momento.
Recordatorio de buenas prácticas: aplica siempre el principio de mínimo privilegio.
Al asignar ámbitos de OAuth a tus agentes de IA, no concedas acceso de escritura (p. ej., https://www.googleapis.com/auth/drive.file) si el agente solo necesita leer datos.
¿Listo para construir?
Sigue aprendiendo con nuestros cursos guiados de DataCamp:
