ParentSquare MCP

An MCP server that gives Claude read access to your own ParentSquare parent account — school posts, calendars, messages, the staff directory, signups, forms, payments and files.

School calendars and flyers are very often posted as image or PDF attachments rather than as calendar entries. This server downloads them and hands them to Claude as real image/text content, so "what's on the school calendar next week?" works even when the calendar itself is empty.

Before you start: how this connects

ParentSquare has no public parent-facing API. Their documented API is district-side, for pushing student data in from an SIS — it is issued to district IT, not to parents, and it is not what you want here. So this server signs in as you and reads the same parent web app you use in a browser.

Two consequences worth knowing up front:

• You need to supply your own session. See Authentication.

• The page layouts are not a contract. Districts run different versions of the app on different URLs, so there are three layers of defence: every route is a list of candidate paths tried in order; if all of them fail, the section is located by matching its label in your sidebar; and if a parser still finds nothing, it returns the readable page text rather than failing. scripts/doctor.py reports what needed which. See Fitting it to your district.

Related MCP server: unofficial-magister-mcp

Install

cd "~/Desktop/ParentSquare MCP"
python3 -m venv .venv
./.venv/bin/python -m pip install -e .

Authentication

Method 1 — browser cookie (recommended)

Works with every district, including ones that sign in through Google, Clever or ClassLink, and with two-factor accounts.

1. Sign in to ParentSquare in your browser.

2. Open DevTools → Network, click any request to parentsquare.com.

3. Under Request Headers, copy the entire value of Cookie:.

4. Put it in PARENTSQUARE_COOKIE (see Connect it to Claude).

The cookie expires eventually — when tools start reporting that the session expired, repeat this.

Method 2 — email and password

Only works if your district uses a plain ParentSquare password, with no two-factor.

PARENTSQUARE_EMAIL=you@example.com ./.venv/bin/python scripts/login.py

This caches the session in ~/.parentsquare-mcp/session.json (mode 600). If your district uses SSO or 2FA, the script says so and points you back to Method 1.

Connect it to Claude

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "parentsquare": {
      "command": "/Users/chen/Desktop/ParentSquare MCP/.venv/bin/python",
      "args": ["-m", "parentsquare_mcp"],
      "cwd": "/Users/chen/Desktop/ParentSquare MCP",
      "env": {
        "PARENTSQUARE_COOKIE": "_parentsquare_session=…; remember_user_token=…"
      }
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add parentsquare \
  --env PARENTSQUARE_COOKIE="_parentsquare_session=…" \
  -- "/Users/chen/Desktop/ParentSquare MCP/.venv/bin/python" -m parentsquare_mcp

If you used scripts/login.py, the cached session is picked up automatically and you can drop the env block entirely.

See .env.example for every setting.

Fitting it to your district

Run this once after connecting:

./.venv/bin/python scripts/doctor.py

It reports, for every section, which URL works and how many rows the parser got:

— routes —
  ok   feed              /feeds
  ok   directory         /directory
  NAV  payments          /school_pay  (found via the sidebar)
  MISS volunteer_hours   (no candidate worked, and no sidebar link matched)

— tools (23 registered) —
  ok   get_feeds              12 rows
  THIN list_signups           0 rows — selectors need work. Source: https://…/signups

• NAV — none of the guessed URLs worked, so the server found the section by matching its sidebar label instead. This already works; adding the reported path to routes.py just saves a lookup. Districts re-route these pages constantly, which is why label matching is the safety net.

• MISS — no URL worked and no sidebar link matched. Open the section in your browser, copy the path from the address bar, and add it to the front of the matching list in parentsquare_mcp/routes.py. If the sidebar calls it something unusual, adding that word to SECTION_KEYWORDS in the same file fixes it for good.

• THIN — the page loaded but nothing matched. Ask Claude to call debug_fetch on that URL to see the real markup, then adjust the selector list at the top of the relevant file in parentsquare_mcp/tools/. The selectors are plain CSS lists, deliberately easy to edit.

• empty — the page loaded and genuinely has nothing in it. Nothing to fix.

Nothing in the doctor writes to ParentSquare.

Tools

Feed and posts

Calendar

Communication

Media and files

Things to act on

Discovery

Nothing here writes to ParentSquare — every tool is read-only against your account. On your own disk, download_file saves where you ask it to, and get_post saves image-only PDFs (scans, which have no extractable text) to ~/Downloads/ParentSquare so they are still reachable.

Things to try

What did the school send home this week?

Is there anything I still need to sign or pay for?

The October calendar was posted as a PDF — what days is my kid off?

Who is my son's teacher and what's their email?

Tests

./.venv/bin/python tests/run_all.py

Four suites — parsers, tools over HTTP, a real MCP handshake over stdio, and the authentication paths — all against a fake ParentSquare served on localhost. They never touch the real site, so they are safe to run at any time.

Layout

parentsquare_mcp/
  config.py      environment settings
  client.py      auth, HTTP, route fallback, login-bounce detection
  routes.py      candidate URLs + sidebar keywords       ← edit when doctor says MISS
  parsers.py     shared HTML helpers and the fallback result shape
  media.py       attachments → images / PDF text
  tools/         one module per group of tools           ← edit when doctor says THIN
scripts/
  login.py       cache a session with email + password
  doctor.py      check routes and tools against your account
tests/

Notes

• Read-only by design. Nothing posts, replies, signs, pays or RSVPs on your behalf.

• Your credentials stay on your machine: in the client config env block, or in ~/.parentsquare-mcp/session.json at mode 600.

• Because it depends on the parent web app's HTML, a ParentSquare redesign can break parsing. That is what doctor.py and debug_fetch are for, and why nothing hard-fails when a selector misses.