google-classroom-mcp
Summary: This MCP server connects LLM agents (Antigravity/Claude) to Google Classroom, letting them read courses, assignments, submissions, announcements, materials, and rosters, plus turn in or reclaim assignments on the user's behalf.
List & inspect courses:
list_courses(filter by state, student/teacher role) andget_course(full course details, enrollment code, calendar ID).Browse coursework:
list_coursework(assignments/quizzes, filter by state, sort by due/update time) andget_coursework(description, rubrics, attached Drive files, YouTube links).Track submissions:
list_submissions(states like TURNED_IN/RETURNED, lateness, grades) andget_submission(attached files, links, grade history).View class stream & resources:
list_announcements(stream notices, creator info, attachments) andlist_coursework_materials(syllabi, lecture slides, shared resources).See rosters:
list_teachersandlist_students(display names, emails, user IDs) for a course.Act on submissions:
turn_in_assignmentto submit for grading andreclaim_assignmentto unsubmit for editing.Auth handling: OAuth 2.0 loopback login with stored refresh token and automatic access-token refresh before requests.
Provides tools for interacting with Google Classroom, enabling AI agents to manage and retrieve courses, coursework, student submissions, announcements, materials, teachers, and students, including turning in and reclaiming assignments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@google-classroom-mcp List my active courses and show assignments due this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Google Classroom Model Context Protocol (MCP) Server
A native, lightweight, and robust Model Context Protocol (MCP) server for the Google Classroom API. It connects LLM reasoning engines (Antigravity, Claude Desktop, and autonomous fleet agents) directly to Google Classroom streams, assignments, submissions, rosters, and educational resources.
π Architecture & Flow
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Antigravity / Claude Desktop (MCP Client) β
βββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββ
β JSON-RPC (Stdio)
βββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββ
β google-classroom-mcp β
β - index.mjs (MCP Protocol Dispatcher) β
β - auth.mjs (OAuth 2.0 Loopback Receiver) β
β - sync-schemas.mjs (Lazy Tool Schema Generator) β
β - sync.ps1 (Ecosystem Sync & Secret Guard) β
βββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββ
β HTTPS REST with Auto Token Refresh
βββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββ
β Google Classroom REST API (v1) β
β https://classroom.googleapis.com/v1/... β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββRelated MCP server: ClassroomScribe
π Available Tools & Implementation Methods
The server implements 12 high-agency tools conforming to @modelcontextprotocol/sdk:
1. list_courses
Method:
GET https://classroom.googleapis.com/v1/coursesParameters:
courseStates(array of strings, optional): Filter by status (ACTIVE,ARCHIVED,PROVISIONED,DECLINED,SUSPENDED). Defaults to['ACTIVE'].pageSize(number, optional): Maximum items to return (default 20).studentId(string, optional): Filter courses enrolled as student ("me"or user ID).teacherId(string, optional): Filter courses instructed as teacher ("me"or user ID).
Returns: Markdown list of matching courses with ID, name, section, room, enrollment code, and web link.
2. get_course
Method:
GET https://classroom.googleapis.com/v1/courses/{courseId}Parameters:
courseId(string, required): Unique Google Classroom course identifier.
Returns: Full course object schema including enrollment code, description, teacher group email, and calendar ID.
3. list_coursework
Method:
GET https://classroom.googleapis.com/v1/courses/{courseId}/courseWorkParameters:
courseId(string, required): Target course identifier.courseWorkStates(array of strings, optional): Filter (PUBLISHED,DRAFT,DELETED).pageSize(number, optional): Maximum assignments to fetch (default 30).orderBy(string, optional): Order criteria (dueDate desc,updateTime desc).
Returns: Formatted summary of assignments, problem sets, due dates/times, max points, and links.
4. get_coursework
Method:
GET https://classroom.googleapis.com/v1/courses/{courseId}/courseWork/{courseWorkId}Parameters:
courseId(string, required): Course identifier.courseWorkId(string, required): Coursework item identifier.
Returns: Complete assignment metadata, instructions, rubrics, and attached materials (Google Drive files, YouTube videos, links).
5. list_submissions
Method:
GET https://classroom.googleapis.com/v1/courses/{courseId}/courseWork/{courseWorkId}/studentSubmissionsParameters:
courseId(string, required): Course identifier.courseWorkId(string, required): Coursework item ID (or"-"for all coursework).userId(string, optional): Target student filter ("me"for current authenticated student).states(array of strings, optional): Filter (NEW,CREATED,TURNED_IN,RETURNED,RECLAIMED_BY_STUDENT).
Returns: Student submission states, lateness flags, assigned grades, draft grades, and turn-in links.
6. get_submission
Method:
GET https://classroom.googleapis.com/v1/courses/{courseId}/courseWork/{courseWorkId}/studentSubmissions/{submissionId}Parameters:
courseId(string, required)courseWorkId(string, required)submissionId(string, required)
Returns: Detailed submission record with attached student drive files, links, and grade history.
7. list_announcements
Method:
GET https://classroom.googleapis.com/v1/courses/{courseId}/announcementsParameters:
courseId(string, required): Course identifier.announcementStates(array of strings, optional): Filter (PUBLISHED,DRAFT,DELETED).pageSize(number, optional): Max announcements (default 20).
Returns: Course stream announcements, updates, creator info, timestamps, and attached assets.
8. list_coursework_materials
Method:
GET https://classroom.googleapis.com/v1/courses/{courseId}/courseWorkMaterialsParameters:
courseId(string, required): Course identifier.courseWorkMaterialStates(array of strings, optional): Defaults to['PUBLISHED'].
Returns: Standalone class resources, lecture slide decks, syllabus documents, and shared materials.
9. list_teachers
Method:
GET https://classroom.googleapis.com/v1/courses/{courseId}/teachersParameters:
courseId(string, required)
Returns: List of instructors with display name, email, and user IDs.
10. list_students
Method:
GET https://classroom.googleapis.com/v1/courses/{courseId}/studentsParameters:
courseId(string, required)
Returns: List of enrolled classmates with display name, email, and user IDs.
11. turn_in_assignment
Method:
POST https://classroom.googleapis.com/v1/courses/{courseId}/courseWork/{courseWorkId}/studentSubmissions/{submissionId}:turnInParameters:
courseId(string, required)courseWorkId(string, required)submissionId(string, required)
Returns: Confirmation that the student submission has been formally marked as turned in for grading.
12. reclaim_assignment
Method:
POST https://classroom.googleapis.com/v1/courses/{courseId}/courseWork/{courseWorkId}/studentSubmissions/{submissionId}:reclaimParameters:
courseId(string, required)courseWorkId(string, required)submissionId(string, required)
Returns: Confirmation that the student submission has been unsubmitted/reclaimed for editing.
π Authentication & Token Lifecycle
Course content copy tool
copy_course_contents previews published topics, coursework, class materials, announcements, and Drive attachments before making changes. It defaults to dryRun: true. To apply a copy, set dryRun: false; the destination must be ACTIVE and have no enrolled students. The tool stores an idempotency/resume ledger at %LOCALAPPDATA%/google-classroom-mcp/copy-ledger.json (or the user's home directory where LOCALAPPDATA is unavailable). Drive requests support shared-drive files. Google Forms, Gemini Gems, and NotebookLM attachments are recreated as titled links because Classroom does not permit creating those special attachment types directly. Classroom rejects new coursework with past due dates: the default pastDueDatePolicy: "skip" leaves those assignments uncopied; pastDueDatePolicy: "omit" publishes them without an expired due date and lists that loss in the result.
For example, extend the Classroom server's MCP env with the existing Drive MCP token and OAuth file paths:
{
"DRIVE_CREDENTIALS_PATH": "C:\\Users\\<user>\\.gdrive-server-credentials.json",
"DRIVE_OAUTH_PATH": "C:\\Users\\<user>\\.gdrive-credentials.json"
}Drive credentials are deliberately separate from Classroom credentials. Configure DRIVE_CREDENTIALS_PATH and DRIVE_OAUTH_PATH to the existing Google Drive MCP token and OAuth client files. The Drive OAuth token needs permission to copy the source files and create files under the target folder. Classroom OAuth requires classroom.coursework.students, classroom.announcements, classroom.courseworkmaterials, and classroom.topics; rerun npm run auth and grant the updated access after changing these scopes. Rubric creation depends on Google account/course support and is reported as a per-item failure when unavailable.
Credentials: Provide standard Google Cloud OAuth 2.0 Client credentials (Desktop Application).
Initial Authorisation (
npm run auth):Launches a local HTTP loopback server on port
58246.Generates Google OAuth consent URL with offline access (
prompt=consent).Opens the browser to authorize.
Captures authorization code and exchanges it for a permanent
refresh_tokenand initialaccess_token.Persists securely to
.classroom-server-credentials.json(gitignored).
Automated Refreshing:
index.mjschecks token expiration before every API request.When remaining validity is
< 60 seconds, or on receiving HTTP401 Unauthorized, it transparently callshttps://oauth2.googleapis.com/tokento refresh the access token.
π Installation & Setup
# 1. Clone repository
git clone https://github.com/Aaradhya-Dev-Tamrakar/google-classroom-mcp.git
cd google-classroom-mcp
# 2. Install dependencies
npm install
# 3. Authenticate with Google Classroom
npm run auth
# 4. Generate Antigravity tool schemas
npm run syncβοΈ Configuration
Antigravity & Claude Desktop Registration
Add this server block to your mcp_config.json:
{
"mcpServers": {
"classroom": {
"command": "node",
"args": [
"F:\\Aaradhya-Dev-Tamrakar\\Utility-MCPs\\google-classroom-mcp\\index.mjs"
],
"env": {
"CLASSROOM_CREDENTIALS_PATH": "C:\\Users\\Aaradhya\\.classroom-server-credentials.json",
"CLASSROOM_OAUTH_PATH": "C:\\Users\\Aaradhya\\.classroom-credentials.json"
}
}
}
}Note on Path Integrity: If legacy tools look for
F:\Aaradhya-Dev-Tamrakar\google-classroom-mcp, maintain a Windows NTFS directory junction:New-Item -ItemType Junction -Path "F:\Aaradhya-Dev-Tamrakar\google-classroom-mcp" -Target "F:\Aaradhya-Dev-Tamrakar\Utility-MCPs\google-classroom-mcp"
Dual OAuth Scope Boundary (INV-AUTH-001)
.classroom-server-credentials.jsongrants scopes strictly for Google Classroom REST API (https://www.googleapis.com/auth/classroom.*).If an agent needs to stream or download binary files attached to coursework (e.g. PDFs or archives via
https://www.googleapis.com/drive/v3/files/{id}?alt=media), it must use the credentials from the companiongdrive-mcpserver (.gdrive-server-credentials.json) which carry full Google Drive API scopes. Calling the Drive media download endpoint with Classroom-only tokens triggers HTTP 403ACCESS_TOKEN_SCOPE_INSUFFICIENT.
π Synchronization & Maintenance (sync.ps1)
This repository follows the centralized ecosystem Git and secret governance standard:
# Routine synchronization & rebase push:
.\sync.ps1
# Custom semantic commit message:
.\sync.ps1 -m "feat(classroom): add rubric parsing support"
# Refresh Antigravity schemas before pushing:
.\sync.ps1 -SyncSchemas
# Dry-run inspection (runs secret scanner without touching git state):
.\sync.ps1 -WhatIf
# Safe pull only:
.\sync.ps1 -PullOnly
# Push the current clean feature branch to its matching origin branch:
.\sync.bat -PushCurrentBranchSafety Features
Secret Scanner Guard: Blocks commits if OAuth credentials, tokens, private keys, or API secrets are staged.
Atomic conventional commit formatting: Autodetects added/modified files and formats clean commit prefixes.
Rebase-safety: Always executes
git pull --rebase --autostashbefore pushing to avoid merge bubbles.
π License
MIT License. Developed for Aaradhya's Personal Tool Ecosystem.
Available Tools
13 toolscopy_course_contentsA
Copy published topics, coursework, class materials, announcements, rubrics when supported, and Drive attachments between courses. Dry-run defaults to true. Applying requires Drive credential paths configured separately from Classroom credentials.
Inputs: driveFolderId (required), sourceCourseId (required), destinationCourseId (required), dryRun, +1 more.
get_courseA
Get detailed information about a specific course by Course ID.
Inputs: courseId (required).
get_courseworkA
Get detailed information for a specific assignment, including description, attached Drive files, YouTube links, and rubrics.
Inputs: courseId (required), courseWorkId (required).
get_submissionA
Get detailed student submission info including attached files, links, and assigned grade.
Inputs: courseId (required), courseWorkId (required), submissionId (required).
list_announcementsB
List stream announcements, notices, and updates for a course.
Inputs: courseId (required), orderBy, pageSize, announcementStates.
list_coursesA
List courses where the user is a student or teacher (e.g. active or archived classes).
Inputs: pageSize, studentId, teacherId, courseStates.
list_courseworkC
List assignments, quizzes, and coursework for a specific course.
Inputs: courseId (required), orderBy, pageSize, courseWorkStates.
list_coursework_materialsA
List materials, syllabi, lecture slides, and resources posted under Classwork.
Inputs: courseId (required), pageSize, courseWorkMaterialStates.
list_studentsB
List students enrolled in a course.
Inputs: courseId (required), pageSize.
list_submissionsB
List student submissions for a coursework (status: TURNED_IN, RETURNED, NEW, late status, assigned grade).
Inputs: courseId (required), courseWorkId (required), states, userId, +1 more.
list_teachersA
List teachers of a course.
Inputs: courseId (required), pageSize.
reclaim_assignmentB
Reclaim a turned-in student submission (unsubmit).
Inputs: courseId (required), courseWorkId (required), submissionId (required).
turn_in_assignmentC
Turn in a student submission for grading.
Inputs: courseId (required), courseWorkId (required), submissionId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 13 tools
Most tools target distinct resources and actions (courses, teachers, students, coursework, submissions, announcements, turn-in/reclaim). The main overlap is between list_coursework (assignments/quizzes) and list_coursework_materials (syllabi/resources), but descriptions adequately distinguish them.
All 13 tools follow a consistent snake_case verb_noun pattern (get_course, list_students, list_submissions, turn_in_assignment, copy_course_contents). The few multi-word verbs like turn_in and reclaim are still readable and consistent.
13 tools is well-scoped for a Classroom integration, covering courses, members, coursework, materials, submissions, and announcements without redundancy. Each tool earns its place.
Covers read operations broadly plus a few actions (turn in, reclaim, copy contents), but has notable gaps: no create/update/delete for courses, coursework, or announcements, and no grading or return-submission operations, leaving teacher-side workflows incomplete.
Maintenance
Related MCP Connectors
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Manage Google Ads from ChatGPT, Claude or any MCP client. Sign in with OAuth or use an API key.
Appreciate teammates, celebrate milestones, and run workspace ops from MCP clients via OAuth.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceThis MCP server provides comprehensive read and write access to Google Classroom, enabling management of courses, rosters, assignments, and grades. It supports full lifecycle operations for educational environments including student submissions, teacher invitations, and coursework organization.-
- FlicenseNot gradedqualityDmaintenanceIntegrates Google Classroom with LLMs and AI agents via MCP. Enables listing courses, assignments, announcements, and generating prioritized TODO summaries.1-
- AlicenseNot gradedqualityCmaintenanceEnables students to access Google Classroom through MCP, listing courses, upcoming assignments, tasks, grades, announcements, materials, topics, and teachers, with optional tools to submit or cancel submissions.MIT
- FlicenseBqualityCmaintenanceEnables teachers to manage Google Classroom courses, topics, assignments, materials, and announcements locally, including creating drafts, scheduling posts, and attaching files via MCP.211-