Google Classroom MCP — Next.js + Google OAuth

Ein Remote-, Read-only-Google-Classroom-MCP für ChatGPT/Agent-Clients. Es ersetzt eine lokale stdio- + tokens.json-Architektur durch zustandslose Next.js-App-Router-Route-Handler, OAuth-Discovery, einen interaktiven Google-Anmeldeablauf, informationsreiche Classroom-Tools und Textextraktion aus Drive-Anhängen.

Was diese Implementierung tut

• Führt /mcp als Web-Standard-MCP-Endpunkt auf der Standard-Node.js-Laufzeit von Next.js aus.

• Verwendet die aktuelle @modelcontextprotocol/server-v2-API anstelle des monolithischen v1-SDKs.

• Implementiert OAuth Protected Resource Metadata und OAuth Authorization Server Metadata.

• Unterstützt sowohl OAuth-Client-ID-Metadaten-Dokumente (CIMD) als auch Dynamic Client Registration (DCR) für Client-Kompatibilität.

• Leitet den Benutzer innerhalb des MCP-Verbindungsablaufs durch Google OAuth. Es gibt keinen lokalen auth-CLI-Befehl und keine tokens.json.

• Hält die Bereitstellung zustandslos: Autorisierungsstatus, kurzlebige Autorisierungscodes, MCP-Zugriffstokens und MCP-Refresh-Tokens werden als verschlüsselte undurchsichtige JWE-Werte mit AUTH_SECRET gespeichert.

• Hält das Upstream-Google-Refresh-Token aus MCP-Zugriffstokens heraus. Das normale MCP-Bearer-Token enthält nur das aktuelle kurzlebige Google-Zugriffstoken; der Google-Refresh-Grant befindet sich nur im verschlüsselten MCP-Refresh-Token, das von /oauth/token verarbeitet wird.

• Verwendet Google-REST-APIs über fetch, vermeidet Node-Dateisystem-APIs und den Node-lastigen googleapis-Client.

• Liest Classroom-Kursarbeiten, die Abgaben des aktuellen Schülers, Ankündigungen, Kursarbeitsmaterialien, Themen und Kursmetadaten.

• Normalisiert Classroom-Anhangstypen: Drive-Dateien, Links, YouTube-Videos, Formulare, Gemini-Gems und NotebookLM-Notizbücher.

• Liest bei Bedarf tatsächlichen Text aus angehängten Google Docs, Sheets, Slides, PDFs und Text-/JSON-/XML-Dateien.

Die Implementierung ist bewusst read-only. Fügen Sie später Mutations-Tools hinzu und fordern Sie Schreib-Scopes nur für diese Operationen an.

Related MCP server: mcp-classroom

Modellorientierte Tools

classroom_overview

Verwenden Sie dies zuerst für die Planung. Es verbindet aktive Kurse + alle veröffentlichten Kursarbeiten + die Abgaben des authentifizierten Schülers und bezieht standardmäßig auch Ankündigungen und Kursmaterialien ein. Es unterstützt Datumsgrenzen, Statusfilter für Aufgaben, ausgewählte Kurse, optionale Arbeiten ohne Fälligkeitsdatum und begrenzte Beitragszahlen. Datumsgrenzen für Aufgaben verwenden Fälligkeitsdaten; Grenzen für Ankündigungen/Materialien verwenden die Aktualisierungs-/Erstellungszeit des Beitrags.

Typische Fragen: „Was ist diese Woche fällig?“, „Was haben meine Lehrer diese Woche gepostet?“, „Was fehlt mir?“, „Gib mir einen Plan für heute Abend.“

classroom_course_context

Gibt ein verbundenes Kursbündel zurück: Metadaten, Themen, Aufgaben + Abgabestatus, Kursarbeitsmaterialien, Ankündigungen und normalisierte Anhänge. Mit attachmentMode: "text" liest es auch eine begrenzte Anzahl von Drive-Anhängen, sodass ein Modell direkt auf einen Lehrplan oder ein Handout verweisen kann.

Typische Fragen: „Was sind die Bewertungsregeln in Chemie?“, „Was hat mein Lehrer diese Woche gepostet?“, „Verwende den Lehrplan bei der Antwort.“

classroom_assignment_context

Gibt eine bestimmte Aufgabe, ihre Rubrik, die Abgabe/Bewertung des aktuellen Schülers und den Rubrik-Bewertungsstatus sowie vom Lehrer bereitgestellte Anhänge und eingereichte Anhänge zurück. Es kann auch Anhangstext extrahieren.

Typische Fragen: „Zerlege diese Aufgabe“, „Was genau muss ich einreichen?“, „Vergleiche meine Arbeit mit den Anweisungen.“

classroom_search

Durchsucht Aufgabentitel/-beschreibungen, Materialien, Ankündigungen, Titel/Links von Lehreranhängen und die eigenen eingereichten Anhangstitel des authentifizierten Schülers in ausgewählten Kursen und einem optionalen Datumsbereich. searchAttachmentContents: true führt eine begrenzte Tiefensuche in Drive-Anhängen von Lehrern und den Abgaben des Schülers durch, nützlich, wenn Sie sich an eine Regel aus einem Lehrplan oder eine alte Datei erinnern, aber nicht an den Dateinamen.

Typische Fragen: „Finde meinen Lehrplan“, „Wo hat der Lehrer Cornell-Notizen erwähnt?“, „Finde das Handout zu Kapitel 4.“

classroom_read_attachment

Liest eine Drive-Datei anhand der ID. Google Docs, Sheets, Slides, Textdateien, JSON/XML und textbasierte PDFs geben extrahierten Text plus Metadaten zurück. Nicht unterstützte Binärtypen geben Metadaten und die Drive-URL zurück, anstatt halluzinierte Inhalte zu liefern.

OAuth-Ablauf, der von einem MCP-Client verwendet wird

Die Google-Anmeldung ist Teil der MCP-Verbindung und kein separater Einrichtungsbefehl:

MCP client
  -> /mcp (no bearer token)
  <- 401 + WWW-Authenticate + resource_metadata
  -> /.well-known/oauth-protected-resource/mcp
  -> /.well-known/oauth-authorization-server
  -> /oauth/authorize (PKCE)
  -> accounts.google.com
  -> /oauth/google/callback
  -> client redirect URI with MCP authorization code
  -> /oauth/token
  <- MCP access token + refresh token
  -> /mcp (Bearer <MCP access token>)

Ihr Google-Refresh-Token wird niemals zum Bearer-Token, das an /mcp gesendet wird; es bleibt im verschlüsselten Refresh-Grant des Connectors. Dadurch verhält sich die Erfahrung wie ein normales „Mit Google verbinden“-MCP, anstatt Sie aufzufordern, Anmeldeinformationen in den Agenten einzufügen.

Google-Cloud-Einrichtung

1. Erstellen/auswählen eines Google-Cloud-Projekts und Aktivieren der Google-Classroom-API, Google-Drive-API, Google-Docs-API, Google-Sheets-API und Google-Slides-API.

2. Konfigurieren Sie den OAuth-Zustimmungsbildschirm. Für eine private/persönliche Bereitstellung halten Sie das erlaubte Konto zusätzlich mit ALLOWED_GOOGLE_EMAILS eingeschränkt.

3. Erstellen Sie einen OAuth-2.0-Webanwendungs-Client.

4. Fügen Sie diese exakte Google-Redirect-URI hinzu: https://YOUR_DOMAIN/oauth/google/callback.

5. Kopieren Sie die Client-ID/das Client-Geheimnis in die Vercel-Umgebungsvariablen, die in .env.example gezeigt werden.

Die angeforderten Google-Scopes sind schreibgeschützte Classroom-Scopes plus drive.readonly. drive.readonly ist ein eingeschränkter Google-Scope, daher kann eine öffentliche/mehrbenutzerfähige Produktions-App eine Google-Verifizierung erfordern. Eine Google-OAuth-App im Testmodus kann auch kurzlebige Refresh-Grants haben; verschieben Sie die Zustimmungskonfiguration in den entsprechenden Produktionszustand, wenn Sie bereit sind.

Vercel-Bereitstellung

Setzen Sie die Umgebungsvariablen aus .env.example, stellen Sie bereit und verwenden Sie dann:

https://YOUR_DOMAIN/mcp

als Remote-MCP-Server-URL in Ihrem MCP-Client / ChatGPT-Custom-App. Die erste nicht authentifizierte MCP-Anfrage erhält die OAuth-Herausforderung; der Client entdeckt die OAuth-Metadaten dieses Servers und öffnet den Autorisierungsablauf. Der Autorisierungsendpunkt leitet den Browser dann an Google weiter, und der Callback gibt einen MCP-Autorisierungscode an den Client zurück.

Für ChatGPT halten Sie offline_access beworben. Diese Implementierung fügt es auch dann hinzu, wenn ein Client es weglässt, damit ein MCP-Refresh-Token ausgestellt werden kann und der Connector nicht bei jedem Ablauf des kurzlebigen Zugriffstokens eine Google-Anmeldung benötigt.

Laufzeit

Alle MCP- und OAuth-Endpunkte verwenden Next.js-App-Router-Route-Handler auf der Standard-Node.js-Laufzeit. Dies entspricht den Next.js-16-Richtlinien und vermeidet Edge-Runtime-Paketbeschränkungen. Die Implementierung verwendet dennoch wo praktikabel portable Web-APIs.

Sicherheitshinweise

Dieses Projekt ist bewusst zustandslos. Das macht die Vercel-Bereitstellung einfach, bedeutet aber, dass der Server ein bereits ausgestelltes MCP-Refresh-Token nicht zentral widerrufen oder den einmaligen Verbrauch von Autorisierungscodes ohne persistenten Speicher garantieren kann. Google-Widerruf oder rotierendes AUTH_SECRET macht den Zugriff global ungültig. Wenn Sie dies von einem persönlichen Connector in einen Mehrbenutzerdienst verwandeln, ersetzen Sie die eigenständige Refresh-Token-/Code-Speicherung durch einen datenbank-/KV-gestützten Autorisierungsserver, der Widerruf, einmalige Code-Verwendung, Token-Rotation/Wiederverwendungserkennung und Konto-Trennungen unterstützt.

Setzen Sie ALLOWED_GOOGLE_EMAILS für eine persönliche Bereitstellung. Setzen Sie ALLOWED_CIMD_HOSTS=chatgpt.com für ChatGPT; CIMD-URL-Abruf wird verweigert, wenn diese Whitelist leer ist.

Aktuelle API-Grenzen

„Volle Beitragsunterstützung“ bedeutet hier die Classroom-Objekte, die die öffentliche API einem Schüler zugänglich macht: Kursarbeiten, Kursarbeitsmaterialien und Ankündigungen, zusammengeführt in modellfreundliche Ansichten. Classroom stellt nicht jedes Element der Website-UI als generischen Beitrags-/Kommentar-Feed bereit. Add-ons von Drittanbietern für Classroom, Nur-Scan-PDFs, Office-Binärdateien, Videos und beliebige verlinkte Webseiten werden als typisierte Metadaten/Links zurückgegeben, sofern kein dedizierter Extraktor hinzugefügt wird.

Lokale Entwicklung

Kopieren Sie .env.example nach .env.local, setzen Sie APP_ORIGIN auf den HTTPS-Ursprung, den Ihr OAuth-Client erreichen kann, und dann:

npm install
npm run dev

Google OAuth erfordert normalerweise eine registrierte Redirect-URI. Verwenden Sie für lokales interaktives OAuth daher einen HTTPS-Tunnel und setzen Sie APP_ORIGIN auf den Ursprung dieses Tunnels.