README.md
Interact with Gradescope for course management, grading, and regrade reviews.
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/gradescope-mcp
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
| Tool | Description | Access |
|---|---|---|
tool_list_courses |
List all courses grouped by role | All |
tool_get_assignments |
List assignments for a course | All |
tool_get_assignment_details |
Get one assignment's details | All |
tool_upload_submission |
Upload files to an assignment | All |
Instructor / TA Management
| Tool | Description |
|---|---|
tool_get_course_roster |
Full roster grouped by role |
tool_get_extensions |
View assignment extensions |
tool_set_extension |
Add or update one student's extension |
tool_modify_assignment_dates |
Change release / due / late-due dates |
tool_rename_assignment |
Rename an assignment |
tool_get_assignment_submissions |
List assignment submissions |
tool_get_student_submission |
Read one student's submission content |
tool_get_assignment_graders |
View graders for a question |
Grading Read
| Tool | Description |
|---|---|
tool_get_assignment_outline |
Question hierarchy, IDs, weights, prompt text |
tool_export_assignment_scores |
Assignment score export and summary |
tool_get_grading_progress |
Per-question grading dashboard |
tool_get_submission_grading_context |
Full grading context for a question submission |
tool_get_question_rubric |
Rubric inspection without a submission ID |
tool_list_question_submissions |
List Question Submission IDs, filterable by grade state |
tool_get_next_ungraded |
Navigate to the next ungraded question submission |
Grading Write
| Tool | Description |
|---|---|
tool_apply_grade |
Apply rubric items, comments, and point adjustments |
tool_create_rubric_item |
Create a rubric item |
tool_update_rubric_item |
Update a rubric item |
tool_delete_rubric_item |
Delete a rubric item |
AI-Assisted / Workflow Helpers
| Tool | Description |
|---|---|
tool_prepare_grading_artifact |
Save a question-specific grading artifact to /tmp/gradescope-mcp |
tool_assess_submission_readiness |
Estimate whether auto-grading is safe enough to attempt |
tool_cache_relevant_pages |
Download crop and nearby pages to /tmp/gradescope-mcp |
tool_prepare_answer_key |
Save assignment-wide answer-key notes to /tmp/gradescope-mcp |
tool_smart_read_submission |
Return a crop-first reading plan |
Answer Groups
| Tool | Description |
|---|---|
tool_get_answer_groups |
List AI-clustered answer groups |
tool_get_answer_group_detail |
Inspect one answer group |
tool_grade_answer_group |
Batch-grade one answer group |
Regrades
| Tool | Description |
|---|---|
tool_get_regrade_requests |
List regrade requests |
tool_get_regrade_detail |
Inspect one regrade request |
Statistics
| Tool | Description |
|---|---|
tool_get_assignment_statistics |
Assignment-level and per-question statistics |
Resources
| URI | Description |
|---|---|
gradescope://courses |
Current course list |
gradescope://courses/{course_id}/assignments |
Assignment list for a course |
gradescope://courses/{course_id}/roster |
Roster for a course |
Prompts
| Prompt | Description |
|---|---|
summarize_course_progress |
Summarize assignment status in a course |
manage_extensions_workflow |
Guide extension-management work |
check_submission_stats |
Summarize assignment submission stat |
Tools (5)
tool_list_coursesList all courses grouped by roletool_get_assignmentsList assignments for a coursetool_apply_gradeApply rubric items, comments, and point adjustmentstool_get_assignment_statisticsAssignment-level and per-question statisticstool_get_regrade_requestsList regrade requestsEnvironment Variables
GRADESCOPE_SESSION_COOKIErequiredAuthentication cookie for Gradescope accessConfiguration
claude_desktop_config.json
{"mcpServers": {"gradescope": {"command": "uv", "args": ["run", "gradescope-mcp"], "env": {"GRADESCOPE_SESSION_COOKIE": "your_cookie_here"}}}}Try it
→List all my current courses and their roles.
→Summarize the grading progress for the latest assignment in my Data Structures course.
→Show me all pending regrade requests for the midterm exam.
→Assess if the current submission for student X is ready for auto-grading.
→Create a summary of assignment submission statistics for the final project.