Ein Entwicklerleitfaden zu Google Workspace MCP-Servern und dem Agent Development Kit

KI-Agenten sind extrem leistungsfähig, leiden aber oft an einem grundlegenden Problem: Sie sind nicht dort angebunden, wo unsere tägliche Arbeit wirklich stattfindet – in E-Mails, Kalendern und Dokumenten. Ohne Zugriff auf deine Live-Daten ist ein LLM nur ein sehr wortgewandter Ideengeber.

In diesem Tutorial zeige ich dir, wie du die Lücke zwischen KI-Modellen und deinen Unternehmensdaten schließt: durch das Konfigurieren des Google Workspace MCP-Servers, das Verständnis der neuesten Sicherheitskontrollen und den Aufbau eines automatisierten Assistenten.

Am Ende wirst du Folgendes können: 

• Die Architektur des Model Context Protocol (MCP) im Kontext von Google Workspace verstehen.
• Die notwendigen OAuth-Kontrollen und den API-Zugriff in Google Cloud konfigurieren.
• Die Konnektivität mit der Gemini CLI und Google Antigravity testen.
• Einen Enterprise-KI-Assistenten in Python mit dem Google ADK bauen, der E-Mails liest, deinen Kalender prüft und Dokumente in einer einzigen Reasoning-Schleife entwirft.

Voraussetzungen

• Ein Google-Cloud-Projekt mit aktivierter Abrechnung.
• Grundkenntnisse in Python und REST-APIs.
• Ein Google Workspace-Konto.

Was ist der Google Workspace MCP-Server?

Der Google Workspace MCP-Server ist eine standardisierte Implementierung des Model Context Protocol (MCP), die es jedem kompatiblen KI-Client (wie Claude Desktop, Gemini CLI oder eigenen Agenten) ermöglicht, sicher mit Google-Workspace-Apps zu interagieren.

Anstatt für jedes neue KI-Projekt eigene REST-API-Wrapper für Gmail, Google Docs, Drive und Calendar zu schreiben, stellt der MCP-Server diese Fähigkeiten als standardisierte „Tools“ bereit, die das LLM nativ versteht.

Ich empfehle dir den Kurs „Introduction to Model Context Protocol (MCP)“, um erste praktische Erfahrungen zu sammeln. 

Normalerweise bedeutet ein App-übergreifender Workflow brüchigen Integrationscode zu schreiben. Mit MCP übergibst du dem LLM einfach die Tools. Der Agent kann selbstständig einen E-Mail-Thread lesen, über den Kalender einen Terminkonflikt erkennen und in Google Docs eine Zusammenfassung entwerfen.

Sicherheit und Admin-Kontrollen in Workspace

Wenn KI-Modelle Zugriff auf Unternehmensmails und -dateien erhalten, ist Datensicherheit die größte Hürde für die Akzeptanz. 

Der Workspace MCP-Server wurde von Grund auf entwickelt, um genau dieses Thema zu adressieren.

Er übernimmt die Authentifizierung vollständig über OAuth 2.0 und striktes Google Cloud IAM. 

Es gibt keine generischen „Master-Keys“. Der Agent handelt ausschließlich im Namen des ausdrücklich authentifizierten Nutzers und respektiert strikt alle bestehenden Google-Workspace-Freigaben und Dokument-ACLs.

Darüber hinaus gibt es robuste Admin-Kontrollen. 

Workspace-Administratoren können bestimmte MCP-Tools auf eine Allowlist setzen, die API-Nutzung in der gesamten Organisation überwachen und Data-Loss-Prevention-(DLP)-Regeln durchsetzen, damit Agenten nicht versehentlich sensible Drive-Dokumente oder E-Mails an unbefugte externe Domains weitergeben.

Zugriff auf den Workspace MCP-Server konfigurieren

Bevor du Code schreibst, bedeutet „Konfiguration“ hier: Google-Cloud-Berechtigungen einrichten, um auf den Remote-Server zuzugreifen.

Google-Cloud-Projekt einrichten

Zuerst musst du sowohl die Standard-Workspace-APIs als auch die dedizierten MCP-Services in deinem Google-Cloud-Projekt aktivieren.

1. Zur Google Cloud Console navigieren.
2. Die benötigten Workspace-APIs aktivieren: Gmail API, Google Drive API, Google Docs API und Google Calendar API.
3. Die MCP-Services aktivieren: gmailmcp.googleapis.com, drivemcp.googleapis.com und calendarmcp.googleapis.com.
4. Zu APIs & Services > OAuth-Zustimmungsbildschirm gehen. Richte den Zustimmungsbildschirm für ein internes Publikum ein. Unter Data Access > Add or Remove Scopes die folgenden Scopes für die gewünschten Server manuell hinzufügen:
• 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

Nutzeranmeldedaten erstellen

Da Workspace-Daten nutzerspezifisch sind, verlangt der Remote-MCP-Endpunkt einen Authorization: Bearer <TOKEN>-Header, der die Person repräsentiert. 

Gehe zu APIs & Services > Credentials und erstelle eine OAuth 2.0-Client-ID (Typ Desktop Application). 

Lade die JSON-Anmeldedatei herunter. Sie wird verwendet, um über einen Browser-Loginflow das notwendige OAuth-2.0-Zugriffstoken zu erhalten. 

Klicke auf Create und kopiere Client ID und Client Secret. Du brauchst sie im nächsten Schritt.

Verbindung testen (Gemini CLI und Antigravity)

Bevor du komplexen Python-Agenten-Code schreibst, empfiehlt sich ein „Hello World“-Test, um deine Anmeldedaten zu prüfen und sicherzugehen, dass die Remote-MCP-Endpunkte erreichbar sind. 

Das Testen der Verbindung in einer einfachen Umgebung hilft, Authentifizierungsprobleme von deiner Anwendungslogik zu trennen. 

Wir könnten die Verbindung sowohl mit der Gemini CLI als auch mit der Google-Antigravity-UI testen, konzentrieren uns hier aber auf die Gemini CLI.

Verbindung über die Gemini CLI

Am schnellsten testest du die Konnektivität mit der Gemini CLI. 

Da Workspace strikte Authentifizierung verlangt, konfigurierst du den Endpunkt und deine OAuth-Anmeldedaten in deiner ~/.gemini/settings.json-Datei:

{
  "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"
        ]
      }
    }
  }
}

Sobald die Einstellungsdatei aktualisiert ist, kannst du die Gemini CLI starten und den Befehl /mcp list ausführen. 

Du siehst deine neu konfigurierten Workspace-Server als „Ready“, aber mit dem Hinweis „(OAuth not authenticated)“. 

Das bestätigt, dass die CLI deine Konfiguration erfolgreich gelesen hat und die Remote-Tools kennt. 

Grundlegende Workspace-Tests ausführen

Jetzt, da die Server erkannt wurden, musst du dich authentifizieren, bevor du sie verwenden kannst. Starte mit dem Authentifizierungsbefehl für deinen Gmail-Endpunkt:

/mcp auth gmail

Dadurch wird ein browserbasierter OAuth-2.0-Flow gestartet. 

Die CLI versucht automatisch, deinen Standardbrowser zu öffnen, damit du dich mit deinem Google-Workspace-Konto anmeldest und die angeforderten Berechtigungen gewährst. 

Wenn sich der Browser nicht automatisch öffnet, gibt dir die CLI eine sichere URL aus, die du manuell kopieren und einfügen kannst. Nach Abschluss der Anmeldung bestätigt die CLI die erfolgreiche Authentifizierung und lädt die Tools für diesen Server neu.

Nach der Authentifizierung kannst du die Verbindung mit einer natürlichsprachlichen Eingabe testen:

my email for any messages containing the word 'Invoice'.

Die CLI führt das Tool im Hintergrund aus, ruft die Daten aus deinem Posteingang ab und der Agent formatiert sie zu einer hilfreichen Antwort:

Demo-Projekt: Einen Workspace-Agenten mit dem Google ADK bauen

Lass uns einen Workspace-Agenten bauen, der sich mit allen fünf Services (Calendar, Chat, Drive, Gmail, People) verbindet und die Authentifizierung sicher handhabt.

Application Default Credentials erzeugen (auth.py)

Bevor der Agent laufen kann, braucht er ein OAuth-Token, das an die MCP-Endpunkte übergeben wird. 

Die Gemini CLI übernimmt das automatisch mit /mcp auth, aber für eine Python-Anwendung müssen wir unser eigenes Token erzeugen und als Application Default Credentials (ADC) speichern.

Erstelle im Projektroot eine Datei namens auth.py. Stelle sicher, dass sich deine heruntergeladene client_secret.json im selben Verzeichnis befindet. 

Dieses Skript nutzt die offizielle google-auth-oauthlib, um eine Authentifizierungs-URL zu generieren, den Code gegen ein Refresh-Token zu tauschen und es im Standardpfad ~/.config/gcloud/application_default_credentials.json zu speichern, wo das ADK es findet.

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}")

Führe das Skript im Terminal aus: python3 auth.py

Bei der Ausführung musst du einen manuellen Authentifizierungsflow durchlaufen:

1. Das Skript gibt eine lange Google-OAuth-URL aus, beginnend mit https://accounts.google.com/o/oauth2/auth?...
2. Kopiere die gesamte URL aus dem Terminal und füge sie in deinen Browser ein.
3. Wähle dein Google-Workspace-Konto und klicke auf Allow, um die Anwendung zu autorisieren.
4. Dein Browser leitet dich anschließend auf eine localhost-Seite um. Hinweis: Es ist völlig normal, wenn dein Browser hier einen „Site can't be reached“-Fehler anzeigt.
5. Kopiere die vollständige URL aus der Adresszeile (sie beginnt mit http://localhost:8085/?state=...&code=...).
6. Füge diese vollständige URL im Terminal an der Eingabeaufforderung „Paste the full localhost URL here:“ ein und drücke Enter.

Das Skript tauscht den Code gegen ein OAuth-Token, speichert es unter ~/.config/gcloud/application_default_credentials.json und erzeugt eine .env-Datei in deinem workspace_agent-Verzeichnis mit deinen Google-Cloud-Projekteinstellungen. 

Deine lokale Umgebung ist jetzt vollständig authentifiziert!

Den Agenten bauen (agent.py)

Erstelle nun eine Datei namens agent.py. 

Da Workspace-Daten sehr sensibel sind, verlangen die MCP-Server, dass das soeben erzeugte Zugriffstoken in jeden HTTP-Request-Header injiziert wird. 

Außerdem müssen wir die ADK-Umgebung sicher konfigurieren.

So setzt sich der Code zusammen:

1. Umgebung und Token-Caching (TokenRelay)

Zunächst laden wir die in Schritt zuvor erzeugten Application Default Credentials (ADC) des Nutzers. 

Ein kritischer Teil von Enterprise-Agenten ist effizientes Token-Caching. Wenn wir bei jeder Toolausführung ein Refresh durchführen, könnten wir auf API-Limits stoßen oder bei Retries Endlosschleifen auslösen. 

TokenRelay cached das Token im Speicher und erneuert es nur, wenn es in weniger als 5 Minuten abläuft.

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. Die MCP-Toolsets konfigurieren

Mit dem bereitstehenden Token-Cache konfigurieren wir unsere 5 MCP-Verbindungen. Wir verwenden StreamableHTTPConnectionParams für die Verbindung zu Server-Sent-Events-(SSE)-Endpunkten.

Die Stärke des McpToolset liegt darin, den Remote-Endpunkt dynamisch zu interrogieren. Es lädt automatisch verfügbare Tools und JSON-Schemas. Du musst nichts davon hardcoden!

# 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. Den Agenten initialisieren

Zum Schluss instanziieren wir unseren LlmAgent. Wir verwenden das gemini-2.5-flash-Modell, injizieren dynamisch das aktuelle Datum in den Systemprompt, damit das LLM relative Zeiten („diese Woche“, „heute“) versteht, und übergeben die 5 Toolsets.

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]
)

Ausführung mit ADK Web

Anstatt eine eigene Python-Schleife zu schreiben, können wir den Agenten sofort mit der integrierten ADK-Weboberfläche testen und ausführen. Starte den Webserver aus dem Terminal: 

adk web 

Damit startest du einen lokalen Entwicklungsserver. Öffne http://localhost:8080 im Browser. 

Du siehst deinen Agenten geladen und einsatzbereit. 

In dieser UI kannst du nativ mit dem Agenten chatten und beobachten, wie er nahtlos zwischen Gmail, Calendar und Drive wechselt, um deine Anfragen zu erfüllen!

Den Agenten in der Praxis testen

Jetzt, wo der Agent läuft, stelle ihm komplexe, funktionsübergreifende Fragen, für die du sonst drei Tabs öffnen müsstest. 

Zum Beispiel:

Prompt 1: Prüfe meinen Kalender für morgen und fasse die Themen meiner Meetings zusammen. Gibt es dafür relevante Dokumente in meinem Drive?

Hinter den Kulissen passiert Folgendes:

1. Der Agent versteht, dass er zuerst Kalenderdaten braucht, und führt das Tool list_events aus, wobei er das morgige Datum aus dem Systemprompt ableitet.
2. Er parst die JSON-Antwort, um die Meetingtitel zu finden.
3. Er erkennt den Bedarf an zugehörigen Dokumenten, extrahiert Schlüsselwörter aus den Meetingtiteln und übergibt sie nahtlos an einen zweiten Toolaufruf: search_files.
4. Abschließend verdichtet er die Ergebnisse aus den Calendar- und Drive-MCP-Servern zu einem einzigen, gut lesbaren Briefing.

Anstatt eigene API-Wrapper und Integrationslogik zu schreiben, hast du einfach eine Frage gestellt – das LLM orchestriert die mehrstufige Ausführung selbst.

Prompt 2: Finde alle E-Mails der letzten 7 Tage, die von [E-Mail einfügen] gesendet wurden.

Hinter den Kulissen passiert Folgendes:

1. Der Agent übersetzt deine natürlichsprachliche Anfrage automatisch in die exakte Abfragesyntax der Gmail API.
2. Er ruft das Tool search_threads auf und übergibt den dynamisch erzeugten Query-String.
3. Er holt die jüngsten Threads, extrahiert relevante Metadaten und präsentiert Betreffzeilen und Daten übersichtlich formatiert.

Weitere Prompts zum Ausprobieren

Die Möglichkeiten sind nahezu unbegrenzt, wenn deine Unternehmensdaten mit einer Reasoning-Engine verbunden sind. 

Probiere in deiner lokalen Umgebung auch diese Prompts aus:

• „Finde die letzte E-Mail, die ich von meiner Führungskraft erhalten habe. Haben sie mich um etwas gebeten?“
• „Finde das Projekt-Kickoff-Deck in meinem Drive, lies den Inhalt und sag mir, welche Ziele für Q3 gesetzt sind.“
• „Gibt es Terminkonflikte in meinem Kalender für nächste Woche?“

Wie geht es weiter? Enterprise-Automatisierung freischalten

Durch die Kombination von Googles Agent Development Kit mit den standardisierten Workspace-MCP-Servern hast du in unter hundert Zeilen Code einen Assistenten in Enterprise-Qualität gebaut. 

Doch das ist nur der Anfang.

Diese Architektur eröffnet Entwicklerinnen, Entwicklern und Unternehmen unter anderem Folgendes:

1. Multi-Agent-Systeme: Statt eines riesigen Agenten kannst du mit dem ADK eine Flotte spezialisierter Sub-Agenten bauen. Einer managt gezielt deinen Kalender und löst Terminkonflikte, ein anderer überwacht streng einen gemeinsamen Teameingang und kategorisiert eingehende Anfragen.

2. Individuelle Enterprise-Tools: Da MCP ein Standard ist, bist du nicht auf Workspace beschränkt. Du kannst deinem Agenten leicht zusätzliche MCP-Tools hinzufügen – etwa einen Postgres-MCP-Server, um die Vertriebsdatenbank deines Unternehmens abzufragen, oder einen Jira-MCP-Server, der automatisch Tickets aus Chat-Nachrichten erstellt.

3. Automatisierte Workflows: Du kannst diesen Agenten aus der ADK-Weboberfläche herauslösen und headless deployen. Denk an einen geplanten CRON-Job, der deinen Agenten jeden Morgen um 8 Uhr weckt, Posteingang und Kalender analysiert und dir eine Zusammenfassung per Google Chat schickt.

Fazit

Der Google Workspace MCP-Server eliminiert den nötigen „Klebecode“, um KI mit Produktivitäts-Apps im Unternehmen zu verbinden. Als sicherer, vollständig verwalteter Remote-Endpunkt ermöglicht er es Entwicklern, tief integrierte agentische Workflows zu bauen, die Nutzerrechte und Unternehmensstandards out of the box respektieren.

Best Practice: Immer nach dem Prinzip der minimalen Rechte arbeiten. 

Wenn du OAuth-Scopes für deine KI-Agenten vergibst, erteile niemals Schreibrechte (z. B. https://www.googleapis.com/auth/drive.file), wenn der Agent nur Lesezugriff braucht.

Bereit zum Bauen?

Setze deine Lernreise mit unseren geführten DataCamp-Kursen fort:

• Building AI Agents with Google ADK
• Introduction to GCP