Skip to main content
Glama

Gradescope MCP

A lightweight, read-only MCP server for Gradescope. It provides student-focused access to courses, assignments, deadlines, submission history, and uploaded submission files through a small set of MCP tools.

The server is built on gradescopeapi and does not expose Gradescope write operations. Downloading a submitted file only creates a local copy; it does not modify anything on Gradescope.

Features

  • gradescope_list_courses — courses visible to the account

  • gradescope_list_assignments — exact assignment dates, status, and grades for one course

  • gradescope_upcoming_assignments — upcoming work across student courses, sorted by due time

  • gradescope_list_submissions — the authenticated student's submitted assignments

  • gradescope_get_submission_files — filenames and metadata for the student's own uploaded files

  • gradescope_download_submission_file — download one of those files to the local machine

The server does not upload submissions or expose grading, roster management, extension management, or other Gradescope write operations.

Gradescope does not provide an official public student API. gradescopeapi works by parsing Gradescope pages, so site changes can occasionally require a library update.

Related MCP server: Canvas MCP Server

Requirements

  • Python 3.11+

  • uv

  • A Gradescope email/password login

If you normally enter Gradescope only through university SSO, create a native Gradescope password using Gradescope's password-reset flow. Do not store your university SSO password here.

Setup

git clone https://github.com/YeetingWaterbottle/gradescope-mcp.git
cd gradescope-mcp
uv sync --no-dev

Create a local credential file from the example:

cp .env.example .env

On PowerShell:

Copy-Item .env.example .env

Edit .env:

GRADESCOPE_EMAIL="student@example.com"
GRADESCOPE_PASSWORD="your-native-gradescope-password"

.env is ignored by Git.

Run the server:

uv run gradescope-mcp

When .env is in the current working directory it is loaded automatically. You can instead keep credentials elsewhere:

uv run gradescope-mcp --env-file /absolute/path/to/gradescope.env

PowerShell example:

uv run gradescope-mcp --env-file C:\Users\you\.config\gradescope.env

Environment variables supplied by the parent process take precedence over values in the dotenv file.

Run directly from GitHub

Run the server directly from GitHub with uvx:

uvx --from git+https://github.com/YeetingWaterbottle/gradescope-mcp.git gradescope-mcp --env-file /absolute/path/to/gradescope.env

MCP client configuration

The exact UI varies by client. A generic stdio configuration using the public GitHub repository is:

{
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/YeetingWaterbottle/gradescope-mcp.git",
    "gradescope-mcp",
    "--env-file",
    "/absolute/path/to/gradescope.env"
  ]
}

On Windows, use normal JSON escaping for the credential path, for example "C:\\Users\\you\\.config\\gradescope.env".

examples/chat-on-steroids.json contains the same configuration as a reusable template. Replace the credential-file path with an absolute path on your machine.

Tools

gradescope_list_courses

Returns courses grouped by role (student / instructor) with Gradescope course IDs and term information.

gradescope_list_assignments

Input:

{"course_id": "123456"}

Returns assignment ID, name, release time, due time, late due time, status, grade, and maximum grade.

The status field is Gradescope's own displayed status. The MCP does not reinterpret it. If Gradescope displays Submitted, the tool returns Submitted.

gradescope_upcoming_assignments

Input:

{"days": 14}

Aggregates assignments from all student courses and returns those due within the requested window, sorted by exact due timestamp. The accepted range is 1–365 days.

gradescope_list_submissions

Optionally accepts a course_id. If omitted, it lists the authenticated student's submissions across all student courses. The result includes the assignment and submission IDs needed to inspect attached files.

gradescope_get_submission_files

Given a course, assignment, and submission ID, returns safe file metadata such as filename, type, page count, and a short file_ref.

Gradescope's temporary signed storage URLs are deliberately kept inside the MCP server rather than exposed in model context.

PDF/image-style homework submissions and Gradescope text/source-file submissions are supported when Gradescope exposes them to the authenticated student. Online-form assignments naturally return an empty file list.

gradescope_download_submission_file

Downloads one file identified by file_ref to a directory on the machine running the MCP server. It never changes Gradescope. By default it refuses to overwrite an existing local file.

Read-only design

The project exposes only student-focused read operations against Gradescope. Instructor-oriented and write operations such as roster management, grading, extensions, assignment configuration, and submission uploads are not included.

Development

uv sync --all-groups
uv run pytest

CI runs on Linux, macOS, and Windows with Python 3.11–3.13.

Security

  • Never commit .env.

  • Prefer a Gradescope-specific/native password rather than reusing an important password.

  • Keep credential files readable only by your user where your OS supports that.

  • The MCP exposes only read operations against Gradescope, but the credentials still represent your account and should be protected accordingly.

License

MIT. See LICENSE.

Available Tools

6 tools
gradescope_download_submission_fileA
Idempotent

Download one of the authenticated student's own submitted files locally.

This does not modify Gradescope. It creates a file on the machine running the MCP server. file_ref comes from gradescope_get_submission_files.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_refYes
course_idYes
overwriteNo
assignment_idYes
submission_idYes
destination_dirYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description usefully clarifies that no Gradescope state is modified and that the side effect is a local file on the MCP server host — context that reconciles the contradictory-looking readOnlyHint=false with destructiveHint=false. It omits, however, what happens when the destination file already exists, which is exactly what the undocumented 'overwrite' parameter controls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the purpose, then the side-effect clarification, then the parameter provenance hint. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and the local-vs-remote side effect is covered. But for a file-writing tool the description leaves the overwrite collision behavior and the three ID parameters unexplained, which is a real gap at 0% schema coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across six parameters, so the description carries the full burden and only partially does so: it explains the provenance of file_ref and implies destination_dir, but says nothing about course_id/assignment_id/submission_id or the overwrite flag's behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Download) and resource (the authenticated student's own submitted file) with the scope qualifier 'own', which distinguishes it from sibling gradescope_get_submission_files, which lists files rather than fetching one. The final sentence further routes the agent to the right sibling for obtaining file_ref.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It tells the agent where file_ref comes from ('comes from gradescope_get_submission_files'), which is the key precondition for calling this tool. It stops short of stating when not to use it (e.g., bulk download vs single file) but gives clear context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

gradescope_get_submission_filesA
Read-onlyIdempotent

Return safe metadata for files in one of the authenticated student's submissions.

Temporary signed Gradescope/S3 URLs are intentionally not returned. Use gradescope_download_submission_file to retrieve a file.

ParametersJSON Schema
NameRequiredDescriptionDefault
course_idYes
assignment_idYes
submission_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: signed Gradescope/S3 URLs are intentionally suppressed, which explains an otherwise surprising absence in the response.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, no filler, with the capability stated first and the redirect to the download sibling second. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so explaining return fields is not required, and the description correctly characterizes the payload as safe metadata plus what is excluded. However, for a tool requiring three opaque IDs with no schema descriptions, the definition leaves the agent without enough to supply correct identifiers.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for all three required parameters (course_id, assignment_id, submission_id), and the description does not explain any of them — not their format, where to obtain them, or how they compose. Only the vague ownership scoping ('authenticated student's submissions') hints at semantics, so it fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (get/return) and resource (files in a submission) with a clear scope qualifier ('one of the authenticated student's submissions'). It implicitly separates itself from gradescope_download_submission_file, which is the tool that actually moves bytes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: list metadata here, and use gradescope_download_submission_file to retrieve an actual file. It also frames the scoping constraint (only the authenticated student's own submissions), though it does not state exclusions for other list tools like gradescope_list_submissions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

gradescope_list_assignmentsB
Read-onlyIdempotent

List assignments for one Gradescope course.

status is the exact status parsed from Gradescope's student course table. It is intentionally not reinterpreted into a separate submitted/not-submitted flag.

ParametersJSON Schema
NameRequiredDescriptionDefault
course_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered without the description. The description does add genuine behavioral context by explaining that the `status` value is passed through exactly as parsed and deliberately not normalized into submitted/not-submitted — useful fidelity information an agent would otherwise guess wrong about.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs that are front-loaded with the primary action; no filler or repetition. The second paragraph is arguably tangential for a listing tool (it describes a returned field rather than a call-time concern), which is the only thing keeping it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the return shape need not be explained, and annotations cover the operation's safety semantics. The gap is the undocumented required course_id and the absence of any routing against gradescope_upcoming_assignments, so an agent has enough to call it but not enough to always pick it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the single required parameter course_id is completely undocumented in structured fields, and the description does not compensate — it never states the expected format or source of a course_id. Paragraph two discusses a `status` field that is not even a parameter of this tool, adding no parameter-level clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (assignments) scoped to one Gradescope course, so the core purpose is unambiguous. It does not, however, differentiate itself from the sibling gradescope_upcoming_assignments, leaving the agent to infer the boundary between a full listing and an upcoming-only listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance, no prerequisites, and no mention of the sibling tools. The only hint is the implicit 'for one Gradescope course' scoping, which the agent must extrapolate into usage conditions on its own.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

gradescope_list_coursesA
Read-onlyIdempotent

List Gradescope courses grouped by student/instructor role.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, covering the safety profile. The description adds the role-grouping behavior, which is a useful output-shape hint, but nothing about auth requirements or API limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence with zero waste, and the grouping behavior is stated up front. Nothing to trim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value detail is unnecessary, and there are no parameters to document. A brief note on typical workflow position would round it out, but it is sufficient for a no-arg list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate beyond the role-grouping note.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (Gradescope courses) plus a scope detail (grouped by student/instructor role). This distinguishes it from assignment/submission siblings by resource, though it doesn't explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the object being listed – an agent would infer this is the entry point before listing assignments or submissions. No explicit when/when-not guidance or alternatives are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

gradescope_list_submissionsA
Read-onlyIdempotent

List the authenticated student's own submitted assignments.

If course_id is omitted, submissions from all student courses are returned. This does not download submitted files.

ParametersJSON Schema
NameRequiredDescriptionDefault
course_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds useful scope context: results are limited to the caller's own submissions, span all courses when no course_id is given, and exclude file content.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero filler, with the core action first and the two clarifying constraints following. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description covers scope and the non-download boundary. It does not mention result volume or pagination behavior for a list tool with openWorldHint, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the only parameter is undocumented in the schema, so the description must carry the meaning. It does: omitting course_id changes the result set to all student courses, which is more than the schema's bare default=null conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List ... submitted assignments') and scopes it to the authenticated student's own submissions. The closing note that it does not download files distinguishes it from the download/get_submission_files siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the course_id omission case (all courses returned) and signals the file-download boundary against siblings. It does not explicitly say when to prefer this over gradescope_list_assignments, but the read-only listing context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

gradescope_upcoming_assignmentsB
Read-onlyIdempotent

Return upcoming assignments across all student courses, sorted by due time.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this a safe, idempotent, non-destructive read, so the safety burden is lifted. The description adds the sort order and all-courses scope, but says nothing about pagination, result limits, or how the time window is bounded.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words. It is tight, though the same brevity leaves the 'days' parameter unaddressed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. However the lone parameter is undocumented in both schema and description, and there is no routing guidance against the sibling listing tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single 'days' parameter has 0% schema description coverage and a default of 14, yet the description never explains it. The word 'upcoming' gestures at a window but leaves the parameter's meaning (lookahead horizon?) entirely to inference.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Return'), resource ('upcoming assignments'), scope ('across all student courses') and ordering ('sorted by due time'). This scope reasonably separates it from gradescope_list_assignments, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word 'upcoming' and 'across all student courses' imply the time-window/all-courses use case versus a course-scoped listing, but there is no explicit when-to-use or when-not-to-use guidance and no alternative is referenced.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.1.0
    • First observedgradescope_download_submission_file
    • First observedgradescope_get_submission_files
    • First observedgradescope_list_assignments
    • First observedgradescope_list_courses
    • First observedgradescope_list_submissions
    • First observedgradescope_upcoming_assignments

TDQS

A3.7/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a distinct resource or action: listing courses, assignments, upcoming assignments, submissions, getting file metadata, and downloading a file. Descriptions clarify boundaries (e.g., list_assignments vs list_submissions), leaving no overlapping purposes.

Naming Consistency4/5

All tools use a consistent gradescope_ prefix and snake_case. However, most list operations start with list_, while gradescope_upcoming_assignments breaks that pattern by not including the list_ verb, a minor deviation.

Tool Count5/5

Six tools are well-scoped for a read-focused Gradescope student workflow, with each tool earning its place. No bloated or missing tools at the set level.

Completeness4/5

The set covers the core student journey: viewing courses, assignments, upcoming deadlines, submissions, and downloading submitted files. Minor gaps exist, such as no tool for detailed assignment or course metadata, but these are manageable workarounds.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    Enables students to locally archive and read their own course assignments, deadlines, original and graded PDFs, rubric feedback, comments, and submission history through a read-only MCP connection. Supports course and assignment summaries, document reading with OCR, change tracking, and scheduled syncs.
    12
    MIT