Gradescope MCP
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., "@Gradescope MCPwhat assignments do I have due in the next 7 days?"
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.
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 accountgradescope_list_assignments— exact assignment dates, status, and grades for one coursegradescope_upcoming_assignments— upcoming work across student courses, sorted by due timegradescope_list_submissions— the authenticated student's submitted assignmentsgradescope_get_submission_files— filenames and metadata for the student's own uploaded filesgradescope_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.
gradescopeapiworks by parsing Gradescope pages, so site changes can occasionally require a library update.
Related MCP server: Canvas MCP Server
Requirements
Python 3.11+
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-devCreate a local credential file from the example:
cp .env.example .envOn PowerShell:
Copy-Item .env.example .envEdit .env:
GRADESCOPE_EMAIL="student@example.com"
GRADESCOPE_PASSWORD="your-native-gradescope-password".env is ignored by Git.
Run the server:
uv run gradescope-mcpWhen .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.envPowerShell example:
uv run gradescope-mcp --env-file C:\Users\you\.config\gradescope.envEnvironment 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.envMCP 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 pytestCI 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 toolsgradescope_download_submission_fileAIdempotent
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.
| Name | Required | Description | Default |
|---|---|---|---|
| file_ref | Yes | ||
| course_id | Yes | ||
| overwrite | No | ||
| assignment_id | Yes | ||
| submission_id | Yes | ||
| destination_dir | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_filesARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | Yes | ||
| assignment_id | Yes | ||
| submission_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_assignmentsBRead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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_coursesARead-onlyIdempotent
List Gradescope courses grouped by student/instructor role.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_submissionsARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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_assignmentsBRead-onlyIdempotent
Return upcoming assignments across all student courses, sorted by due time.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
6 tool updates
v0.1.0- First observed
gradescope_download_submission_file - First observed
gradescope_get_submission_files - First observed
gradescope_list_assignments - First observed
gradescope_list_courses - First observed
gradescope_list_submissions - First observed
gradescope_upcoming_assignments
TDQS
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Read-only IELTS and CELPIP question banks, learner practice, progress, scores, and feedback.
- uNotesOAuthnet.unotes
Search university course materials, your flashcards, quizzes, streak and quota. All tools read-only.
- PAVEOAuthcom.pavecfi
Read-only flight-training records for CFIs, students and schools: syllabus, schedule, FAR/AIM.
Read-only access to your Citlyze workspace: AI search visibility, citations, and recommendations.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables read-only querying of Moodle as a student, including courses, assignments, grades, forums, and files, using a personal web services token.11-
- FlicenseBqualityCmaintenanceProvides read-only access to Canvas LMS data including courses, assignments, grades, and deadlines through 23 structured tools.23-
- FlicenseNot gradedqualityBmaintenanceEnables a study assistant to explain topics, build study plans, and generate revision checklists, with read-only access to course outline and status resources.-
- AlicenseAqualityCmaintenanceEnables 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.12MIT