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 for students

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.