google-classroom-mcp
Provides read-only access to Google Classroom, with tools for listing courses, retrieving course details, viewing coursework and due dates, checking upcoming assignments across active courses, reading announcements, and pulling teacher and student rosters plus submission states and grades for 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 what assignments are due this week across my classes?"
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-mcp
Read-only Google Classroom access for DeepSeek — and any other MCP-capable agent.
This is a Model Context Protocol server that turns your Google Classroom account into tools an LLM can call: courses, coursework, due dates, announcements, rosters and student submissions.
DeepSeek's API does not speak MCP by itself, so point an MCP-capable harness at this server
and select a DeepSeek model there. Works with DeepSeek Harness,
opencode, Claude Desktop, Cursor, or the bundled example agent (examples/deepseek_agent.py)
that calls the DeepSeek API directly.
Tools
Tool | Returns |
| Courses you teach or attend (id, name, section, room, state, link) |
| One course with description and enrollment code |
| Assignments, quizzes, questions and materials, with due dates |
| Upcoming coursework across all active courses, sorted by due date |
| Recent announcements in a course |
| Teacher roster (name, email) |
| Student roster (name, email) |
| Submission state and grades for one assignment |
Every tool is read-only. The server cannot create, edit or delete anything in Classroom.
Related MCP server: Google Classroom MCP
Setup
1. Create a Google OAuth client
Open the Google Cloud Console and create a project.
APIs & Services → Library: enable the Google Classroom API.
APIs & Services → OAuth consent screen: choose External, fill in the required fields, and add your own Google account under Test users. In Testing mode Google expires refresh tokens after 7 days. For a durable personal setup, click Publish app (no verification needed for personal use; you will see an "unverified app" warning during sign-in).
APIs & Services → Credentials → Create credentials → OAuth client ID: application type Desktop app, then download the JSON.
Save the file as
~/.google-classroom-mcp/client_secret.json(Windows:%USERPROFILE%\.google-classroom-mcp\client_secret.json), or setCLASSROOM_MCP_CLIENT_SECRET_FILEto its path.
2. Install
git clone https://github.com/praisethefacts/google-classroom-mcp
cd google-classroom-mcp
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .3. Sign in once
google-classroom-mcp-authA browser window opens; grant the read-only scopes. The refreshable token is cached at
~/.google-classroom-mcp/token.json.
4. Connect an MCP host
opencode (~/.config/opencode/opencode.json):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"google-classroom": {
"type": "local",
"command": ["google-classroom-mcp"],
"enabled": true
}
}
}Claude Desktop / Cursor (claude_desktop_config.json or .cursor/mcp.json):
{
"mcpServers": {
"google-classroom": {
"command": "google-classroom-mcp"
}
}
}If the host cannot find google-classroom-mcp, use the absolute path to the script inside
your venv (Windows: ...\.venv\Scripts\google-classroom-mcp.exe).
DeepSeek Harness (dsh)
DeepSeek Harness installs integrations as
plugin bundles. Use the ready-made
dsh-plugin-google-classroom
bundle: open Plugins in DSH and install
github:praisethefacts/dsh-plugin-google-classroomor skip the bundle and load the overlay directly:
dsh web --patch examples/dsh-overlay.cordis.ymlBoth run the server with uvx (no separate pip install needed), so only steps 1–3 above
still apply — the Google OAuth client and one-time sign-in. Copy the overlay's insert row
into $DSH_HOME/profiles/<name>/cordis.patch.yml to keep it across runs. DSH scrubs
credential-looking environment variables before launching stdio servers, so keep the default
file-based token at ~/.google-classroom-mcp/token.json rather than CLASSROOM_MCP_* env
vars.
5. Optional: run it from a plain DeepSeek script
pip install -e ".[example]"
set DEEPSEEK_API_KEY=sk-... # PowerShell: $env:DEEPSEEK_API_KEY="sk-..."
python examples/deepseek_agent.py "What do I have due this week?"The example starts the MCP server, converts its tools into OpenAI-style function schemas,
and lets deepseek-chat call them in a loop.
Environment variables
Variable | Purpose |
| Override the config directory (default |
| Path to the OAuth client JSON |
| Path to the cached token (default |
| Inline OAuth client instead of a file |
| Inline token JSON, for hosted/remote setups |
| Used only by |
Security
Only read-only Classroom scopes are requested (see
classroom_mcp/auth.py).The token lives outside the repository and is git-ignored. Never commit it.
Revoke access anytime at myaccount.google.com/permissions.
Development
pip install -e ".[dev]"
pytest -qLicense
Available Tools
8 toolsget_courseA
Get one course by id, including description and enrollment code.
Args: course_id: Course id from list_courses (numeric string).
Inputs: course_id (required).
list_announcementsC
Recent announcements for a course.
Args: course_id: Course id from list_courses. limit: Maximum number of announcements to return.
Inputs: course_id (required), limit.
list_coursesA
List Google Classroom courses for the signed-in account (teacher or student).
Args: course_states: Optional state filter. Defaults to ["ACTIVE"]. Other values: "ARCHIVED", "PROVISIONED", "DECLINED", "SUSPENDED"; pass several to include multiple states.
Inputs: course_states.
list_courseworkA
List coursework (assignments, quizzes, questions, materials) for a course.
Args: course_id: Course id from list_courses. states: Optional state filter. Defaults to ["PUBLISHED"]; can include "DRAFT" or "DELETED". limit: Maximum number of items to return.
Inputs: course_id (required), limit, states.
list_due_soonB
Upcoming coursework across all active courses, sorted by due date.
Args: days: Look-ahead window in days (default 7). include_overdue: Also include items whose due date already passed.
Inputs: days, include_overdue.
list_studentsA
Student roster (names and emails) for a course.
Args: course_id: Course id from list_courses.
Inputs: course_id (required).
list_submissionsB
Submission state and grades for one assignment.
Args: course_id: Course id from list_courses. coursework_id: Coursework id from list_coursework. user_id: "me" (default) for the signed-in student's submission, a student's numeric id/email, or "-" for all students (teachers only). limit: Maximum number of submissions to return.
Inputs: course_id (required), coursework_id (required), limit, user_id.
list_teachersA
Teacher roster (names and emails) for a course.
Args: course_id: Course id from list_courses.
Inputs: course_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct resource and scope: courses, single course, coursework, due-soon across courses, announcements, teachers, students, and submissions. The only near-overlap is list_coursework vs list_due_soon, but the descriptions clearly distinguish per-course listing from cross-course due-date aggregation.
Consistent snake_case verb_noun pattern throughout (list_courses, get_course, list_coursework, etc.). The single 'get_course' appropriately pairs with 'list_courses' for singular retrieval, so the convention is predictable.
Eight tools is well-scoped for a read-oriented Classroom client. Each tool earns its place by covering a distinct entity or query, with no redundancy or filler.
Read coverage is solid (courses, coursework, submissions, announcements, rosters), but the surface is entirely read-only. Common Classroom mutations—creating courses/coursework, submitting assignments, grading, posting announcements, or updating/deleting—are absent, creating dead ends for write-oriented workflows.
Maintenance
Related MCP Connectors
Read-only Google Search Console and Google Analytics for AI agents.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
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.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceIntegrates Google Classroom with LLMs and AI agents via MCP. Enables listing courses, assignments, announcements, and generating prioritized TODO summaries.1-
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to read Google Classroom data—including coursework, submissions, announcements, and Drive attachments—through a remote, OAuth-protected MCP server with interactive Google sign-in.-
- FlicenseAqualityCmaintenanceEnables Claude to read and write Google Classroom data, including courses, coursework, materials, announcements, rosters, submissions, and Drive attachment contents.15-
- AlicenseAqualityBmaintenanceEnables students to query Google Classroom courses, pending assignments, grades, announcements, and materials, and to attach files or submit assignments, with support for multiple Google accounts from any MCP client.9MIT