Google Classroom MCP — Next.js + Google OAuth

一个面向 ChatGPT/agent 客户端的远程、只读 Google Classroom MCP。它用无状态的 Next.js App Router Route Handlers、OAuth 发现机制、交互式 Google 登录流程、高信息量的 Classroom 工具以及 Drive 附件文本提取，取代了本地 stdio + tokens.json 架构。

此实现的功能

• 在默认的 Next.js Node.js 运行时上，将 /mcp 作为符合 Web 标准的 MCP 端点运行。

• 使用当前的 @modelcontextprotocol/server v2 API，而非 v1 单体 SDK。

• 实现 OAuth Protected Resource Metadata 和 OAuth Authorization Server Metadata。

• 同时支持 OAuth Client ID Metadata Documents (CIMD) 和 Dynamic Client Registration (DCR)，以保证客户端兼容性。

• 在 MCP 连接流程中引导用户完成 Google OAuth。没有本地 auth CLI 命令，也没有 tokens.json。

• 保持部署无状态：授权状态、短期授权码、MCP 访问令牌和 MCP 刷新令牌均使用 AUTH_SECRET 加密为不透明的 JWE 值。

• 将上游 Google 刷新令牌排除在 MCP 访问令牌之外。常规 MCP bearer 仅包含当前短期的 Google 访问令牌；Google 刷新授权只存在于由 /oauth/token 处理的加密 MCP 刷新令牌中。

• 通过 fetch 使用 Google REST API，避免使用 Node 文件系统 API 和依赖 Node 的 googleapis 客户端。

• 读取 Classroom 课程作业、当前学生的提交、公告、课程作业材料、主题和课程元数据。

• 规范化 Classroom 附件类型：Drive 文件、链接、YouTube 视频、Forms、Gemini Gems 和 NotebookLM 笔记本。

• 在请求时读取所附 Google Docs、Sheets、Slides、PDF 以及纯文本/JSON/XML 文件中的实际文本。

此实现刻意保持只读。后续如需添加变更工具，请仅为这些操作请求写入作用域。

Related MCP server: mcp-classroom

面向模型的工具

classroom_overview

规划时首先使用此工具。它整合了活跃课程 + 所有已发布的课程作业 + 已认证学生的提交，默认还会纳入公告和课程材料。它支持日期范围、作业状态筛选、选定课程、可选的无限期作业以及有上限的帖子数量。作业日期范围使用截止日期；公告/材料范围使用帖子更新/创建时间。

典型问题：“这周有什么作业到期？”“老师们这周发布了什么？”“我漏掉了什么？”“给我一个今晚的计划。”

classroom_course_context

返回一个整合的课程包：元数据、主题、作业 + 提交状态、课程作业材料、公告和规范化附件。使用 attachmentMode: "text" 时，它还会读取有限数量的 Drive 附件，以便模型直接引用教学大纲或讲义。

典型问题：“化学课的评分规则是什么？”“老师这周发布了什么？”“回答时请参考教学大纲。”

classroom_assignment_context

返回特定作业、其评分标准、当前学生的提交/成绩和评分标准评分状态、教师提供的附件以及已提交的附件。它还可以提取附件文本。

典型问题：“拆解这个作业”，“我到底需要提交什么？”“将我的作业与要求进行比较。”

classroom_search

在选定课程和可选日期范围内搜索作业标题/描述、材料、公告、教师附件标题/链接以及已认证学生自己提交的附件标题。searchAttachmentContents: true 会在教师和学生的提交中的 Drive 附件内部执行有上限的深度搜索，当你记得教学大纲或旧文件中的某条规则但记不清文件名时非常有用。

典型问题：“找到我的教学大纲”，“老师在哪里提到了康奈尔笔记？”“找到关于第 4 章的讲义。”

classroom_read_attachment

按 ID 读取一个 Drive 文件。Google Docs、Sheets、Slides、文本文件、JSON/XML 和基于文本的 PDF 会返回提取的文本及元数据。不支持的二进制类型会返回元数据和 Drive URL，而不是虚构的内容。

MCP 客户端使用的 OAuth 流程

Google 登录是 MCP 连接的一部分，而不是单独的设置命令：

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

你的 Google 刷新令牌永远不会成为发送到 /mcp 的 bearer 令牌；它保留在连接器的加密刷新授权中。这正是让体验像正常的“使用 Google 连接”MCP 而不是要求你将凭据粘贴到 agent 中的原因。

Google Cloud 设置

1. 创建/选择一个 Google Cloud 项目，并启用 Google Classroom API、Google Drive API、Google Docs API、Google Sheets API 和 Google Slides API。

2. 配置 OAuth 同意屏幕。对于私有/个人部署，请同时使用 ALLOWED_GOOGLE_EMAILS 限制允许的账户。

3. 创建一个 OAuth 2.0 Web application 客户端。

4. 添加这个确切的 Google 重定向 URI：https://YOUR_DOMAIN/oauth/google/callback。

5. 将客户端 ID/客户端密钥复制到 .env.example 中显示的 Vercel 环境变量中。

请求的 Google 作用域是只读的 Classroom 作用域加上 drive.readonly。drive.readonly 是受限的 Google 作用域，因此公开/多用户生产应用可能需要 Google 验证。处于 Testing 状态的 Google OAuth 应用也可能有短期刷新授权；准备好后，请将同意配置移至相应的生产状态。

Vercel 部署

设置 .env.example 中的环境变量，部署，然后使用：

https://YOUR_DOMAIN/mcp

作为 MCP 客户端 / ChatGPT 自定义应用中的远程 MCP 服务器 URL。第一个未认证的 MCP 请求会收到 OAuth 质询；客户端发现此服务器的 OAuth 元数据并打开授权流程。授权端点随后将浏览器重定向到 Google，回调将 MCP 授权码返回给客户端。

对于 ChatGPT，请保持通告 offline_access。即使客户端省略了它，此实现也会添加它，以便可以签发 MCP 刷新令牌，并且连接器无需在短期访问令牌每次过期时都进行 Google 登录。

运行时

所有 MCP 和 OAuth 端点都在默认的 Node.js 运行时上使用 Next.js App Router Route Handlers。这符合 Next.js 16 的指导，并避免了 Edge 运行时的包限制。此实现仍然在可行的地方使用可移植的 Web API。

安全说明

此项目有意保持无状态。这使 Vercel 部署变得简单，但也意味着服务器无法在没有持久化存储的情况下集中撤销已签发的某个 MCP 刷新令牌，或保证授权码的一次性消费。Google 撤销或轮换 AUTH_SECRET 会使访问全局失效。如果你将此个人连接器转变为多用户服务，请将自包含的刷新令牌/授权码存储替换为基于数据库/KV 的授权服务器，以支持撤销、一次性授权码使用、令牌轮换/重用检测和账户断开。

为个人部署设置 ALLOWED_GOOGLE_EMAILS。为 ChatGPT 设置 ALLOWED_CIMD_HOSTS=chatgpt.com；当此允许列表为空时，CIMD URL 获取将被拒绝。

当前 API 边界

这里的“完整帖子支持”指的是公共 API 向学生公开的 Classroom 对象：课程作业、课程作业材料和公告，整合为对模型友好的视图。Classroom 不会将网站 UI 的每个部分都作为通用的帖子/评论流公开。第三方 Classroom 插件、仅扫描的 PDF、Office 二进制文件、视频和任意链接的网页都会作为类型化元数据/链接返回，除非添加了专门的提取器。

本地开发

将 .env.example 复制为 .env.local，将 APP_ORIGIN 设置为你的 OAuth 客户端可以访问的 HTTPS 源，然后：

npm install
npm run dev

Google OAuth 通常需要已注册的重定向 URI，因此对于本地交互式 OAuth，请使用 HTTPS 隧道并将 APP_ORIGIN 设置为该隧道的源。