Metadata-Version: 2.5
Name: classroom-mcp
Version: 0.1.0
Summary: Google Classroom MCP server for students: courses, assignments with your submission status, and announcements.
Project-URL: Homepage, https://github.com/OmarNiazi/classroom-mcp
Project-URL: Issues, https://github.com/OmarNiazi/classroom-mcp/issues
Author: Omar Niazi
License-Expression: MIT
License-File: LICENSE
Keywords: claude,google-classroom,mcp,model-context-protocol,students
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Education
Requires-Python: >=3.11
Requires-Dist: google-api-python-client>=2.100
Requires-Dist: google-auth-oauthlib>=1.2
Requires-Dist: google-auth>=2.20
Requires-Dist: mcp<2,>=1.30
Requires-Dist: platformdirs>=4.0
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

﻿# classroom-mcp

Let your AI assistant read your **Google Classroom**: your classes, what's due (and whether
you've turned it in), and your teachers' announcements.

> "What do I still have to hand in this week?"
> "Did my networks teacher post anything about the exam?"
> "Which assignments am I late on, across all my classes?"

It works with any app that supports MCP servers, such as Claude Desktop, Claude Code, Cursor
and VS Code. It's **read-only**: it can't submit work, post, or change anything.

---

## Setup (about 3 minutes)

### 1. Install `uv`
`uv` is a small tool that downloads and runs this server for you. You don't need to install
Python yourself.

**Windows:** open PowerShell and paste:
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
**macOS / Linux:** open Terminal and paste:
```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. Add it to your app

**Claude Desktop:** go to Settings â†’ Developer â†’ Edit Config. Paste this into the file (or merge
the `google-classroom` part into the `mcpServers` you already have), save, then **fully quit and
reopen** Claude Desktop:
```json
{
  "mcpServers": {
    "google-classroom": {
      "command": "uvx",
      "args": ["classroom-mcp"]
    }
  }
}
```

**Claude Code:**
```sh
claude mcp add --scope user google-classroom -- uvx classroom-mcp
```

**Cursor:** put the same JSON as Claude Desktop in `~/.cursor/mcp.json`.

**VS Code:** add this to `.vscode/mcp.json` (note the key is `servers`):
```json
{ "servers": { "google-classroom": { "command": "uvx", "args": ["classroom-mcp"] } } }
```

**Any other MCP app:** the command is `uvx` and the argument is `classroom-mcp`.

### 3. Ask a question, then sign in
Ask something like *"What classes am I in?"* A browser window opens for you to sign in with
Google:

1. Choose the Google account you use for Classroom.
2. Google will say **"Google hasn't verified this app"**. This is expected for a new
   open-source project. Click **Advanced**, then **Go to â€¦ (unsafe)**.
3. **Leave every box ticked** and click **Continue**. Every permission is read-only.
4. When the page says **Connected to Google Classroom**, go back to your app. It usually
   carries on by itself; if not, ask again.

That's it. You stay signed in on this computer.

---

## What it can see

| Can | Can't |
|---|---|
| Your active classes | Submit, unsubmit or edit anything |
| Assignments, due dates, points, attachment names | See classmates' work or grades |
| **Your own** submission status and grades | Download attachment files (planned) |
| Teacher announcements | Post or comment |

Tools exposed to the assistant: `get_all_courses`, `get_assessment_items`
(with an `only_pending` filter), `read_stream_announcements`.

## Privacy
Everything runs on **your computer**. Your Google sign-in is saved only in your user folder
(`%LOCALAPPDATA%\classroom-mcp\` on Windows, `~/Library/Application Support/classroom-mcp/` on
macOS, `~/.config/classroom-mcp/` on Linux). There's no server run by this project, and no
analytics. Your Classroom data goes from Google to your app, and nowhere else. Your AI app's own
privacy terms apply to what you ask it. Full details are in [PRIVACY.md](https://github.com/OmarNiazi/classroom-mcp/blob/main/PRIVACY.md).

## Signing out / switching accounts
```sh
uvx classroom-mcp logout   # revokes access with Google and deletes the saved sign-in
uvx classroom-mcp login    # sign in again, now
uvx classroom-mcp status   # are you signed in, and where it's saved
```
You can also remove access anytime at <https://myaccount.google.com/permissions>.

## Troubleshooting

**"My school blocks this app" / "Access blocked" / "admin_policy_enforced"**
Your school's Google Workspace doesn't allow unverified third-party apps. This is common
for school-managed accounts, especially for students under 18. Only your school's IT admin
can allow it. A personal Google account that's enrolled in your classes will work.

**The app says it can't find `uvx`, or the server fails to start**
Apps opened from the Start menu or Dock don't always see newly installed tools. Restart your
computer, or put the full path in `"command"` instead of `uvx`:
- Windows: `"C:\\Users\\<you>\\.local\\bin\\uvx.exe"` (in JSON, backslashes are doubled)
- macOS: `"/Users/<you>/.local/bin/uvx"`
- Linux: `"/home/<you>/.local/bin/uvx"`

**The browser didn't open.** The assistant's reply includes the sign-in link; open it yourself.

**I unticked a permission.** You'll be asked to sign in again. Leave all boxes ticked.

**It worked before, now it asks me to sign in again.** You (or your school) removed its
access, or the sign-in expired. Just sign in again.

## Phones
Not yet. Phone apps can't launch programs on your phone, so this needs a hosted version. A
self-hosted option is planned. For now, use a computer.

## Known limits
- Until Google verifies the app, you'll see the warning screen, and it's limited to the first
  100 users.
- Only **active** classes are listed.
- Attachment files can't be downloaded yet (that needs access to your whole Google Drive).

---

## Development
```sh
git clone https://github.com/OmarNiazi/classroom-mcp && cd classroom-mcp
uv sync
uv run pytest
uv run classroom-mcp          # run the server from source (stdio)
```
Point a host at your checkout with
`"command": "uv", "args": ["run", "--directory", "/path/to/classroom-mcp", "classroom-mcp"]`.

| Environment variable | Purpose |
|---|---|
| `CLASSROOM_MCP_CLIENT_SECRETS` | Path to your own OAuth client JSON (Desktop app type) instead of the bundled one |
| `CLASSROOM_MCP_CONFIG_DIR` | Store the sign-in somewhere else (e.g. a second account) |

Design decisions are recorded in [`docs/adrs/`](https://github.com/OmarNiazi/classroom-mcp/tree/main/docs/adrs). Start with
[`docs/project-state.md`](https://github.com/OmarNiazi/classroom-mcp/blob/main/docs/project-state.md).

## License
[MIT](https://github.com/OmarNiazi/classroom-mcp/blob/main/LICENSE)
