Gradescope MCP Server

An MCP (Model Context Protocol) server for Gradescope that exposes course management, grading, regrade review, statistics, and AI-assisted grading workflows to MCP clients.

The server is designed for instructors and TAs who want to use AI agents with real Gradescope data while keeping write operations gated behind explicit confirmation.

This repository also includes a reusable local skill at skills/gradescope-assisted-grading/SKILL.md for human-approved grading workflows.

Current Status

• 34 MCP tools
• 3 MCP resources
• 7 MCP prompts
• 30 automated tests
• Python 3.10+
• Package manager: uv

What The Project Provides

Read-oriented workflows

• Course discovery and assignment listing
• Assignment outline parsing for online and scanned-PDF assignments
• Roster inspection with a custom HTML parser
• Submission listing for multiple assignment types
• Grading progress, rubric context, answer groups, regrades, and statistics
• Workflow helpers that cache grading artifacts and answer-key snapshots to /tmp

Write-oriented workflows

• Uploading submissions
• Setting student extensions
• Modifying assignment dates
• Renaming assignments
• Applying grades
• Creating, updating, and deleting rubric items
• Batch grading answer groups

All write-capable tools are preview-first and require confirm_write=True before any mutation is executed.

Tool Inventory

Core

Instructor / TA Management

Grading Read

Grading Write

AI-Assisted / Workflow Helpers

Answer Groups

Regrades

Statistics

Resources

Prompts

Architecture

Entry points

• src/gradescope_mcp/__main__.py: loads .env, configures logging, runs the FastMCP server
• src/gradescope_mcp/server.py: registers all tools, resources, and prompts

Authentication

• src/gradescope_mcp/auth.py: maintains a singleton GSConnection
• Credentials come from GRADESCOPE_EMAIL and GRADESCOPE_PASSWORD
• .env is loaded automatically when starting with python -m gradescope_mcp

Tool modules

• tools/courses.py: course listing and roster parsing
• tools/assignments.py: assignment listing and assignment write operations
• tools/submissions.py: uploads, submission listing, grader discovery
• tools/extensions.py: extension reads and writes
• tools/grading.py: outline parsing, score exports, grading progress
• tools/grading_ops.py: grading context, writes, rubric CRUD, navigation
• tools/grading_workflow.py: /tmp artifacts, answer keys, readiness, page caching, smart reading
• tools/answer_groups.py: AI-assisted answer-group inspection and batch writes
• tools/regrades.py: regrade listing and detail inspection
• tools/statistics.py: assignment statistics
• tools/safety.py: preview-first confirmation helpers for mutations

Important Behavior And Constraints

Write safety

• Mutating tools return a preview when confirm_write=False
• The actual change only happens with confirm_write=True
• Rubric edits and deletions can cascade to existing grades
• tool_grade_answer_group can affect many submissions at once and needs extra care

Submission IDs

• tool_get_assignment_submissions returns assignment-level Global Submission IDs
• Grading tools require Question Submission IDs
• Use tool_list_question_submissions, tool_get_next_ungraded, or grading context tools to get the correct IDs

Scoring direction

• Gradescope questions may be positive or negative scoring
• Rubric weights are stored as positive numbers in both modes
• The scoring mode determines whether a checked rubric item adds or deducts points

Scanned / handwritten assignments

• Structured reference answers are often unavailable
• This is expected, not necessarily a parsing failure
• The workflow helpers are built to use crop regions, full pages, adjacent pages, rubric text, and user-provided reference notes

Quick Start

1. Prerequisites

• Python 3.10+
• uv

2. Install

git clone https://github.com/Yuanpeng-Li/gradescope-mcp.git
cd gradescope-mcp
cp .env.example .env

Then edit .env with your Gradescope credentials.

3. Run locally

uv run python -m gradescope_mcp

4. Configure an MCP client

Example client configuration:

{
  "mcpServers": {
    "gradescope": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/gradescope-mcp",
        "python",
        "-m",
        "gradescope_mcp"
      ],
      "env": {
        "GRADESCOPE_EMAIL": "your_email@example.com",
        "GRADESCOPE_PASSWORD": "your_password"
      }
    }
  }
}

5. Debug with MCP Inspector

npx @modelcontextprotocol/inspector uv run python -m gradescope_mcp

6. Run tests

uv run pytest -q

Assisted Grading Skill

The repository includes one project-local skill:

• gradescope-assisted-grading

It is intended for:

• preview-first grading
• rubric review before mutation
• scanned exam grading
• answer-group triage
• explicit human approval before any grade write

Install the skill locally

mkdir -p .agent/skills
ln -s "$(pwd)/skills/gradescope-assisted-grading" .agent/skills/gradescope-assisted-grading

If you prefer copying:

mkdir -p .agent/skills
cp -R skills/gradescope-assisted-grading .agent/skills/

Verify installation

ls .agent/skills/gradescope-assisted-grading
cat .agent/skills/gradescope-assisted-grading/SKILL.md

Invoke it from a client with:

• Use the gradescope-assisted-grading skill
• $gradescope-assisted-grading

Project Structure

gradescope-mcp/
├── .env.example
├── AGENT.md
├── DEVLOG.md
├── OPERATIONS_LOGS/
│   └── RECORDS.md
├── README.md
├── pyproject.toml
├── skills/
│   └── gradescope-assisted-grading/
│       └── SKILL.md
├── src/
│   └── gradescope_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── auth.py
│       ├── server.py
│       └── tools/
│           ├── __init__.py
│           ├── answer_groups.py
│           ├── assignments.py
│           ├── courses.py
│           ├── extensions.py
│           ├── grading.py
│           ├── grading_ops.py
│           ├── grading_workflow.py
│           ├── regrades.py
│           ├── safety.py
│           ├── statistics.py
│           └── submissions.py
└── tests/
    ├── test_answer_groups.py
    ├── test_assignments_and_grading_ops.py
    ├── test_extensions_and_answer_key.py
    ├── test_grading_workflow.py
    └── test_write_safety.py

Development Notes

• AGENT.md summarizes the current architecture and maintenance expectations
• DEVLOG.md records the implementation history
• OPERATIONS_LOGS/RECORDS.md is the mutation log template for real-account testing

Known Caveats

1. Gradescope behavior differs across assignment types; several tools rely on HTML parsing or reverse-engineered endpoints.
2. Roster parsing uses a custom parser because the upstream library parser is unreliable when sections are present.
3. Some assignment types do not support the extensions API even for staff users.
4. Scanned assignments usually do not provide a structured answer key.
5. Question grading requires Question Submission IDs, not assignment-level Global Submission IDs.