Gradescope MCP Server

Instructions

Returns a summary table with student names, total scores, statistics,
and per-question breakdowns. Requires instructor/TA access.

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

Implementation Reference

• src/gradescope_mcp/tools/grading.py:205-235 (handler)

  The core implementation of the export_assignment_scores function.

  def export_assignment_scores(course_id: str, assignment_id: str) -> str:
      """Export per-question scores for an assignment as a formatted table.
  
      Returns a summary table with student names, total scores, and per-question
      breakdowns. Requires instructor/TA access.
  
      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()
          url = f"{conn.gradescope_base_url}/courses/{course_id}/assignments/{assignment_id}/scores"
          resp = conn.session.get(url)
      except AuthError as e:
          return f"Authentication error: {e}"
      except Exception as e:
          return f"Error fetching scores: {e}"
  
      if resp.status_code != 200:
          return f"Error: Cannot access scores (status {resp.status_code}). Check permissions."
  
      content_type = resp.headers.get("content-type", "")
      if "csv" not in content_type and "text" not in content_type:
          return f"Error: Unexpected content type: {content_type}"
  
      # Parse the CSV
      reader = csv.DictReader(io.StringIO(resp.text))

• src/gradescope_mcp/server.py:302-313 (registration)

  Registration of the tool_export_assignment_scores as an MCP tool, which calls the grading utility function.

  @mcp.tool()
  def tool_export_assignment_scores(course_id: str, assignment_id: str) -> str:
      """Export per-question scores for an assignment.
  
      Returns a summary table with student names, total scores, statistics,
      and per-question breakdowns. Requires instructor/TA access.
  
      Args:
          course_id: The Gradescope course ID.
          assignment_id: The assignment ID.
      """
      return export_assignment_scores(course_id, assignment_id)