Google Classroom MCP — Next.js + Google OAuth

Удалённый MCP-сервер Google Classroom только для чтения, предназначенный для ChatGPT/агентных клиентов. Он заменяет локальную архитектуру stdio + tokens.json на статeless-обработчики маршрутов Next.js App Router, OAuth discovery, интерактивный вход через Google, информативные инструменты Classroom и извлечение текста из вложений Drive.

Что делает эта реализация

• Запускает /mcp как веб-стандартную конечную точку MCP на стандартном Node.js-рантайме Next.js.

• Использует текущий API @modelcontextprotocol/server v2 вместо монолитного SDK v1.

• Реализует OAuth Protected Resource Metadata и OAuth Authorization Server Metadata.

• Поддерживает как OAuth Client ID Metadata Documents (CIMD), так и Dynamic Client Registration (DCR) для совместимости с клиентами.

• Проводит пользователя через Google OAuth в процессе подключения MCP. Нет локальной команды auth CLI и нет tokens.json.

• Сохраняет развёртывание статeless: состояние авторизации, короткоживущие коды авторизации, MCP access-токены и MCP refresh-токены — это зашифрованные непрозрачные значения JWE с использованием AUTH_SECRET.

• Не включает вышестоящий Google refresh-токен в MCP access-токены. Обычный MCP bearer содержит только текущий короткоживущий Google access-токен; грант обновления Google находится только внутри зашифрованного MCP refresh-токена, обрабатываемого /oauth/token.

• Использует Google REST API через fetch, избегая Node-файловых API и тяжёлого клиента googleapis.

• Читает материалы курса, представления текущего студента, объявления, материалы заданий, темы и метаданные курса.

• Нормализует типы вложений Classroom: файлы Drive, ссылки, видео YouTube, формы, Gemini Gems и блокноты NotebookLM.

• Читает фактический текст из прикреплённых Google Docs, Sheets, Slides, PDF и текстовых/JSON/XML файлов по запросу.

Реализация намеренно только для чтения. Добавляйте инструменты мутации позже и запрашивайте write-скоупы только для этих операций.

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

Читает один файл Drive по ID. Google Docs, Sheets, Slides, текстовые файлы, JSON/XML и текстовые PDF возвращают извлечённый текст плюс метаданные. Неподдерживаемые бинарные типы возвращают метаданные и URL Drive, а не выдуманное содержимое.

OAuth-поток, используемый MCP-клиентом

Вход через 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 refresh-токен никогда не становится bearer-токеном, отправляемым в /mcp; он остаётся внутри зашифрованного гранта обновления коннектора. Именно это делает работу похожей на обычный MCP «Подключиться через Google», а не на запрос вставить учётные данные в агента.

Настройка 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 клиент Веб-приложение.

4. Добавьте точный URI перенаправления Google: https://YOUR_DOMAIN/oauth/google/callback.

5. Скопируйте идентификатор клиента/секрет клиента в переменные окружения Vercel, показанные в .env.example.

Запрашиваемые Google-скоупы — это read-only скоупы Classroom плюс drive.readonly. drive.readonly — ограниченный Google-скоуп, поэтому для публичного/многопользовательского продакшн-приложения может потребоваться проверка Google. Приложение Google OAuth, оставленное в режиме Testing, также может иметь короткоживущие гранты обновления; переведите конфигурацию согласия в соответствующее продакшн-состояние, когда будете готовы.

Развёртывание на Vercel

Установите переменные окружения из .env.example, разверните, затем используйте:

https://YOUR_DOMAIN/mcp

как URL удалённого MCP-сервера в вашем MCP-клиенте / пользовательском приложении ChatGPT. Первый неаутентифицированный MCP-запрос получает OAuth-вызов; клиент обнаруживает OAuth-метаданные этого сервера и открывает поток авторизации. Затем конечная точка авторизации перенаправляет браузер на Google, и обратный вызов возвращает MCP-код авторизации клиенту.

Для ChatGPT сохраняйте рекламу offline_access. Эта реализация добавляет его, даже если клиент его опускает, чтобы можно было выдать MCP refresh-токен и коннектору не требовался вход через Google каждый раз, когда истекает короткоживущий access-токен.

Среда выполнения

Все конечные точки MCP и OAuth используют обработчики маршрутов Next.js App Router на стандартном Node.js-рантайме. Это соответствует рекомендациям Next.js 16 и избегает ограничений пакетов Edge-рантайма. Реализация по-прежнему использует переносимые веб-API, где это практично.

Замечания по безопасности

Этот проект намеренно статeless. Это упрощает развёртывание на Vercel, но означает, что сервер не может централизованно отозвать уже выданный MCP refresh-токен или гарантировать одноразовое использование кода авторизации без постоянного хранилища. Отзыв Google или ротация AUTH_SECRET делает доступ недействительным глобально. Если вы превращаете этот личный коннектор в многопользовательский сервис, замените самодостаточное хранилище refresh-токенов/кодов на сервер авторизации на основе базы данных/KV, поддерживающий отзыв, одноразовое использование кодов, обнаружение ротации/повторного использования токенов и отключение аккаунтов.

Установите ALLOWED_GOOGLE_EMAILS для личного развёртывания. Установите ALLOWED_CIMD_HOSTS=chatgpt.com для ChatGPT; выборка URL CIMD запрещена, когда этот список разрешённых пуст.

Текущие границы API

«Полная поддержка постов» здесь означает объекты Classroom, которые публичный API предоставляет студенту: задания, материалы заданий и объявления, объединённые в удобные для модели представления. Classroom не предоставляет каждую часть веб-интерфейса как универсальную ленту постов/комментариев. Сторонние дополнения Classroom, PDF только для сканирования, бинарные файлы Office, видео и произвольные связанные веб-страницы возвращаются как типизированные метаданные/ссылки, если не добавлен специальный экстрактор.

Локальная разработка

Скопируйте .env.example в .env.local, установите APP_ORIGIN на HTTPS-источник, доступный вашему OAuth-клиенту, затем:

npm install
npm run dev

Google OAuth обычно требует зарегистрированный URI перенаправления, поэтому для локального интерактивного OAuth используйте HTTPS-туннель и установите APP_ORIGIN на источник этого туннеля.