.md"}} ``` Embedded images are written out as real image files and the Markdown points at them, so a reader can actually open them. This matters more than it sounds: Google inlines every picture as a base64 data URI, and on a real document that was 157,879 characters of unreadable text — 1,695 after extraction, with 15 usable PNGs alongside. Requires the project-local rclone setup (`tools/rclone`, `tools/rclone.conf`, Drive remotes scoped read-only). Exports go to a temp directory (`SCHOOLOGY_EXPORT_DIR`, default `<tmp>/schoology-mcp-materials/`), cached per document and pruned after 24h. Pass `export_google_docs=False` to skip it. ### Downloading anything else Teachers also paste Drive links *inside* assignment descriptions, where they are not attachments and nothing auto-exports them. Rather than have the server chase every link it finds, `download_file` lets the agent decide: ``` download_file("https://drive.google.com/file/d/<id>/view") → {"filename": "Ch7-Photosynthesis-Lab-Demo.mp4", "size_mb": 118.4, "declined": "too_large", "error": "118.4 MB, over the 25 MB limit. Not downloaded -- raise max_mb to fetch it."} ``` **For Drive, size is checked before any transfer.** `rclone backend copyid --dry-run` reports the name and size while writing nothing, which is the only pre-flight check available — `--max-size` is silently ignored by `copyid`. A native Google Doc reports no size at all (it has none until exported), and that absence is how the two are told apart. For Schoology-hosted attachments there is no equivalent: Playwright has no streaming response, so the body is already buffered by the time Content-Length can be read. There `max_mb` keeps an oversized file out of the cache rather than off the wire. Accepts Google Drive links and Schoology-hosted attachments (fetched with the logged-in session). Not a general web downloader. What gets exported, by link shape: | Link | Result | |---|---| | `/document/d/<id>` | Markdown + extracted images | | `/spreadsheets/d/<id>` | `.xlsx`, path returned | | `/presentation/d/<id>` | `.pptx`, path returned | | `/file/d/<id>` (uploaded PDF/image/video) | **reported, not downloaded** | | `/forms/d/e/<id>` | not exportable — a Form is not a file | Uploaded files are skipped by default because their size is unknown until the transfer is already happening — the first one encountered in a real assignment was a 110 MB video — and rclone's `--max-size` is ignored by `backend copyid`, so there is no way to abort mid-flight. Pass `allow_binary=True` when you actually want one. Documents whose owner disabled "viewers can download, print, copy" cannot be exported by any API; those report `google_doc.export_error` instead of failing the call. For bulk export, use `scripts/backup_gdocs.sh` / `scripts/get_gdoc.sh` instead. ## Read-only Every tool issues reads. There is no send-message, post or submit endpoint, and none is planned for now. One caveat worth stating plainly: **`get_message_thread` marks that message read on Schoology's side**, exactly as if the student had clicked it. It is the only server-visible side effect in the whole MCP. `check_updates` never calls it, so scheduled checks never touch anyone's unread badges. Use `get_messages` to browse; use `get_message_thread` only when you actually need the full text. ## Reminders (grades, assignments, messages) `check_updates` answers *"what changed since last time?"* — the basis for an agent that tells you when a grade gets posted. **The server is stateless.** It stores nothing about previous runs. You pass in the `baseline` from the last call, and it hands you a fresh one: ```python result = check_updates(baseline=<your stored baseline>) # -> {"alerts": [...], "changed": ["grades"], "baseline": {...}, ...} ``` The baseline is ~5KB of ids and content hashes. Grades, assignments and messages are tracked per item, so an alert can name the assignment that got a score. The calendar is tracked as one whole-feed digest — 709 events would otherwise dominate the baseline. Pass `detailed_sources=["calendar"]` if you need per-event precision. ### Keeping the LLM out of the quiet path (recommended) Most checks find nothing — grades post in bursts, not continuously. Waking an agent to discover that costs ~3k tokens every time, and the agent adds nothing on a run with no news. `scripts/watch_once.py` does the polling without a model. It prints nothing and exits `0` when there is no change, and only on a real change does it emit a payload and exit `10`: ```bash python scripts/watch_once.py --json > /tmp/sgy.json [ $? -eq 10 ] && <wake your agent with the contents of /tmp/sgy.json> ``` | | Quiet run | Run with news | |---|---|---| | Agent woken | no | yes | | Tokens | **0** | one turn, alerts already in hand | | Wall clock | ~25s (4 sources) / ~12s (`--sources messages upcoming`) | same | Because quiet runs cost no tokens, you can poll far more often than you could afford to wake an agent — the only real budget is page loads against Schoology. The emitted payload already contains the alerts, so the woken agent does not need to call `check_updates` again to find out what happened. It is not a reimplementation: it calls the same `check_updates` and plays the caller role described below, just holding the baseline in a file (`~/.local/share/schoology-mcp/watch-state.json`, override with `--state` or `SCHOOLOGY_WATCH_STATE`) instead of in a conversation. **The MCP server stays stateless** — that file belongs to the caller, which here is the script. Exit codes: `0` quiet, `10` changes on stdout, `1` error (state left untouched, nothing reported). Use `--dry-run` to report without committing state. Use the agent-driven flow below instead when you want the agent to *judge* what matters ("is this worth interrupting me for?") on every check rather than only after the script has already found something. ### Wiring it to a schedule Any scheduler works (cron, launchd, a Claude Code scheduled task). The agent it invokes should do exactly this: 1. Read your stored baseline, call `check_updates(baseline=...)`. 2. Notify from `alerts`. 3. **Then** store the returned `baseline`. Storing *after* notifying is deliberate: a crash in between costs you a duplicate notification, never a missed one. Because change detection is content hashing rather than a timestamp cursor, replaying the same baseline twice produces an identical result, and a missed run just makes the next diff bigger. Nothing can slip between two runs. Suggested layout for the agent's own memory: | File | Contents | Written | |---|---|---| | `cursor.json` | the `baseline` object, verbatim | every run | | `failures` | consecutive-failure counter | on error | #### Registering with an external agent (OpenClaw shown) ```bash openclaw mcp add schoology \ --command /path/to/schoology-mcp/.venv/bin/python \ --arg /path/to/schoology-mcp/server.py \ --env SCHOOLOGY_USERNAME=950XXXXX \ --env SCHOOLOGY_KEEPALIVE=false \ --include 'check_updates,get_health,get_messages,get_grades,get_calendar_events,get_material,download_file' ``` The tool whitelist is doing two jobs. It keeps `get_message_thread` out of reach of an unattended agent — that tool marks mail read, the one server-visible side effect here — and it holds down cost, since **every listed tool's schema is re-read on every single run**: 7 tools is ~2,110 tokens against ~3,170 for all 13. Note that `get_material` normally takes a URL discovered via `get_course_materials`. Alerts already carry `url`, so the whitelist above is enough to follow up on something that changed; add `get_course_materials` (+~230 tokens/run) only if the agent should browse a course on its own. Also note `get_material` can shell out to rclone and write to the export cache. That is fine on demand, but it means a scheduled agent that decides to open a material will spawn a subprocess unattended. `check_updates` never does. ### What it will and will not wake you for - Reports: a score posted or changed, a new assignment, a new message, a calendar change. A teacher fixing a typo in an assignment title is classified as `metadata` and raises no alert. - Stays silent: the first run (no baseline means nothing can be "new"); any source that failed to scrape; assignments or events simply expiring off a list. - If a lot changes at once (new grading period, or a partly broken scrape) you get **one** aggregate alert instead of hundreds. ### Failure handling for the calling agent - `status: "error"` → do not touch your stored baseline. Stay quiet for the first couple of failures; if it persists, report it and call `get_health()`. - `status: "suspect"` on a source means *"parsed 0 items but your baseline had many"* — treated as a broken scrape, not as vanished grades. Alerts are suppressed and that source's baseline is echoed back unchanged. - Sources you did not request are passed through untouched, so a cheap `sources=["messages"]` run will not damage your grades baseline. ### Token cost A quiet run (nothing changed) costs roughly **3.7k tokens**, measured: | Component | Tokens | |---|---| | Tool schemas, 7-tool whitelist | ~2,110 | | Baseline passed in | ~1,235 | | Response | ~340 | | Model output | ~15 | Two things keep it there. When nothing moved the reply says `baseline_unchanged` instead of resending an identical 1.2k-token baseline (so the model never has to echo it back either), and per-source health collapses to a one-word status unless you pass `verbose=True` or something is actually wrong. **Polling frequency is by far the biggest lever** — it is pure multiplication: | Schedule | Per day | Per month | |---|---|---| | every 30 min | ~177k | ~5.3M | | hourly | ~88k | ~2.7M | | every 2 hours | ~44k | ~1.3M | | hourly, school hours only (`0 8-18 * * 1-5`) | ~37k | ~1.1M | Grades post in bursts, not continuously, so hourly during school hours catches essentially everything for a fifth of the cost of 30-minute polling. Restrict the tool whitelist too — every unused tool's schema is re-read on every single run. All of which is moot if you use `watch_once.py` above: a quiet run there costs nothing at all, and these numbers apply only when there is actually something to report. Cheaper still: split the schedule. `sources=["messages","upcoming"]` skips both the gradebook page and the calendar feed, so run that often and the full check a few times a day. ### Scheduling notes - Set `SCHOOLOGY_KEEPALIVE=false` for cron-style runs. Each run is a fresh ~30s process, so the 8-minute keep-alive never fires and only competes for the browser lock. - Schoology sessions are short, so an hourly job usually pays a full ClassLink login (tens of seconds). If you want frequent polling, run the server long-lived instead so the session stays warm. - Don't poll more often than about every 30 minutes. Grades post in bursts, each check is several headless page loads, and this is an SSO'd student account. ### Verifying it ```bash python scripts/check_watch.py --fixtures # offline, no login, no network python scripts/check_watch.py --live # against the real account ``` The fixture suite is the one to run after touching a parser: it covers the false-alarm regressions (time-drift, empty-vs-broken, baseline poisoning, first-run silence). Run it before trusting any scheduled job. ## Run ```bash python server.py # speaks MCP over stdio ``` Test interactively with the MCP Inspector: ```bash npx @modelcontextprotocol/inspector python server.py ``` ## Register with Claude Code ```bash claude mcp add schoology -- /your/path/to/schoology-mcp/.venv/bin/python /your/path/to/schoology-mcp/server.py ``` Or add it to an MCP client config (e.g. Claude Desktop `claude_desktop_config.json`): ```json { "mcpServers": { "schoology": { "command": "/your/path/to/schoology-mcp/.venv/bin/python", "args": ["/your/path/to/schoology-mcp/server.py"], "env": { "SCHOOLOGY_USERNAME": "950XXXXX" } } } }</article></body></html>

{"author": "Student Activities Office", "text": "", "images": [{"url": "https://pausd.schoology.com/system/files/.../notice.gif", "path": "/tmp/schoology-mcp-materials/schoology/notice_6a05f62e.gif", "bytes": 2250950, "content_type": "image/gif"}]} ``` Three kinds of `` appear in a post and only one is content: profile avatars are ignored, emoji (served as images by Google Fonts) are folded back into the text as characters, and the actual embedded picture is fetched with the session cookie. Images are cached by URL, so re-reading the feed costs nothing — the sample above is ~11 MB the first time and 0 ms after. Pass `download_images=False` for URLs only. `check_updates` never downloads them; scheduled runs stay light. ## Google Docs materials Teachers frequently attach a Google Doc rather than uploading a file, so a Schoology "link" material is often the actual content. `get_material` exports those to Markdown and returns them under `google_doc`: ```json {"type": "link", "title": "...", "url": "https://docs.google.com/document/d/...", "google_doc": {"content": "# ...", "images": [...], "image_count": 15, "path": "/tmp/schoology-mcp-materials//.md"}} ``` Embedded images are written out as real image files and the Markdown points at them, so a reader can actually open them. This matters more than it sounds: Google inlines every picture as a base64 data URI, and on a real document that was 157,879 characters of unreadable text — 1,695 after extraction, with 15 usable PNGs alongside. Requires the project-local rclone setup (`tools/rclone`, `tools/rclone.conf`, Drive remotes scoped read-only). Exports go to a temp directory (`SCHOOLOGY_EXPORT_DIR`, default `<tmp>/schoology-mcp-materials/`), cached per document and pruned after 24h. Pass `export_google_docs=False` to skip it. ### Downloading anything else Teachers also paste Drive links *inside* assignment descriptions, where they are not attachments and nothing auto-exports them. Rather than have the server chase every link it finds, `download_file` lets the agent decide: ``` download_file("https://drive.google.com/file/d/<id>/view") → {"filename": "Ch7-Photosynthesis-Lab-Demo.mp4", "size_mb": 118.4, "declined": "too_large", "error": "118.4 MB, over the 25 MB limit. Not downloaded -- raise max_mb to fetch it."} ``` **For Drive, size is checked before any transfer.** `rclone backend copyid --dry-run` reports the name and size while writing nothing, which is the only pre-flight check available — `--max-size` is silently ignored by `copyid`. A native Google Doc reports no size at all (it has none until exported), and that absence is how the two are told apart. For Schoology-hosted attachments there is no equivalent: Playwright has no streaming response, so the body is already buffered by the time Content-Length can be read. There `max_mb` keeps an oversized file out of the cache rather than off the wire. Accepts Google Drive links and Schoology-hosted attachments (fetched with the logged-in session). Not a general web downloader. What gets exported, by link shape: | Link | Result | |---|---| | `/document/d/<id>` | Markdown + extracted images | | `/spreadsheets/d/<id>` | `.xlsx`, path returned | | `/presentation/d/<id>` | `.pptx`, path returned | | `/file/d/<id>` (uploaded PDF/image/video) | **reported, not downloaded** | | `/forms/d/e/<id>` | not exportable — a Form is not a file | Uploaded files are skipped by default because their size is unknown until the transfer is already happening — the first one encountered in a real assignment was a 110 MB video — and rclone's `--max-size` is ignored by `backend copyid`, so there is no way to abort mid-flight. Pass `allow_binary=True` when you actually want one. Documents whose owner disabled "viewers can download, print, copy" cannot be exported by any API; those report `google_doc.export_error` instead of failing the call. For bulk export, use `scripts/backup_gdocs.sh` / `scripts/get_gdoc.sh` instead. ## Read-only Every tool issues reads. There is no send-message, post or submit endpoint, and none is planned for now. One caveat worth stating plainly: **`get_message_thread` marks that message read on Schoology's side**, exactly as if the student had clicked it. It is the only server-visible side effect in the whole MCP. `check_updates` never calls it, so scheduled checks never touch anyone's unread badges. Use `get_messages` to browse; use `get_message_thread` only when you actually need the full text. ## Reminders (grades, assignments, messages) `check_updates` answers *"what changed since last time?"* — the basis for an agent that tells you when a grade gets posted. **The server is stateless.** It stores nothing about previous runs. You pass in the `baseline` from the last call, and it hands you a fresh one: ```python result = check_updates(baseline=<your stored baseline>) # -> {"alerts": [...], "changed": ["grades"], "baseline": {...}, ...} ``` The baseline is ~5KB of ids and content hashes. Grades, assignments and messages are tracked per item, so an alert can name the assignment that got a score. The calendar is tracked as one whole-feed digest — 709 events would otherwise dominate the baseline. Pass `detailed_sources=["calendar"]` if you need per-event precision. ### Keeping the LLM out of the quiet path (recommended) Most checks find nothing — grades post in bursts, not continuously. Waking an agent to discover that costs ~3k tokens every time, and the agent adds nothing on a run with no news. `scripts/watch_once.py` does the polling without a model. It prints nothing and exits `0` when there is no change, and only on a real change does it emit a payload and exit `10`: ```bash python scripts/watch_once.py --json > /tmp/sgy.json [ $? -eq 10 ] && <wake your agent with the contents of /tmp/sgy.json> ``` | | Quiet run | Run with news | |---|---|---| | Agent woken | no | yes | | Tokens | **0** | one turn, alerts already in hand | | Wall clock | ~25s (4 sources) / ~12s (`--sources messages upcoming`) | same | Because quiet runs cost no tokens, you can poll far more often than you could afford to wake an agent — the only real budget is page loads against Schoology. The emitted payload already contains the alerts, so the woken agent does not need to call `check_updates` again to find out what happened. It is not a reimplementation: it calls the same `check_updates` and plays the caller role described below, just holding the baseline in a file (`~/.local/share/schoology-mcp/watch-state.json`, override with `--state` or `SCHOOLOGY_WATCH_STATE`) instead of in a conversation. **The MCP server stays stateless** — that file belongs to the caller, which here is the script. Exit codes: `0` quiet, `10` changes on stdout, `1` error (state left untouched, nothing reported). Use `--dry-run` to report without committing state. Use the agent-driven flow below instead when you want the agent to *judge* what matters ("is this worth interrupting me for?") on every check rather than only after the script has already found something. ### Wiring it to a schedule Any scheduler works (cron, launchd, a Claude Code scheduled task). The agent it invokes should do exactly this: 1. Read your stored baseline, call `check_updates(baseline=...)`. 2. Notify from `alerts`. 3. **Then** store the returned `baseline`. Storing *after* notifying is deliberate: a crash in between costs you a duplicate notification, never a missed one. Because change detection is content hashing rather than a timestamp cursor, replaying the same baseline twice produces an identical result, and a missed run just makes the next diff bigger. Nothing can slip between two runs. Suggested layout for the agent's own memory: | File | Contents | Written | |---|---|---| | `cursor.json` | the `baseline` object, verbatim | every run | | `failures` | consecutive-failure counter | on error | #### Registering with an external agent (OpenClaw shown) ```bash openclaw mcp add schoology \ --command /path/to/schoology-mcp/.venv/bin/python \ --arg /path/to/schoology-mcp/server.py \ --env SCHOOLOGY_USERNAME=950XXXXX \ --env SCHOOLOGY_KEEPALIVE=false \ --include 'check_updates,get_health,get_messages,get_grades,get_calendar_events,get_material,download_file' ``` The tool whitelist is doing two jobs. It keeps `get_message_thread` out of reach of an unattended agent — that tool marks mail read, the one server-visible side effect here — and it holds down cost, since **every listed tool's schema is re-read on every single run**: 7 tools is ~2,110 tokens against ~3,170 for all 13. Note that `get_material` normally takes a URL discovered via `get_course_materials`. Alerts already carry `url`, so the whitelist above is enough to follow up on something that changed; add `get_course_materials` (+~230 tokens/run) only if the agent should browse a course on its own. Also note `get_material` can shell out to rclone and write to the export cache. That is fine on demand, but it means a scheduled agent that decides to open a material will spawn a subprocess unattended. `check_updates` never does. ### What it will and will not wake you for - Reports: a score posted or changed, a new assignment, a new message, a calendar change. A teacher fixing a typo in an assignment title is classified as `metadata` and raises no alert. - Stays silent: the first run (no baseline means nothing can be "new"); any source that failed to scrape; assignments or events simply expiring off a list. - If a lot changes at once (new grading period, or a partly broken scrape) you get **one** aggregate alert instead of hundreds. ### Failure handling for the calling agent - `status: "error"` → do not touch your stored baseline. Stay quiet for the first couple of failures; if it persists, report it and call `get_health()`. - `status: "suspect"` on a source means *"parsed 0 items but your baseline had many"* — treated as a broken scrape, not as vanished grades. Alerts are suppressed and that source's baseline is echoed back unchanged. - Sources you did not request are passed through untouched, so a cheap `sources=["messages"]` run will not damage your grades baseline. ### Token cost A quiet run (nothing changed) costs roughly **3.7k tokens**, measured: | Component | Tokens | |---|---| | Tool schemas, 7-tool whitelist | ~2,110 | | Baseline passed in | ~1,235 | | Response | ~340 | | Model output | ~15 | Two things keep it there. When nothing moved the reply says `baseline_unchanged` instead of resending an identical 1.2k-token baseline (so the model never has to echo it back either), and per-source health collapses to a one-word status unless you pass `verbose=True` or something is actually wrong. **Polling frequency is by far the biggest lever** — it is pure multiplication: | Schedule | Per day | Per month | |---|---|---| | every 30 min | ~177k | ~5.3M | | hourly | ~88k | ~2.7M | | every 2 hours | ~44k | ~1.3M | | hourly, school hours only (`0 8-18 * * 1-5`) | ~37k | ~1.1M | Grades post in bursts, not continuously, so hourly during school hours catches essentially everything for a fifth of the cost of 30-minute polling. Restrict the tool whitelist too — every unused tool's schema is re-read on every single run. All of which is moot if you use `watch_once.py` above: a quiet run there costs nothing at all, and these numbers apply only when there is actually something to report. Cheaper still: split the schedule. `sources=["messages","upcoming"]` skips both the gradebook page and the calendar feed, so run that often and the full check a few times a day. ### Scheduling notes - Set `SCHOOLOGY_KEEPALIVE=false` for cron-style runs. Each run is a fresh ~30s process, so the 8-minute keep-alive never fires and only competes for the browser lock. - Schoology sessions are short, so an hourly job usually pays a full ClassLink login (tens of seconds). If you want frequent polling, run the server long-lived instead so the session stays warm. - Don't poll more often than about every 30 minutes. Grades post in bursts, each check is several headless page loads, and this is an SSO'd student account. ### Verifying it ```bash python scripts/check_watch.py --fixtures # offline, no login, no network python scripts/check_watch.py --live # against the real account ``` The fixture suite is the one to run after touching a parser: it covers the false-alarm regressions (time-drift, empty-vs-broken, baseline poisoning, first-run silence). Run it before trusting any scheduled job. ## Run ```bash python server.py # speaks MCP over stdio ``` Test interactively with the MCP Inspector: ```bash npx @modelcontextprotocol/inspector python server.py ``` ## Register with Claude Code ```bash claude mcp add schoology -- /your/path/to/schoology-mcp/.venv/bin/python /your/path/to/schoology-mcp/server.py ``` Or add it to an MCP client config (e.g. Claude Desktop `claude_desktop_config.json`): ```json { "mcpServers": { "schoology": { "command": "/your/path/to/schoology-mcp/.venv/bin/python", "args": ["/your/path/to/schoology-mcp/server.py"], "env": { "SCHOOLOGY_USERNAME": "950XXXXX" } } } }</article></body></html>

schoology-mcp

Installation