psquare-mcp

# ParentSquare MCP Server

[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io) [![PyPI](https://img.shields.io/pypi/v/parentsquare-mcp)](https://pypi.org/project/parentsquare-mcp/)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives Claude access to [ParentSquare](https://www.parentsquare.com), a school-parent communication platform. Since ParentSquare has no public API, this server scrapes the web interface using saved session cookies.

Covers both the **parent/guardian experience** (feeds, posts, calendars, messages, directories, sign-ups, forms, payments) and **school admin roster management** — reading student and guardian rosters, and creating/editing students and guardians plus sending registration invitations. Admin write tools are **off by default**, gated behind `PS_ENABLE_WRITES`, and every write is recorded to a local audit log.

Available on the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.thehesiod/psquare` and on [PyPI](https://pypi.org/project/parentsquare-mcp/) as `parentsquare-mcp`.

## Disclaimer

> **This project is not affiliated with, endorsed by, or sponsored by ParentSquare, Inc.** "ParentSquare" and all related names, logos, and trademarks are the property of ParentSquare, Inc.
>
> This server communicates with ParentSquare's **undocumented internal APIs** (scraping the web UI and calling its non-public `/api/v2/` JSON endpoints) — these are not published, not guaranteed to be stable, and may change or be blocked at any time without notice. Use of those interfaces may violate ParentSquare's Terms of Service; you are responsible for reviewing the ToS and deciding whether your use is acceptable.
>
> **Use at your own risk.** The authors and contributors accept no responsibility for any consequences of using this software, including but not limited to: account suspension or termination, data loss or corruption, missed or incorrect notifications, MFA lockouts, leaked session cookies, IP blocks, or any other direct or indirect damages. No warranty is provided — see [LICENSE](LICENSE) for the full MIT no-warranty clause.
>
> If ParentSquare publishes an official API, this project should be considered deprecated in favor of that.

## Features

### Feed & Posts
- **`get_feeds`** — Browse paginated school feed with titles, authors, summaries, and attachment names
- **`get_post`** — Full post details with body text, comments, poll results, signup items, and **inline image/PDF content** (Claude can "see" attached calendars, flyers, etc.)
- **`get_group_feed`** — Posts from a specific group

### Calendar
- **`get_calendar_events`** — Events from ICS calendar as structured JSON (title, start/end, location, description)
- Falls back to guiding Claude to search feed posts for image/PDF calendars when ICS is empty

### Communication
- **`list_conversations`** / **`get_conversation`** — Read message threads
- **`get_directory`** — Staff directory as structured JSON (name, role, phone, user_id)
- **`get_staff_member`** — Full staff details with email, office hours, and **inline profile photo**

### Media & Files
- **`list_photos`** — Photo gallery with URLs
- **`list_files`** — Document files
- **`download_file`** — Download any attachment to local disk

### Participate
- **`list_signups`** — Sign-up and RSVP posts with progress tracking (e.g. "53/103 Items")
- **`list_notices`** — Alerts and secure documents
- **`list_polls`** — Polls with vote counts and winning options
- **`list_forms`** — Permission slips and signable forms
- **`list_payments`** — Payment items with prices and summary stats
- **`list_volunteer_hours`** — Logged volunteer hours with totals

### Groups & Discovery
- **`list_schools`** — Schools and students as structured JSON
- **`list_school_features`** — Available sections per school (parsed from sidebar)
- **`list_groups`** — Groups with member counts, descriptions, and membership status
- **`list_links`** — Quick-access links (Google Drive, external sites)

### Student
- **`get_student_dashboard`** — School, grade, classes, and teachers as structured JSON

### Admin (roster: students & guardians)
Read tools are always available; **write tools are disabled by default** and only run when `PS_ENABLE_WRITES` is set (see below). Every write is recorded to a local audit log. v1 is create/edit only — no destructive operations.
- **`list_students`** — School roster (id, name, grade, SIS id, guardians) as structured JSON, with optional `grade` / `name_contains` filters
- **`list_parents`** — Guardian roster (user_id, name, email, phone, linked students) as structured JSON, with optional `name_contains` / `student_name_contains` filters; provides the `user_id` needed by `edit_parent` / `link_guardian_to_student`
- **`list_grades`** — A school's grades and their `grade_id` values (needed for add/edit)
- **`get_student`** — Admin detail for one student (name, grade, SIS id, linked guardians, classes)
- **`add_student`** *(write)* — Create a student in a grade
- **`edit_student`** *(write)* — Update a student's name, SIS id, or grade (unchanged fields preserved)
- **`add_parent`** *(write)* — Create a guardian linked to a student
- **`edit_parent`** *(write)* — Update a guardian's name, email, or phone (existing links preserved)
- **`link_guardian_to_student`** *(write)* — Link an existing guardian to an additional student
- **`invite_parent`** *(write)* — Send (or resend) a ParentSquare registration invitation to one guardian
- **`bulk_invite_parents`** *(write)* — Invite many guardians at once; already-registered guardians are skipped automatically

### Admin (classes, staff & enrollment)
Same write gate and audit log as above; no deletion of classes or staff.
- **`list_classes`** / **`get_class`** — A school's classes, and one class with its full staff list (teachers, assistants, room parents)
- **`add_class`** *(write)* — Create a class; new classes start **hidden** until `set_class_visibility`
- **`edit_class`** *(write)* — Rename a class or change its grades
- **`set_class_visibility`** *(write)* — Show or hide classes (date-driven, defaults to today)
- **`list_staff`** — Staff and admin roster (user_id, name, email, phone, role/title) as structured JSON, with an optional `name_contains` filter; provides the `user_id` needed by `edit_staff` / `add_class_staff`
- **`add_staff`** *(write)* — Add a teacher, staff member, or admin, optionally assigning them to classes
- **`edit_staff`** *(write)* — Update a staff member's name, email, phone, title, or staff ID (class assignments and STAFF/ADMIN access preserved; guardians are rejected — use `edit_parent`)
- **`add_class_staff`** / **`remove_class_staff`** *(write)* — Assign or unassign teachers, assistants, and room parents for a class. Section-membership writes are serialized inside one server process; never issue them in parallel, and verify each result with a fresh read.
- **`list_class_students`** — The students enrolled in a class
- **`add_class_students`** / **`remove_class_students`** / **`move_student_to_class`** *(write)* — Manage which students are enrolled in which classes. These share the same global serialization lock as class-staff writes because student-section updates can replace a student's full enrollment list.

### Authentication
- **`submit_mfa_code`** — Complete MFA verification with a 6-digit code
- Supports MCP elicitation for inline MFA prompts (set `PS_NO_ELICIT` to disable for unattended callers)
- Session cookies persisted to `~/.parentsquare_cookies.json`
- Credentials loaded from environment variables, 1Password, or LastPass CLI on session expiry

## Setup

### Enabling admin write tools

The admin write tools (`add_student`, `edit_student`, `add_parent`, `edit_parent`,
`link_guardian_to_student`) modify the live school roster, so they are **off by
default**. To enable them, set `PS_ENABLE_WRITES=1` (or `true`/`yes`/`on`) in the
server's environment and restart. Every write attempt (including blocked ones) is
appended as JSONL to `PS_AUDIT_LOG` (default `~/.parentsquare_audit.log`). Read
tools (`list_students`, `list_parents`, `list_grades`, `get_student`) work regardless.

ParentSquare's form endpoints answer every accepted POST with the same generic
`200` "reload" response, which some silent failures also return. To avoid
false-positive successes, the create/link tools (`add_student`, `add_parent`,
`link_guardian_to_student`) **read back authoritative state after the write** and
only report `✅ Success (verified)` once the new record is actually found. If the
POST is accepted but the read-back can't find the change, they return a `⚠️`
warning that it likely did not persist; if the read-back itself can't run, they
report the write as submitted-but-unverified.

The read-back also overrules a `5xx`. ParentSquare renders its error page *after*
the transaction commits, so a server error can hide a write that actually landed
— `add_student` did exactly that on every create until a missing
`student[section_ids][]` form param was tracked down. Reporting those as failures
invited retries, and each retry duplicated a real student with no API route to
delete one. So when a write returns a `5xx` but the record is found on read-back,
the tool reports `✅ Success (verified)` with a note not to retry. An explicit
rejection (a `4xx`, or a `200` carrying an `alert-danger` flash) is still
reported as a failure regardless of read-back.

### Prerequisites

Credentials can be provided in either of two ways (checked in this order):

1. **Environment variables** — set `PS_USERNAME` and `PS_PASSWORD`
2. **A credential manager** selected by `PS_CREDENTIAL_PROVIDER` (default `1password`):
   - **[1Password CLI](https://developer.1password.com/docs/cli/)** (`op`) — with a "Parentsquare" item containing `username` and `password` fields
   - **[LastPass CLI](https://github.com/LastPass/lastpass-cli)** (`lpass`) — set `PS_CREDE