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.

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.