Gradescope MCP Server

Instructions

Returns a list of submission IDs and file counts.
Note: May be slow for large classes as it fetches each submission individually.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.

Implementation Reference

• src/gradescope_mcp/tools/submissions.py:100-150 (handler)

  The core implementation of get_assignment_submissions that fetches submission data from the Gradescope API.

  def get_assignment_submissions(course_id: str, assignment_id: str) -> str:
      """Get all submissions for an assignment (instructor/TA only).
  
      Works for all assignment types: scanned PDF, online, and code assignments.
      Returns submission IDs, graded status, and grading progress.
  
      Note: The returned IDs are **Global Submission IDs** (the whole assignment
      submission). For grading a specific question, you may need the per-question
      submission ID from `get_submission_grading_context`.
  
      Args:
          course_id: The Gradescope course ID.
          assignment_id: The assignment ID.
      """
      if not course_id or not assignment_id:
          return "Error: both course_id and assignment_id are required."
  
      try:
          conn = get_connection()
          # Primary: submissions.json (works for scanned PDF/image assignments)
          resp = conn.session.get(
              f"{conn.gradescope_base_url}/courses/{course_id}"
              f"/assignments/{assignment_id}/submissions.json",
              headers={
                  "Accept": "application/json",
                  "X-Requested-With": "XMLHttpRequest",
              },
          )
  
          if resp.status_code == 200:
              return _format_submissions_json(resp.json(), assignment_id, course_id)
  
          # Fallback: scrape review_grades HTML table (works for online assignments)
          return _get_submissions_from_review_grades(conn, course_id, assignment_id)
  
      except AuthError as e:
          return f"Authentication error: {e}"
      except Exception as e:
          return f"Error fetching submissions: {e}"
  
  
  def _format_submissions_json(data: dict, assignment_id: str, course_id: str) -> str:
      """Format submission data from the submissions.json endpoint."""
      detailed = data.get("detailed_submissions", {})
      basic = data.get("submissions", {})
  
      if not detailed and not basic:
          return f"No submissions found for assignment `{assignment_id}` in course `{course_id}`."
  
      subs = detailed or basic
      total = len(subs)

• src/gradescope_mcp/server.py:242-255 (registration)

  The registration of the tool_get_assignment_submissions function as an MCP tool using the @mcp.tool decorator.

  @mcp.tool()
  def tool_get_assignment_submissions(
      course_id: str, assignment_id: str
  ) -> str:
      """Get all submissions for an assignment (instructor/TA only).
  
      Returns a list of submission IDs and file counts.
      Note: May be slow for large classes as it fetches each submission individually.
  
      Args:
          course_id: The Gradescope course ID.
          assignment_id: The assignment ID.
      """
      return get_assignment_submissions(course_id, assignment_id)