mcp-classroom

MCP server for Google Classroom — read assignments, check submission states, upload files to Drive, and view attached files. Pairs with a Claude Code skill + Playwright for browser automation to work around Google Workspace write restrictions.

What it can do

Feature	How
List courses	MCP
List & get assignments	MCP (slim response — no heavy file metadata)
Check submission state & grade	MCP
List files attached to a submission	MCP
Upload file to Google Drive	MCP
Attach file to submission	Playwright (API blocked by Workspace admins)
Turn in / Mark as done	Playwright (API blocked by Workspace admins)
Unsubmit (reclaim)	Playwright (API blocked by Workspace admins)

Why Playwright? Google Workspace for Education admins can restrict third-party apps from modifying student submissions via the API (@ProjectPermissionDenied). Playwright automates the browser instead, bypassing that restriction entirely.

---

Requirements

• Python 3.11+
• Node.js (for playwright-cli)
• A Google Cloud project with the Classroom API and Drive API enabled

---

1. Google Cloud Console setup

1.1 Create a project

1. Go to console.cloud.google.com
2. Create a new project (e.g. mcp-classroom)

1.2 Enable APIs

In APIs & Services → Library, enable:

• Google Classroom API
• Google Drive API

1.3 Configure OAuth consent screen

1. Go to APIs & Services → OAuth consent screen
2. User type: External
3. Fill in app name, support email, developer email
4. Add scopes:

   https://www.googleapis.com/auth/classroom.courses.readonly
   https://www.googleapis.com/auth/classroom.coursework.me
   https://www.googleapis.com/auth/classroom.coursework.students
   https://www.googleapis.com/auth/classroom.student-submissions.me.readonly
   https://www.googleapis.com/auth/classroom.rosters.readonly
   https://www.googleapis.com/auth/classroom.announcements.readonly
   https://www.googleapis.com/auth/drive.file
   https://www.googleapis.com/auth/drive.readonly
   

5. Add your Google account as a test user
6. Publishing status: you can leave it in Testing while developing, or publish to Production to avoid the unverified app warning

1.4 Create OAuth credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Download the JSON file
5. Rename it to client_secret_<...>.json and place it in the project root (next to pyproject.toml)

---

2. Install the MCP server

# Clone the repo
git clone https://github.com/your-username/mcp-classroom.git
cd mcp-classroom

# Install Python dependencies
pip install -e .

First run — authenticate

mcp-classroom

A browser window will open asking you to authorize the app with your Google account. After approval, a token.json is saved locally (gitignored).

---

3. Register with Claude Code

Add the server to your Claude Code MCP config (~/.claude/claude.json or via claude mcp add):

{
  "mcpServers": {
    "google-classroom": {
      "command": "mcp-classroom",
      "args": []
    }
  }
}

Or if running from source:

{
  "mcpServers": {
    "google-classroom": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/absolute/path/to/mcp-classroom"
    }
  }
}

---

4. Install Playwright (for browser automation)

npm install -g playwright-cli
npx playwright install chromium

Save your Google session (one time)

playwright-cli open --browser=chrome https://accounts.google.com/signin
# Log in manually in the browser window
playwright-cli state-save ~/classroom-auth.json
playwright-cli close

---

5. Install the Claude Code skill (optional but recommended)

The skill tells Claude how to use the MCP + Playwright together without you having to explain the workflow every time.

1. Copy skill/SKILL.md to your Claude skills directory:

   ~/.claude/skills/google-classroom/SKILL.md
   

2. Edit the skill file and fill in your own course IDs and assignment IDs (run list_courses and list_coursework once to get them).
3. Update the auth state path inside the skill to match where you saved classroom-auth.json.
4. Reload plugins in Claude Code: /reload-plugins

---

Available MCP tools

Tool	Description
list_courses	List active courses (slim: id, name, section, state)
get_course	Get full details of a course
list_coursework	List assignments (slim: id, title, state, dueDate)
get_coursework	Get assignment details + description (no teacher file attachments)
list_my_submissions	List your submissions — state, grade, attachment count
get_my_submission	Get one submission's details
list_submission_attachments	List titles and Drive IDs of files you've attached
upload_file_to_drive	Upload a local file to Google Drive
list_drive_files	Search files in your Drive
add_drive_attachment	Attach a Drive file to a submission (may be blocked by Workspace)
add_link_attachment	Attach a URL to a submission (may be blocked by Workspace)
remove_attachment	Remove an attachment (may be blocked by Workspace)
turn_in_submission	Turn in a submission (may be blocked by Workspace)
reclaim_submission	Unsubmit a submission (may be blocked by Workspace)
list_announcements	List course announcements
list_students	List students in a course
list_teachers	List teachers in a course

Tools marked "may be blocked by Workspace" return 403 @ProjectPermissionDenied on institutional Google Workspace accounts. Use Playwright automation instead for those operations.

---

File structure

mcp-classroom/
├── src/
│   ├── server.py      # MCP tool definitions
│   ├── classroom.py   # Classroom API calls
│   ├── drive.py       # Drive API calls
│   └── auth.py        # OAuth flow + scopes
├── skill/
│   └── SKILL.md       # Claude Code skill template
├── tests/
├── pyproject.toml
├── requirements.txt
└── README.md

---

Gitignored (never commit these)

• token.json — your OAuth token
• client_secret_*.json — your OAuth client credentials