Schoology MCP

An MCP server for PAUSD Schoology (https://pausd.schoology.com). It drives a headless browser that logs in automatically through the ClassLink portal and exposes tools to fetch grades, upcoming assignments and recent posts.

It builds on the scraping approach from dajun666/schoology-get (Playwright + BeautifulSoup), and adds the missing piece: automated login — no more hand-exporting cookies.json.

How login works

PAUSD students reach Schoology through ClassLink. The server:

1. Opens https://launchpad.classlink.com/pausd and fills the student ID + password.

2. Clicks the Schoology tile, which performs SAML SSO into Schoology.

3. Saves the session to storage_state.json so later runs skip the login until it expires (then it logs in again automatically).

Setup

python3 -m venv .venv
source .venv/bin/activate          # do this in every new shell

pip install -r requirements.txt
playwright install chromium

cp .env.example .env
# edit .env: set SCHOOLOGY_USERNAME (your 8-digit student ID)

# store the password in the OS keychain -- not in any file:
python scripts/set_credentials.py

The python … commands below assume this .venv is activated. The MCP server itself runs outside any shell, so it is registered with the venv's Python by absolute path — see Register with Claude Code.

Credentials & password storage

The password is never stored in a plaintext file. set_credentials.py saves it to the OS keychain (macOS Keychain) via the keyring library — encrypted at rest and unlocked by your macOS login. The server reads it from there at runtime.

• Update it later: re-run python scripts/set_credentials.py.

• Remove it: python scripts/set_credentials.py --delete.

• macOS may ask once to allow access to the keychain item — choose Always Allow so the unattended server isn't blocked.

• SCHOOLOGY_USERNAME (the student ID) stays in .env; it is the keychain lookup key, not a secret.

• Fallback: if you set the SCHOOLOGY_PASSWORD environment variable, it is used instead of the keychain (handy for throwaway/CI use).

Caveat: the keychain protects the password at rest and keeps it out of dotfiles, backups and git — but any process running as your macOS user can still read it. It is strictly better than a plaintext .env, not a sandbox.

Verify login (do this first)

python scripts/login_check.py --show-browser

This logs in, saves storage_state.json, and dumps page HTML into dumps/. All four parsers are verified against a real PAUSD account (grades, courses, upcoming assignments, recent posts). If Schoology changes its markup later, re-run this and re-check the selectors in schoology_mcp/parsers.py against the fresh dumps/.

Tools

Run

python server.py            # speaks MCP over stdio

Test interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector python server.py

Register with Claude Code

claude mcp add schoology -- /Users/roy/projects/schoology-mcp/.venv/bin/python /Users/roy/projects/schoology-mcp/server.py

Or add it to an MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "schoology": {
      "command": "/Users/roy/projects/schoology-mcp/.venv/bin/python",
      "args": ["/Users/roy/projects/schoology-mcp/server.py"],
      "env": {
        "SCHOOLOGY_USERNAME": "950XXXXX"
      }
    }
  }
}

No password appears in the config — it is read from the OS keychain (set once via scripts/set_credentials.py). SCHOOLOGY_USERNAME can come from .env or the env block above.

Sessions & auto-refresh

Schoology sessions expire quickly. The server handles this automatically:

• Detect-and-retry — every tool call checks (by page content, not just URL) whether the page it got back is really logged in. If the session died, it re-logs in via ClassLink and retries — a call never silently returns logged-out data.

• Keep-alive — a background task re-visits Schoology every SCHOOLOGY_KEEPALIVE_MINUTES (default 8) to keep the session warm, so interactive calls rarely wait for a fresh login.

• Persistence — the refreshed session is saved to storage_state.json, so restarting the server reuses it instead of logging in again.

Set SCHOOLOGY_KEEPALIVE=false to disable the background task; detect-and-retry still applies.

Notes

• .env and storage_state.json hold credentials/session — they are git-ignored. Never commit them.

• Set SCHOOLOGY_HEADLESS=false in .env to watch the browser while debugging.

Contributing

Feature requests and issues are always welcomed — open one on the issue tracker or send a PR.

Forking for your own district

This repo is hard-wired to PAUSD (pausd.schoology.com + the ClassLink /pausd tenant). It is intentionally easy to retarget: fork the repo and edit the two URLs (and, if your district doesn't use ClassLink SSO, schoology_mcp/auth.py).

If you ship a working fork for another district, open an issue with a link — we can list known-good forks here.

License

MIT — fork it, ship it, no warranty.

Star History