google-classroom-mcp

MCP server for Google Classroom, built for the student and with support for several Google accounts at once. It lets Claude Code, Claude Desktop, Cursor or any MCP client look up your courses, pending assignments, due dates, grades and announcements and, if you ask it to, attach files or turn in an assignment.

It uses the official Google Classroom API with OAuth on your own account. It asks for Classroom and Drive permissions: read-only to download to your disk the attachments of assignments, materials and announcements (Google Docs, Sheets and Slides are exported to PDF, xlsx, etc.), and drive.file to upload your submissions to a "Classroom Submissions" folder in your Drive (with that permission the server only sees the files it uploads itself).

About submissions. The Google API only allows attaching files and turning in from the same application that created the assignment. If your teacher created it from the Classroom web app (the usual case), attaching returns 403 @ProjectPermissionDenied. That is a Google restriction, not the server's. For those assignments there is submit_in_browser: it drives Google Chrome with your session and makes the same clicks you would (see Submitting through the browser). submit_assignment(files=[...]) tries the API route and, if it fails, at least leaves your files in Drive.

Requirements

• uv installed. On macOS: brew install uv. On any system: curl -LsSf https://astral.sh/uv/install.sh | sh.

• A Google Cloud OAuth client secret (free, see below).

• Google Chrome, only if you want to submit assignments through the browser.

• Your Classroom account must allow third-party apps. If it is an institutional account, the administrator may have that blocked.

Related MCP server: Google Classroom MCP

Installation

1. Create the client secret in Google Cloud (once, about 5 minutes):

1. Go to https://console.cloud.google.com and create a project, for example classroom-mcp.

2. APIs & Services > Library: enable Google Classroom API and Google Drive API (Drive is needed to download attachments).

3. APIs & Services > OAuth consent screen (or "Google Auth Platform"): user type External, fill in name and email, and under Test users add all the Google accounts you use to sign in to Classroom.

4. APIs & Services > Credentials > Create credentials > OAuth client ID, application type Desktop app. Download the JSON.

5. Recommended: in Google Auth Platform > Audience, click Publish app. While the app is in "Testing" status, Google expires every authorization after 7 days and you have to repeat setup. In "Production" the authorization lasts indefinitely; the app is still yours and unverified, you will just see the "unverified app" notice once per account.

2. Authorize your account (opens the browser; the token is stored in ~/.config/google-classroom-mcp/accounts/<alias>.json with permissions only for your user):

uvx --from git+https://github.com/AlanMagno1/google-classroom-mcp google-classroom-mcp setup ~/Downloads/client_secret_XXXX.json

If Google warns that the app is not verified, choose "Continue": the app is yours.

Another account? Run setup again (without the JSON this time) and pick the other Google account in the browser. By default each account is saved with its email as the alias; if you prefer a short name use setup --as unam. With --hint you@university.edu Google goes straight to that account and setup refuses to save if you authorize with a different one (useful when the browser only has the wrong account open).

3. Register the server in Claude Code:

claude mcp add google-classroom -s user -- uvx --from git+https://github.com/AlanMagno1/google-classroom-mcp google-classroom-mcp

Done. Open Claude Code and ask it, for example:

What assignments do I have pending in Classroom?

Check https://classroom.google.com/c/NzE2NDU5MjM0/a/NjA1MzIx/details and tell me what it asks for.

Download the files for Data Mining practice 3 and summarize what has to be done.

Submit ~/Documents/practica3.ipynb to Data Mining practice 3.

Other clients (Claude Desktop, Cursor, etc.)

{
  "mcpServers": {
    "google-classroom": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/AlanMagno1/google-classroom-mcp", "google-classroom-mcp"]
    }
  }
}

Environment variables

Several Google accounts

A single server handles all your accounts. Every tool accepts an optional account parameter (alias, email, or a piece of either):

• If there is only one account, you never need to pass it.

• list_courses and list_pending_assignments without account go through every account and mark which one each course belongs to.

• Tools that take a course or an assignment work out on their own which account it is in.

If for some reason you want two separate servers, the GOOGLE_CLASSROOM_MCP_CONFIG_DIR variable still works with a different server name for each one.

Tools

All of them accept account? as the last parameter. course_id also accepts the course URL; the ids in Classroom URLs are base64 and the server decodes them on its own.

Google-native files have no binary to download, so they are exported: Docs and Slides to pdf, Sheets to xlsx, drawings to png. With export_format you can ask for another one (docx, txt, md, html, csv, pptx...). dest_dir accepts an absolute path or a folder relative to the downloads folder.

upload_file and submit_assignment(files=...) need the account to have been authorized with the drive.file permission. If you authorized it with an earlier version, those two tools will tell you which command to run; everything else keeps working without it.

Submitting through the browser

Since the API refuses to turn in assignments created by the teacher, submit_in_browser submits the same way you would: with Playwright it drives your installed Google Chrome on a separate profile, opens the assignment with the right account, "Add or create" > "File", uploads the file, "Turn in", and then confirms through the API that the state changed to TURNED_IN. reclaim_in_browser does the opposite: it clicks "Unsubmit", confirms and checks that the submission is no longer TURNED_IN. If something fails, either one leaves a screenshot in ~/Downloads/google-classroom-mcp/_browser/.

It requires Google Chrome installed and, for each account, a session signed in once in its own Chrome profile (one account per profile; Google's multi-account sign-in is not reliable for this):

google-classroom-mcp browser-login unam --email you@university.edu   # opens Chrome: sign in and close the window
google-classroom-mcp browser-login personal --email you@gmail.com
google-classroom-mcp browser-status                                  # session of each profile

Profiles live in ~/.config/google-classroom-mcp/browser-profiles/<alias> (variable GOOGLE_CLASSROOM_BROWSER_PROFILES). Always sign in from browser-login: on macOS the Chrome that Playwright opens encrypts cookies with a different key than your regular Chrome, so a session started elsewhere is no use to it. If Google blocks signing in from the controlled browser, browser-login ALIAS --plain opens a Chrome without automation but compatible with it. When submitting, Chrome runs hidden in the background; with GOOGLE_CLASSROOM_BROWSER_HEADLESS=0 the window is shown, useful to watch what happens if something fails. Automating the Classroom web app is not a use Google offers officially; it is your account and your assignments, but it is worth knowing.

Commands

google-classroom-mcp setup [client_secret.json] [--as ALIAS] [--hint EMAIL]   # saves the client secret and authorizes an account
google-classroom-mcp accounts                                  # lists the configured accounts
google-classroom-mcp remove ALIAS                              # removes an account
google-classroom-mcp check                                     # checks the connection of every account
google-classroom-mcp browser-login ALIAS [--email EMAIL] [--plain]   # signs in to that account's Chrome profile
google-classroom-mcp browser-status                            # session of each browser profile
google-classroom-mcp                                           # starts the MCP server over stdio (used by the client)

Permissions requested

Classroom: read access to courses, materials, announcements, topics, the course roster (to read your profile) and the profile email, and read and write access to your own coursework and submissions (classroom.coursework.me). Drive: read-only (drive.readonly) to download attachments, and drive.file to upload your submissions; with the latter the server can only see and touch the files it created itself, never the rest of your Drive, and it deletes nothing. Nothing is sent to any server other than Google's. upload_file, submit_assignment, submit_in_browser, reclaim_submission and reclaim_in_browser create files or modify your submission: Claude should only use them when you explicitly ask.

If you already had accounts authorized with an earlier version, they keep working for everything except uploading; for that, run google-classroom-mcp setup --as <alias> --hint <email> again once per account.

Development

git clone https://github.com/AlanMagno1/google-classroom-mcp
cd google-classroom-mcp
uv sync
uv run google-classroom-mcp check

To try local changes in Claude Code without publishing:

claude mcp add google-classroom -s user -- uv --directory /path/to/google-classroom-mcp run google-classroom-mcp

License

MIT