Google Classroom MCP — Next.js + Google OAuth

Un MCP remoto y de solo lectura para Google Classroom, diseñado para clientes de ChatGPT/agentes. Reemplaza una arquitectura local de stdio + tokens.json con Route Handlers de Next.js App Router sin estado, descubrimiento OAuth, un flujo interactivo de inicio de sesión con Google, herramientas de Classroom de alta información y extracción de texto de archivos adjuntos de Drive.

Qué hace esta implementación

• Ejecuta /mcp como un endpoint MCP estándar web en el runtime Node.js predeterminado de Next.js.

• Usa la API actual @modelcontextprotocol/server v2 en lugar del SDK monolítico v1.

• Implementa metadatos de recursos protegidos OAuth y metadatos del servidor de autorización OAuth.

• Admite tanto documentos de metadatos de ID de cliente OAuth (CIMD) como registro dinámico de clientes (DCR) para compatibilidad con clientes.

• Envía al usuario a través de OAuth de Google dentro del flujo de conexión MCP. No hay un comando CLI auth local ni tokens.json.

• Mantiene la implementación sin estado: el estado de autorización, los códigos de autorización de corta duración, los tokens de acceso MCP y los tokens de actualización MCP son valores JWE opacos cifrados usando AUTH_SECRET.

• Mantiene el token de actualización de Google upstream fuera de los tokens de acceso MCP. El portador MCP normal contiene solo el token de acceso de Google de corta duración actual; la concesión de actualización de Google solo está dentro del token de actualización MCP cifrado manejado por /oauth/token.

• Usa las API REST de Google a través de fetch, evitando las API del sistema de archivos de Node y el cliente googleapis pesado para Node.

• Lee el trabajo del curso de Classroom, las entregas del estudiante actual, los anuncios, los materiales del trabajo del curso, los temas y los metadatos del curso.

• Normaliza los tipos de archivos adjuntos de Classroom: archivos de Drive, enlaces, videos de YouTube, Formularios, Gems de Gemini y cuadernos de NotebookLM.

• Lee texto real de Google Docs, Sheets, Slides, PDFs y archivos de texto plano/JSON/XML adjuntos cuando se solicita.

La implementación es deliberadamente de solo lectura. Agrega herramientas de mutación más adelante y solicita solo los alcances de escritura para esas operaciones.

Related MCP server: mcp-classroom

Herramientas orientadas al modelo

classroom_overview

Úsala primero para planificar. Combina cursos activos + todo el trabajo del curso publicado + las entregas del estudiante autenticado, y por defecto también incluye anuncios y materiales de clase. Admite límites de fechas, filtrado por estado de tarea, cursos seleccionados, trabajo opcional sin fecha de vencimiento y recuentos de publicaciones limitados. Los límites de fechas de tareas usan fechas de vencimiento; los límites de anuncios/materiales usan la hora de actualización/creación de la publicación.

Preguntas típicas: "¿Qué vence esta semana?", "¿Qué publicaron mis profesores esta semana?", "¿Qué me falta?", "Dame un plan para esta noche."

classroom_course_context

Devuelve un paquete de curso combinado: metadatos, temas, tareas + estado de entrega, materiales del trabajo del curso, anuncios y archivos adjuntos normalizados. Con attachmentMode: "text", también lee un número limitado de archivos adjuntos de Drive para que un modelo pueda referenciar directamente un programa de estudios o un folleto.

Preguntas típicas: "¿Cuáles son las reglas de calificación en Química?", "¿Qué publicó mi profesor esta semana?", "Usa el programa de estudios al responder."

classroom_assignment_context

Devuelve una tarea específica, su rúbrica, la entrega/calificación del estudiante actual y el estado de la rúbrica, los archivos adjuntos proporcionados por el profesor y los archivos adjuntos enviados. También puede extraer texto de archivos adjuntos.

Preguntas típicas: "Desglosa esta tarea", "¿Qué exactamente necesito enviar?", "Compara mi trabajo con las instrucciones."

classroom_search

Busca títulos/descripciones de tareas, materiales, anuncios, títulos/enlaces de archivos adjuntos de profesores y títulos de archivos adjuntos enviados por el estudiante autenticado en los cursos seleccionados y un rango de fechas opcional. searchAttachmentContents: true realiza una búsqueda profunda limitada dentro de los archivos adjuntos de Drive tanto de profesores como de las entregas del estudiante, útil cuando recuerdas una regla de un programa de estudios o un archivo antiguo pero no su nombre de archivo.

Preguntas típicas: "Encuentra mi programa de estudios", "¿Dónde mencionó el profesor las notas Cornell?", "Encuentra el folleto sobre el Capítulo 4."

classroom_read_attachment

Lee un archivo de Drive por ID. Google Docs, Sheets, Slides, archivos de texto, JSON/XML y PDFs basados en texto devuelven texto extraído más metadatos. Los tipos binarios no compatibles devuelven metadatos y la URL de Drive en lugar de contenido alucinado.

Flujo OAuth utilizado por un cliente MCP

El inicio de sesión con Google es parte de la conexión MCP en lugar de un comando de configuración separado:

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

Tu token de actualización de Google nunca se convierte en el token portador enviado a /mcp; permanece dentro de la concesión de actualización cifrada del conector. Esto es lo que hace que la experiencia se comporte como un MCP normal de "Conectar con Google" en lugar de pedirte que pegues credenciales en el agente.

Configuración de Google Cloud

1. Crea/selecciona un proyecto de Google Cloud y habilita la API de Google Classroom, la API de Google Drive, la API de Google Docs, la API de Google Sheets y la API de Google Slides.

2. Configura la pantalla de consentimiento de OAuth. Para una implementación privada/personal, mantén la cuenta permitida restringida con ALLOWED_GOOGLE_EMAILS también.

3. Crea un cliente OAuth 2.0 de Aplicación web.

4. Agrega esta URI de redirección de Google exacta: https://YOUR_DOMAIN/oauth/google/callback.

5. Copia el ID de cliente/secreto de cliente en las variables de entorno de Vercel que se muestran en .env.example.

Los alcances de Google solicitados son alcances de Classroom de solo lectura más drive.readonly. drive.readonly es un alcance restringido de Google, por lo que una aplicación de producción pública/multiusuario puede requerir verificación de Google. Una aplicación de OAuth de Google en modo Testing también puede tener concesiones de actualización de corta duración; mueve la configuración de consentimiento al estado de producción apropiado cuando estés listo.

Implementación en Vercel

Configura las variables de entorno de .env.example, implementa y luego usa:

https://YOUR_DOMAIN/mcp

como la URL del servidor MCP remoto en tu cliente MCP / aplicación personalizada de ChatGPT. La primera solicitud MCP no autenticada recibe el desafío OAuth; el cliente descubre los metadatos OAuth de este servidor y abre el flujo de autorización. El endpoint de autorización luego redirige el navegador a Google, y la devolución de llamada devuelve un código de autorización MCP al cliente.

Para ChatGPT, mantén offline_access anunciado. Esta implementación lo agrega incluso si un cliente lo omite para que se pueda emitir un token de actualización MCP y el conector no necesite un inicio de sesión de Google cada vez que expire el token de acceso de corta duración.

Runtime

Todos los endpoints MCP y OAuth usan Route Handlers de Next.js App Router en el runtime Node.js predeterminado. Esto coincide con la guía de Next.js 16 y evita las restricciones de paquetes del runtime Edge. La implementación aún usa API web portátiles cuando es práctico.

Notas de seguridad

Este proyecto es intencionalmente sin estado. Eso hace que la implementación en Vercel sea simple, pero significa que el servidor no puede revocar centralmente un token de actualización MCP ya emitido ni garantizar el consumo de un código de autorización de un solo uso sin almacenamiento persistente. La revocación de Google o la rotación de AUTH_SECRET invalida el acceso globalmente. Si conviertes esto de un conector personal a un servicio multiusuario, reemplaza el almacenamiento autocontenido de tokens de actualización/códigos con un servidor de autorización respaldado por base de datos/KV que admita revocación, uso de códigos de un solo uso, detección de rotación/reutilización de tokens y desconexiones de cuentas.

Configura ALLOWED_GOOGLE_EMAILS para una implementación personal. Configura ALLOWED_CIMD_HOSTS=chatgpt.com para ChatGPT; la obtención de URL CIMD se deniega cuando esta lista de permitidos está vacía.

Límites actuales de la API

"Compatibilidad completa con publicaciones" aquí significa los objetos de Classroom que la API pública expone a un estudiante: trabajo del curso, materiales del trabajo del curso y anuncios, combinados en vistas amigables para el modelo. Classroom no expone cada parte de la interfaz web como un feed genérico de publicaciones/comentarios. Los complementos de terceros de Classroom, PDFs solo de escaneo, binarios de Office, videos y páginas web arbitrarias enlazadas se devuelven como metadatos/enlaces tipados a menos que se agregue un extractor dedicado.

Desarrollo local

Copia .env.example a .env.local, configura APP_ORIGIN al origen HTTPS que tu cliente OAuth pueda alcanzar, luego:

npm install
npm run dev

Google OAuth normalmente requiere una URI de redirección registrada, por lo que para OAuth interactivo local usa un túnel HTTPS y configura APP_ORIGIN a ese origen del túnel.