Skip to main content
Glama
parentsquare-mcp
by tdlm

ParentSquare MCP (TypeScript)

A local MCP server that lets Claude, Cursor, and other MCP clients read your ParentSquare account: feeds, calendar, messages, directory, groups, and the rest. ParentSquare does not publish a public API, so this talks to the same web pages and internal endpoints the site uses in a browser.

This repo is a TypeScript port for local use. The original Python implementation is thehesiod/psquare-mcp (MIT). That project did the hard work of mapping ParentSquare's HTML, JSON:API, GraphQL, and ICS endpoints. This port follows the same behavior and tool names.

Disclaimer

This project is not affiliated with ParentSquare, Inc. It uses undocumented internal APIs that can change or stop working without notice. You are responsible for deciding whether that fits ParentSquare's terms and your own risk tolerance. Session cookies and credentials stay on your machine, but treat them like passwords.

Related MCP server: pronote-mcp

What you can do

The server exposes the same 23 tools as the Python version, including:

  • Feeds and posts (get_feeds, get_post, get_group_feed)

  • Calendar (get_calendar_events)

  • Messages (list_conversations, get_conversation)

  • Directory (get_directory, get_staff_member)

  • Photos and files (list_photos, list_files, download_file)

  • Sign-ups, notices, polls, links, payments, volunteer hours, forms

  • Schools, groups, and student dashboard (list_schools, list_groups, get_student_dashboard)

  • MFA (submit_mfa_code)

get_post can return inline images. PDF text extraction works if you install the optional pdf-parse dependency (pnpm install picks it up from optionalDependencies when available).

Requirements

  • Node.js 20+

  • pnpm

  • ParentSquare login credentials, either:

    • PS_USERNAME and PS_PASSWORD environment variables, or

    • 1Password CLI with an item named Parentsquare (fields username and password)

Setup

git clone <this-repo>
cd parentsquare-mcp
pnpm install

On first run the server loads saved cookies from ~/.parentsquare_cookies.json if present. When the session expires it re-authenticates using env vars or 1Password. MFA codes go through the submit_mfa_code tool.

To bootstrap cookies manually without storing a password in env:

pnpm export-cookies

That walks you through copying the Cookie header from Chrome DevTools (the ps_s session cookie is httpOnly, so the Network tab is required).

Run locally

pnpm start

The server speaks MCP over stdio. Point your client at it with something like:

{
  "mcpServers": {
    "parentsquare": {
      "command": "node",
      "args": ["/absolute/path/to/parentsquare-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/parentsquare-mcp",
      "env": {
        "PS_USERNAME": "your@email.com",
        "PS_PASSWORD": "your-password"
      }
    }
  }
}

Run pnpm build after cloning or pulling changes so dist/ exists. Use node with the compiled entry point rather than pnpm exec tsx: Cursor's MCP spawn environment often does not include Homebrew's pnpm on PATH.

Replace the paths with your checkout location. If you use 1Password instead of env vars, omit the env block.

Environment variables

Variable

Purpose

Default

PS_USERNAME

Login email

—

PS_PASSWORD

Login password

—

PS_COOKIE_FILE

Cookie JSON path

~/.parentsquare_cookies.json

PS_DOWNLOAD_DIR

download_file target

~/Downloads/parentsquare

How it works

Each tool fetches HTML or JSON from ParentSquare, parses it (cheerio for HTML, node-ical for calendars), and returns markdown or JSON. The HTTP client keeps cookies fresh, re-logs in when redirected to /signin, and sends a Chrome User-Agent because ParentSquare returns 403 otherwise. Schools, students, and your user ID are discovered from page content on first use. No config file lists your schools.

License

MIT. See LICENSE. Copyright (c) 2026 Scott Weaver; based on thehesiod/psquare-mcp by Alexander Mohr (also MIT). Optional PDF support uses pdf-parse, which has its own license terms.

Available Tools

23 tools
download_fileB

Download a photo, video, or file to local disk from a ParentSquare URL.

Inputs: url (required), filename.

get_calendar_eventsB

Get calendar events for a school using the ICS calendar export.

Inputs: school_id (required).

get_conversationA

Read a specific message conversation thread with all messages.

Inputs: chat_id (required), school_id (required).

get_directoryA

List school contact info and staff directory with names, roles, and phone numbers.

Inputs: school_id (required).

get_feedsC

Get recent posts from a school's feed with titles, authors, dates, and summaries.

Inputs: school_id (required), page.

get_group_feedB

Get posts from a specific group's feed.

Inputs: group_id (required), school_id (required).

get_postA

Get full details of a specific post including body text, comments, and attachments. Image attachments are returned inline; PDF text is extracted when pdf-parse is installed.

Inputs: feed_id (required).

get_staff_memberA

Get detailed info for a specific staff member including email, photo, and office hours.

Inputs: user_id (required), school_id (required).

get_student_dashboardB

Get student dashboard information including school, grade, classes, and teachers.

Inputs: student_id (required).

list_conversationsC

List message conversations for a school.

Inputs: school_id (required).

list_filesA

List files and documents posted for a school.

Inputs: school_id (required).

list_formsC

List available forms and permission slips for a school.

Inputs: school_id (required).

list_groupsA

List groups at a school with member counts and descriptions.

Inputs: school_id (required).

list_noticesC

List alerts and notices for a school.

Inputs: school_id (required).

list_paymentsA

List payment items for a school with summary stats and item prices.

Inputs: school_id (required).

list_photosB

List photos posted for a school.

Inputs: school_id (required), page.

list_pollsB

List polls for a school with questions, options, and vote counts.

Inputs: school_id (required).

list_school_featuresA

List features available for a specific school by parsing its sidebar navigation.

Inputs: school_id (required).

list_schoolsA

List available schools and students in your ParentSquare account. Returns JSON with schools, students, and your user ID.

Inputs: no named parameters.

list_signupsC

List sign-up and RSVP posts for a school.

Inputs: school_id (required), page.

list_volunteer_hoursA

List your logged volunteer hours for a school.

Inputs: school_id (required).

submit_mfa_codeA

Submit a 6-digit MFA verification code to complete ParentSquare login. When a ParentSquare tool returns an MFA error, check your email for the code.

Inputs: code (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 23 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: list_schools, get_post, download_file, list_polls, etc. Even the many list_* tools are clearly differentiated by their resource type (feeds, conversations, photos, files, signups, notices, etc.). No overlapping purposes.

    Naming Consistency5/5

    All tool names follow a consistent lowercase_snake_case verb_noun pattern, using list_, get_, download_, or submit_. There is no mixing of naming conventions or vague verbs.

    Tool Count4/5

    23 tools is on the higher side but justified by the wide domain coverage (authentication, schools, feeds, messages, calendar, media, directory, groups, payments, forms). While it feels slightly heavy, each tool represents a distinct feature area.

    Completeness3/5

    The tool set is read-focused, covering most informational resources (feeds, posts, conversations, calendar, photos, files, directory, groups, dashboard, signups, notices, polls, links, payments, volunteer hours, forms). However, there are no write operations (e.g., creating posts, responding to signups, submitting forms), and some detail endpoints like individual calendar events are missing, leaving notable gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A local MCP server that exposes Pronote (French school management system) data via MCP, enabling AI assistants to retrieve schedules, homework, grades, absences, and more. Supports token-based authentication with QR code setup.
      -