Gradescop is a local, read-only Gradescope MCP server that archives your coursework and lets you query it from Codex.
Connect & check status: connect opens a browser for interactive sign-in; connection_status shows stored health, sync freshness, and archive location.
Sync your data: sync asynchronously refreshes courses, attachments, submissions, rubrics, and annotations (optionally scoped by course/assignment); sync_status reports job progress and gaps.
Browse courses & assignments: list_courses lists courses across terms; list_assignments shows status, scores, and visible deadlines with filters (status, search, due-date range, pagination).
Inspect assignment detail: get_assignment returns metadata, material file IDs, and completeness; get_submission returns submitted answers, page mappings, and history.
Read feedback: get_feedback returns visible comments, annotations, and applied rubric items (with applied_only=false to see all visible rubric items).
Read original documents: read_document extracts page-level text from preserved PDFs, with optional local OCR for scanned pages.
Search & track changes: search_coursework searches titles, feedback, and full document text; get_changes lists archive changes since a timestamp.
All operations are read-only and local—never submitting work, editing answers, or requesting regrades.
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., "@Gradescop refresh Gradescope and show my upcoming assignment deadlines"
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.
Get started · Architecture · Roadmap · Test coverage · Contribute
Gradescop is a local, read-only Gradescope MCP (Model Context Protocol) server and Codex plugin for students. Archive assignments, deadlines, original and graded PDFs, released rubric feedback, comments, annotations, and accessible submission history across courses.
Preview release: macOS only. Independent project; not affiliated with Gradescope, Turnitin, or OpenAI. Each user signs in to their own account. This repository contains code and synthetic tests, not account data.
Requires macOS, Node.js 22.13 or newer, Google Chrome, and Poppler (pdftotext and pdftoppm on PATH). Optional OCR requires Tesseract. With Homebrew, install these using brew install node poppler and optionally brew install tesseract; install Google Chrome separately.
git clone https://github.com/duhaolei43-source/gradescope-mcp.git gradescope-personal
cd gradescope-personal
npm ci
node scripts/configure.mjs
npm test
npm run connect
npm run syncSign in yourself in the browser opened by connect; institutional SSO/MFA may require interaction. Never place your password in a prompt, repository, command, or environment variable. A blocked SSO flow is unsupported until verified; do not bypass it.
Related MCP server: moodle-cli
From the cloned directory, register the server with the Codex CLI:
codex mcp add gradescope --env NODE_NO_WARNINGS=1 --env "PATH=$PATH" -- "$(command -v node)" "$PWD/src/server.mjs"Open a new local Codex task. Ask: “Refresh Gradescope and show upcoming assignments,” or “Read all released feedback on this assignment.” Other STDIO MCP clients can use the generated .mcp.json configuration. Keep this checkout in place: configuration points at it.
This command registers MCP tools; it does not install a plugin card in the + picker. For plugin packaging, this repository includes .codex-plugin/plugin.json, the generated .mcp.json, an icon, and skills/gradescope/SKILL.md. Use Codex's plugin-creator workflow to register the clone in your personal marketplace, validate it, and install gradescope-personal@personal. A one-command public marketplace installer is planned. Do not install both registrations simultaneously under the same server name.
Twelve tools: connection_status, connect, sync, sync_status, list_courses, list_assignments, get_assignment, get_submission, get_feedback, read_document, search_coursework, get_changes.
A full sync includes older courses. It reconciles dashboard counts and reports retrieval failures. Query summaries first, then relevant questions and PDF pages. Original files retain every page. Rubric point_effect accounts for positive and negative scoring. OCR results require verification.
Use node src/cli.mjs status for cached health. A saved session is not proof that login still works. Expired sessions require npm run connect. Sync is asynchronous through MCP; wait for sync_status before reporting current data.
Scheduling is opt-in and is not created by installation. Ask Codex: “Run a full Gradescope sync daily at 9 AM local time, including older courses. Notify only on changed assignments, deadlines, submissions, grades or feedback, failures, or required login. Stay quiet when unchanged.” The host and Codex must be available for local scheduled execution. Never use GitHub Actions to synchronize your actual coursework.
The archive is in ~/Library/Application Support/GradescopePersonal, outside this repository. Sessions use AES-256-GCM with a macOS Keychain key. Files are created with owner-only permissions. PDF/text coursework itself is not encrypted by this application. Protect your OS account and disk. Retrieved text enters your MCP client's conversation when requested. No hosted service receives the archive from this code.
The adapter reads account-visible student pages and embedded viewer data. It never submits work, starts assessments, activates attempts, edits answers, or sends regrade requests. Reads may record a view on Gradescope. Hidden grades, unopened timed content, unavailable templates, and unapproved external file hosts cannot be promised. Layout changes can break extraction. Support is currently limited to www.gradescope.com and observed upload hosts.
See public plan, approach comparison, security guidance, and contributing.
flowchart LR
A[Your Gradescope account] -->|Interactive sign-in| B[Chrome session]
B --> C[Student page reader]
C --> D[(Local archive)]
D --> E[12 MCP tools]
E --> F[Codex conversation]
K[macOS Keychain] -. protects session .-> B
C --> G[Coverage and change checks]
G --> DYou ask | Gradescop retrieves |
What is due? | Assignment status and timezone-aware deadlines |
Why did I lose points? | Released rubric items, scoring direction, comments and annotations |
Show the original work | Preserved PDF files and page-level text |
What changed? | Changes since the previous sync, with explicit retrieval failures |
Run npm run smoke after installing Poppler. Tests use synthetic records and a generated PDF, isolated temporary archives and local MCP processes. No login or private coursework is needed. See the test matrix and limits.
Released under the MIT license. Dependency licenses remain their respective authors' property. Gradescope and Codex names identify compatible products; this project is independent.
Open a private browser for interactive Gradescope login. Never pass credentials to this tool.
Inputs: no named parameters.
Check stored connection health, synchronization freshness and shared local archive location. This does not verify a live login.
Inputs: no named parameters.
Read assignment metadata, material file IDs, original date labels and completeness. Refresh with sync when live verification is needed.
Inputs: assignment_id (required).
Read compact archive changes since a timestamp. Complete data remains in the archive; changes are not a substitute for coverage checks.
Inputs: since (required), limit, offset.
Read all visible comments and annotations for selected questions. Applied rubric items are returned by default; applied_only=false includes all visible rubric items. Never interpret unapplied items as deductions.
Inputs: assignment_id (required), limit, offset, question_id, +1 more.
Read submitted answers, page mappings, history and document references for an assignment or specific archived attempt.
Inputs: assignment_id (required), submission_id.
List assignment status, scores and effective visible deadlines. Time remaining is calculated now; fetched_at shows source freshness. Paginate to retrieve all.
Inputs: limit, query, offset, status, +3 more.
List all discovered courses across terms. Includes discovery counts, access restrictions and verification time.
Inputs: limit, offset.
Read original document text by page. The path points to the preserved original. Optional local OCR helps scanned pages; OCR transcription is unverified.
Inputs: document_id (required), ocr, page, page_count.
Search locally preserved assignment titles, submission feedback and full document text. Returns short evidence snippets and IDs; retrieve original documents for full context.
Inputs: query (required), limit, offset.
Refresh Gradescope course listings, attachments, submissions, visible rubric and annotations. Runs asynchronously; poll sync_status. Omitting filters checks all courses, including older courses.
Inputs: course_id, assignment_id.
Read a background synchronization job. Report partial failures and missing coverage explicitly.
Inputs: job_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 12 tools
Most tools target a distinct resource+action (courses, assignments, submissions, feedback, documents, changes). The only mild overlap is between connect/connection_status (live login vs stored health) and sync/sync_status (trigger vs poll), but descriptions explicitly differentiate these cases. An agent can reliably pick the right tool in nearly all situations.
All names are snake_case, and the majority follow a verb_noun pattern (list_courses, get_assignment, get_submission, read_document, search_coursework, get_changes). A few are bare verbs or noun_status forms (connect, sync, connection_status, sync_status), which are minor deviations from the dominant convention but still readable and consistent.
Twelve tools is well within the ideal 3-15 range and each one earns its place: connection, sync lifecycle, and the read paths for courses, assignments, submissions, feedback, documents, and archive changes. No redundant or filler tools are present.
For a read/archival surface the coverage is strong: connection, sync, discovery, assignments, submissions, feedback, documents, search, and change tracking are all present. Minor gaps exist (no explicit course-detail tool or standalone rubric-metadata tool), but these are workable around via get_assignment and get_feedback.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Read your plat.plus courses, tasks, course pages, sessions, files and messages. Read-only.
Read-only flight-training records for CFIs, students and schools: syllabus, schedule, FAR/AIM.
Read-only MCP over your Excel or Airtable plus the PDFs beside it, joined as one relational dataset.
