Gradescope MCP Server

Instructions

Returns a table grouped by role with name, email, SID, and submission count.
Requires instructor or TA access to the course.

Args:
    course_id: The Gradescope course ID.

Implementation Reference

• src/gradescope_mcp/tools/courses.py:146-180 (handler)

  The core implementation of the roster retrieval logic.

  def get_course_roster(course_id: str) -> str:
      """Get the roster of students and staff for a course.
  
      Uses a custom HTML parser (the gradescopeapi library's parser
      has a bug with the column indexing when sections are present).
  
      Args:
          course_id: The Gradescope course ID.
      """
      if not course_id:
          return "Error: course_id is required."
  
      try:
          conn = get_connection()
          # Fetch the memberships page directly
          url = f"{conn.gradescope_base_url}/courses/{course_id}/memberships"
          resp = conn.session.get(url)
          if resp.status_code != 200:
              return f"Error: Unable to access roster (status {resp.status_code}). Check your permissions."
  
          soup = BeautifulSoup(resp.text, "html.parser")
          members = _parse_roster(soup, course_id)
      except AuthError as e:
          return f"Authentication error: {e}"
      except Exception as e:
          return f"Error fetching roster: {e}"
  
      if not members:
          return f"No members found for course `{course_id}`, or you don't have permission to view the roster."
  
      # Group by role
      by_role: dict[str, list] = {}
      for member in members:
          role = member["role"]
          by_role.setdefault(role, []).append(member)

• src/gradescope_mcp/server.py:103-113 (registration)

  The MCP tool registration and wrapper function for get_course_roster.

  @mcp.tool()
  def tool_get_course_roster(course_id: str) -> str:
      """Get the full roster (students, TAs, instructors) for a course.
  
      Returns a table grouped by role with name, email, SID, and submission count.
      Requires instructor or TA access to the course.
  
      Args:
          course_id: The Gradescope course ID.
      """
      return get_course_roster(course_id)