Google Classroom MCP — Next.js + Google OAuth

ChatGPT/エージェントクライアント向けに設計された、リモートで読み取り専用のGoogle Classroom MCPです。ローカルのstdio + tokens.json アーキテクチャを、ステートレスなNext.js App Router Route Handlers、OAuthディスカバリ、インタラクティブなGoogleサインインフロー、高情報量のClassroomツール、Drive添付ファイルのテキスト抽出に置き換えます。

この実装が行うこと

• /mcp を、デフォルトのNext.js Node.jsランタイム上のWeb標準MCPエンドポイントとして実行します。

• モノリシックなv1 SDKではなく、現在の @modelcontextprotocol/server v2 APIを使用します。

• 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ベアラーには現在の短期間の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

1つの結合されたコースバンドルを返します：メタデータ、トピック、課題 + 提出ステータス、クラスワーク教材、アナウンス、正規化された添付ファイル。attachmentMode: "text" の場合、モデルがシラバスや配布資料を直接参照できるように、制限付きの数のDrive添付ファイルも読み取ります。

典型的な質問：「化学の採点ルールは？」「今週、先生は何を投稿した？」「回答するときはシラバスを使用して。」

classroom_assignment_context

特定の課題、そのルーブリック、現在の学生の提出物/成績とルーブリックの成績状態、教師提供の添付ファイル、提出された添付ファイルを返します。添付ファイルのテキスト抽出も可能です。

典型的な質問：「この課題を分解して」「正確に何を提出する必要がある？」「自分の作業を指示と比較して。」

classroom_search

選択したコースとオプションの日付範囲にわたって、課題のタイトル/説明、教材、アナウンス、教師の添付ファイルのタイトル/リンク、認証済み学生自身の提出添付ファイルのタイトルを検索します。searchAttachmentContents: true は、教師と学生の提出物の両方からDrive添付ファイル内の制限付きの深い検索を実行します。シラバスのルールや古いファイルの名前を覚えているがファイル名がわからない場合に役立ちます。

典型的な質問：「シラバスを見つけて」「先生がコーネルノートについて言及したのはどこ？」「第4章の配布資料を見つけて。」

classroom_read_attachment

IDで1つの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 に送信されるベアラートークンになることはありません。コネクタの暗号化されたリフレッシュグラント内に留まります。これにより、エージェントに資格情報を貼り付けるように求めるのではなく、通常の「Googleで接続」MCPのように動作します。

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アプリケーションクライアントを作成します。

4. この正確なGoogleリダイレクトURIを追加します：https://YOUR_DOMAIN/oauth/google/callback。

5. クライアントID/クライアントシークレットを .env.example に示されているVercel環境変数にコピーします。

要求されるGoogleスコープは、読み取り専用のClassroomスコープに加えて drive.readonly です。drive.readonly は制限付きのGoogleスコープであるため、公開/マルチユーザーの本番アプリではGoogleの審査が必要になる場合があります。テスト状態のままの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へのデプロイは簡単ですが、サーバーが既に発行された1つのMCPリフレッシュトークンを集中的に失効させたり、永続ストレージなしで認可コードの1回限りの使用を保証したりすることはできません。Googleの失効または AUTH_SECRET のローテーションは、アクセスをグローバルに無効にします。これを個人用コネクタからマルチユーザーサービスに変える場合は、自己完結型のリフレッシュトークン/コードストレージを、失効、1回限りのコード使用、トークンのローテーション/再利用検出、アカウントの切断をサポートするデータベース/KVバックアップの認可サーバーに置き換えてください。

個人用デプロイには ALLOWED_GOOGLE_EMAILS を設定してください。ChatGPTには ALLOWED_CIMD_HOSTS=chatgpt.com を設定してください。この許可リストが空の場合、CIMD URLフェッチは拒否されます。

現在のAPI境界

ここでの「完全な投稿サポート」とは、公開APIが学生に公開するClassroomオブジェクト（コースワーク、コースワーク教材、アナウンス）を、モデルに優しいビューに結合したものを意味します。Classroomは、WebサイトUIのすべての部分を汎用の投稿/コメントフィードとして公開するわけではありません。サードパーティのClassroomアドオン、スキャン専用PDF、Officeバイナリ、ビデオ、任意のリンクされたWebページは、専用の抽出器が追加されない限り、型付きメタデータ/リンクとして返されます。

ローカル開発

.env.example を .env.local にコピーし、APP_ORIGIN をOAuthクライアントが到達できるHTTPSオリジンに設定してから、次を実行します：

npm install
npm run dev

Google OAuthは通常、登録されたリダイレクトURIを必要とするため、ローカルのインタラクティブOAuthにはHTTPSトンネルを使用し、APP_ORIGIN をそのトンネルオリジンに設定してください。