@hlao-mcp/google-classroom

MCP server that wraps the Google Classroom REST API and exposes it as read-only typed tools for HLAO agents.

This package is separate from any HLAO Google Workspace MCP by design. It carries its own scoped OAuth client and credentials so an agent that calls classroom data cannot also touch Drive or Gmail. Keep the scopes minimal: only the three readonly Classroom scopes listed below.

Tools

All read-only:

| Tool | What it does | | ------------------------------- | ------------------------------------------------------------------------- | | list_courses | List Classroom courses, optionally filtered by teacher / student / state. | | get_course_by_id | Fetch a single course's metadata. | | list_students_in_course | List enrolled students in a course. | | list_teachers_in_course | List teachers attached to a course. | | list_coursework_in_course | List assignments in a course. | | get_coursework_by_id | Fetch a single coursework item. | | list_student_submissions | List student submissions for a coursework item. | | get_student_submission_by_id | Fetch a single student submission. |

Credentials

| Variable | What it is | | --------------------------------- | ----------------------------------------------------------------------- | | GOOGLE_CLASSROOM_CLIENT_ID | Google Cloud OAuth 2.0 client id. Required. | | GOOGLE_CLASSROOM_CLIENT_SECRET | OAuth 2.0 client secret. Required. | | GOOGLE_CLASSROOM_REFRESH_TOKEN | Refresh token from the OAuth dance with the scopes below. Required. |

Required OAuth scopes

Request only these three scopes during the OAuth dance:

• https://www.googleapis.com/auth/classroom.courses.readonly
• https://www.googleapis.com/auth/classroom.rosters.readonly
• https://www.googleapis.com/auth/classroom.coursework.students.readonly

Adding broader scopes (e.g. classroom.coursework.students without .readonly) widens this server's blast radius. Don't.

How to get credentials

1. Create a Google Cloud project (or pick one) and enable the Classroom API under APIs & Services → Library.
2. Under APIs & Services → OAuth consent screen, configure the consent screen (internal or external) and add the three scopes above.
3. Under APIs & Services → Credentials → Create credentials → OAuth client ID, choose Web application (or installed application for desktop). Add a redirect URI you control.
4. Copy the Client ID and Client Secret.
5. Run the OAuth 2.0 authorization-code dance once with the three scopes, requesting access_type=offline and prompt=consent. Capture the refresh token returned.
6. Store all three values in your .env.

If you ever need to add a Workspace MCP (Drive, Gmail, etc.), create a separate OAuth client with its own credentials. Sharing one client across multiple MCPs collapses the scopes audit and makes blast-radius questions unanswerable.

Local development

cp .env.example .env
pnpm install
pnpm --filter @hlao-mcp/google-classroom build

HLAO_MCP_HTTP_PORT=3007 node dist/server.js
# or
HLAO_MCP_TRANSPORT=stdio node dist/server.js

HLAO wrapping

@hlao/mcp-gateway forwards a verified passport as x-hlao-authority. Every tool here is read-only; the passport serves the audit substrate ("which agent acting on which passport read which course at what time") rather than gating writes.