Google Classroom MCP — Next.js + Google OAuth

ChatGPT/에이전트 클라이언트용 원격 읽기 전용 Google Classroom MCP입니다. 로컬 stdio + tokens.json 아키텍처를 상태 비저장 Next.js App Router Route Handler, OAuth 디스커버리, 대화형 Google 로그인 흐름, 정보량이 많은 Classroom 도구, Drive 첨부 파일 텍스트 추출로 대체합니다.

이 구현이 하는 일

• /mcp를 기본 Next.js Node.js 런타임에서 웹 표준 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

하나의 결합된 과정 번들을 반환합니다: 메타데이터, 주제, 과제 + 제출 상태, 수업 자료, 공지사항, 정규화된 첨부 파일. attachmentMode: "text"를 사용하면 제한된 수의 Drive 첨부 파일도 읽어 모델이 강의 계획서나 유인물을 직접 참조할 수 있습니다.

일반적인 질문: "화학의 채점 규칙은 무엇인가요?", "선생님이 이번 주에 무엇을 게시했나요?", "답변할 때 강의 계획서를 사용하세요."

classroom_assignment_context

특정 과제, 루브릭, 현재 학생의 제출물/성적 및 루브릭 성적 상태, 교사 제공 첨부 파일, 제출된 첨부 파일을 반환합니다. 첨부 파일 텍스트 추출도 가능합니다.

일반적인 질문: "이 과제를 분석해 주세요.", "정확히 무엇을 제출해야 하나요?", "내 작업을 지시 사항과 비교해 주세요."

classroom_search

선택된 과정과 선택적 날짜 범위에서 과제 제목/설명, 자료, 공지사항, 교사 첨부 파일 제목/링크, 인증된 학생의 제출 첨부 파일 제목을 검색합니다. searchAttachmentContents: true는 교사와 학생 제출물의 Drive 첨부 파일 내부를 제한적으로 심층 검색하여, 강의 계획서의 규칙이나 오래된 파일의 이름은 기억나지만 파일명은 기억나지 않을 때 유용합니다.

일반적인 질문: "내 강의 계획서를 찾아 주세요.", "선생님이 Cornell 노트를 언급한 곳이 어디인가요?", "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로 전송되는 베어러 토큰이 되지 않으며, 커넥터의 암호화된 리프레시 그랜트 안에만 유지됩니다. 이것이 에이전트에 자격 증명을 붙여넣도록 요청하는 대신 일반적인 "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 웹 애플리케이션 클라이언트를 만듭니다.

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 Handler를 사용합니다. 이는 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을 해당 터널 오리진으로 설정하세요.