# 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](https://github.com/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](https://developer.1password.com/docs/cli/) with an item named `Parentsquare` (fields `username` and `password`)

## Setup

```bash
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:

```bash
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

```bash
pnpm start
```

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

```json
{
  "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](LICENSE). Copyright (c) 2026 Scott Weaver; based on [thehesiod/psquare-mcp](https://github.com/thehesiod/psquare-mcp/) by Alexander Mohr (also MIT). Optional PDF support uses `pdf-parse`, which has its own license terms.