Read your child's school news from the terminal, a desktop app or Claude: an unofficial client and API description for Parro, the Dutch parent–school communication app by Topicus (ParnasSys). It reads announcements, newsletters (including the text inside PDF attachments), the calendar, chats and class info, and shows what you have not read yet. It can change five things, only when you ask: mark items as read, send a text message to a chat you are in, delete a chat message you wrote, sign you up or withdraw you as a helper for a calendar item, and answer a calendar item's invitation.
All pictures in this README show invented example data from the test suite.
Not affiliated with or endorsed by Topicus, ParnasSys or Parro. Behaviour was observed, not documented by the vendor, and may change at any time. Only calls seen in the Parro web app and the standard OAuth2 login flow are used and described.
- Install it, on Windows, macOS or Linux (Python 3.10 or newer). pipx
or uv keep it in its own environment and put the commands on your
PATH:
Or
pipx install parro-api-client
uv tool install parro-api-client. To read PDF newsletters as text, install"parro-api-client[attachments]"instead. Straight from GitHub:pipx install git+https://github.com/chris-swift-dev/parro-api-client. - Log in. You type the password; the login then lasts up to 8 hours:
parro-client login --prompt
- See what is new:
parro-client overview
Update with pipx upgrade parro-api-client. Without installing anything: download a release
from the Releases page, unpack it,
and run python3 parro_cli.py wherever this README says parro-client.
A window instead of a terminal: see Desktop app. For Claude and other MCP clients, see MCP server. API explorers: the spec is browsable in Swagger UI; the project page has the downloads.
parro-client |
a command-line client: readable markdown at a terminal, JSON when piped (jq) |
parro-client-mcp |
an MCP server over stdio for Claude and other MCP clients |
parro-client-gui |
a desktop app for Windows, macOS and Linux (optional, Python 3.12+) |
parro/ |
the library they all use: login, API calls, summaries, attachments |
openapi/parro.public.openapi.json |
the OpenAPI 3.0.3 description of the API (contract version 224) |
The Parro web app talks to a Topicus "geon" REST API at https://rest-v2.parro.com/rest/v2. This
client speaks that API and adds three things:
- It strips the geon boilerplate. A three-group list is 2.8 KB of JSON carrying about 300 bytes
of information. Every command returns a compact summary;
--raw(MCP:raw: true) gives the untouched payload. - It reads attachments. Newsletters arrive as PDFs;
attachment/parro_attachmentreturns their text. Photos come back as images (MCP) or can be saved (CLI). - It shows the data the way the app does. Announcements once each with author and groups, an agenda per day, conversations in reading order, an overview of what is new. Every id stays visible, so the next command is always at hand.
It reads. It can change five things in Parro, and only when you ask for it:
mark an item as read, send a text message to a chat you are in, delete a message you wrote, sign up
or withdraw as a helper, and answer an invitation: see Changing things in Parro. Apart from those three PUT …/read calls, the
POST and the DELETE of a message, the POST and DELETE of a helper sign-up and the POST of an answer, the
Parro API only receives GET; the other POST requests go to the login server's token, revoke and login-form
endpoints. Standard library only; PyMuPDF / pypdf (PDF text)
and Pillow (photo downscaling) are optional.
flowchart LR
you([You, at a terminal]) --> cli[parro-client]
claude([Claude or another MCP client]) --> mcp[parro-client-mcp]
desktop([You, in a window]) --> gui[parro-client-gui]
gui --> core
cli --> core["parro/<br>login · API calls · summaries · markdown"]
mcp --> core
core -- "GET; mark as read, send a message, sign up as helper, answer an invitation when you ask" --> api[(Parro REST API)]
core -- "login, refresh, logout" --> idp[(ParnasSys login server)]
core -- "attachments" --> cdn[(Attachment CDN)]
core --- disk[("~/.parro: tokens, cache, archive")]
At a terminal the CLI prints markdown; piped into another program it prints JSON. --format (or
PARRO_FORMAT) chooses explicitly. Dates are shown in the school's time zone, labels are English,
content is shown as written. Calendar items that ask parents to help (driving, reading aloud) are
marked helpers wanted; with --details you see each slot's id, how many signed up, and whether
you did.
The agenda: calendar --details
Announcements: announcements
tests/snapshots/ holds the output of every view.
parro-client --help
parro-client login --prompt # type the password; the login lasts up to 8 hours
parro-client status
parro-client overview # what is new: unread announcements, new calendar items
parro-client overview --all # the latest announcements and everything coming up
parro-client announcements --limit 5 --unread-only
parro-client attachment <announcement-id> --text
parro-client calendar --details # agenda with location, description and helper slots
parro-client calendar-link # Parro's own link to subscribe from Google/Apple/Outlook
parro-client calendar --ics parro.ics --details # or: an .ics file to import
parro-client sync # keep a local archive (repeat to update)
parro-client privacy # can you still change your children's privacy choices?
parro-client chatrooms --archived include --type group
parro-client chat-messages <chatroom-id> --since 2026-10-01 --mark-read
parro-client mark-read announcement <id> # the school can see this
parro-client chat-send <chatroom-id> "Ik kan rijden op de 12e" # shows who receives it, then asks
parro-client helper signup <event-id> --count 3 # shows the slot, then asks
parro-client rsvp accept <event-id> # or decline, tentative; shows your old and new answer, then asks
parro-client announcements --format json | jq '.announcements[].title'
parro-client get /accountsettings
parro-client token # paste into Swagger UI → Authorize → bearerTokenAll commands and options
Commands: login [--prompt], logout, status, token, login-url, login-finish <url>,
overview [--all], me, children, privacy [--link CHILD_ID], groups [--previous], unread,
system-news [--full], announcements [--group ID] [--limit N] [--unread-only] [--full],
announcement <id> [--mark-read], calendar [--group ID] [--limit N] [--details] [--past] [--ics FILE],
calendar-link, attachment <event-id> [--attachment-id ID | --all] [--save-to DIR] [--text],
attachment --chat <chatroom-id> --message <message-id> [--save-to DIR],
chatrooms [--unread] [--archived only|include] [--type single|bot|calendar|group|family] [--schoolyear YEAR],
chat-messages <chatroom-id> [--since DATE] [--mark-read], chat-delete <chatroom-id> <message-id> [--yes], chat-members <chatroom-id> [--former],
mark-read announcement|calendar|chat|group <id> [--yes],
chat-send <chatroom-id> [TEXT] [--file PATH] [--yes],
helper signup <event-id> [--slot ID] [--count N] [--yes],
helper withdraw <event-id> [--slot ID] [--yes],
rsvp accept|decline|tentative <event-id> [--yes], sync [--to DIR] [--previous] [--photos],
cache info|clear, get <path> [--param k=v ...] [--limit N] [--offset N],
completion bash|zsh|fish.
Global options: --format auto|json|markdown, --login-method, --raw, --compact,
--no-cache, --verbose. --full shows whole texts instead of a 3-line preview.
Exit codes: 0 ok · 1 API/network error · 2 usage · 3 not logged in · 4 login halted.
Tab completion for commands, options and their fixed values (--format, rsvp accept, …), and
file names where a file or folder is asked. Add one line to your shell's startup file:
eval "$(parro-client completion bash)" # ~/.bashrc
eval "$(parro-client completion zsh)" # ~/.zshrc
parro-client completion fish | source # ~/.config/fish/config.fishCompleting never runs a request and needs no login. Windows PowerShell is not covered.
Prefer a window? The desktop app does what the command line does, on Windows, macOS and Linux.
Without Python: download the installer for your computer from the
latest release: an .msi for
Windows, a .dmg for macOS 14 or newer, a .flatpak for Linux. They are not signed yet, so Windows
and macOS warn at the first start; docs/INSTALL-DESKTOP.md
says what to do.
With Python 3.12 or newer, together with the command line (Qt adds about 300 MB):
pipx install "parro-api-client[gui]"
parro-client-gui
It follows your system's light or dark setting. There is no web server or open port, and text from others stays text. It shares its login, cache and archive with the command line, and it can log in by itself from a password file, with the same one-attempt rule. If you agree, it tells you about a new version, asking GitHub at most once a day and downloading nothing itself. More in docs/DESKTOP-APP.md.
It reads. It can change five things, and only when you ask. Reading something never changes it. The guide has the commands, the refusals and what can be undone.
| What | Command | MCP tool and its switch | Who notices |
|---|---|---|---|
| Mark as read | mark-read announcement <id> |
parro_mark_read, PARRO_ALLOW_MARK_READ=1 |
The school: read counts and read receipts |
| Send a text message to a chat you are in | chat-send <chatroom-id> "text" |
parro_send_chat_message, PARRO_ALLOW_SEND_CHAT=1 |
Real people, under your name. It cannot be taken back |
| Delete a chat message you wrote yourself | chat-delete <chatroom-id> <message-id> |
parro_delete_chat_message, PARRO_ALLOW_DELETE_CHAT=1 |
Everyone in the chat sees that a message was deleted. It cannot be undone |
| Sign up or withdraw as a helper | helper signup <event-id>, helper withdraw <event-id> |
parro_helper_signup, parro_helper_withdraw, PARRO_ALLOW_HELPER_SIGNUP=1 |
The school sees your name, and you may take the last place |
| Answer an invitation | rsvp accept <event-id> (or decline, tentative) |
parro_rsvp, PARRO_ALLOW_RSVP=1 |
The school sees your answer. You can change it, not remove it |
Sending, signing up and answering show what would happen and ask first. Called without
confirm: true, their MCP tools only return that preview.
Think before you switch on a tool for an assistant. An assistant also reads what other people write in Parro. Text in a chat or a newsletter could try to talk it into sending a message, signing you up or answering in your name, and whatever it can read (your children's names, school letters) could end up in a message. Not every one of these tools is marked as destructive, so set your MCP client to ask before each of them, and read the preview before you agree. The guide has the warning for each.
Ask Claude about school, and it reads Parro for you. An illustration with the invented test data:
You: Do I need to do anything for school in the coming weeks?
Claude calls
parro_overview,parro_calendar {"details": true}andparro_announcement, then answers: Two things need a reply: the trip to the Natuurmuseum on Thursday 12 November (group 6 still needs two parents who can drive; there is a permission form attached) and the parent–teacher talks for group 3 on 17 November (pick a ten-minute slot). Friday 13 November is a study day: no school, but the after-school care is open.
It has tools for announcements, attachments (including the text inside PDFs), the calendar, chats, class info and what is new, and for logging in. The tools that change something are off unless you switch them on: see Changing things in Parro. All 25 tools are listed in docs/MCP.md.
With the package installed (Quick start), Claude Code:
claude mcp add parro -s user -- parro-client-mcpClaude Desktop (claude_desktop_config.json) does not see your shell's PATH, so give the full path
of the command: which parro-client-mcp (Windows: where parro-client-mcp) prints it.
{
"mcpServers": {
"parro": {
"command": "/Users/you/.local/bin/parro-client-mcp",
"env": { "PARRO_USERNAME": "you@example.com", "PARRO_PASSWORD_FILE": "/path/to/password-file" }
}
}
}Without installing it first, uv can start it on demand:
"command": "uvx", "args": ["--from", "parro-api-client", "parro-client-mcp"] (also with the full
path of uvx for Claude Desktop). From an unpacked release:
"command": "python3", "args": ["/path/to/parro-api-client/parro_mcp.py"].
Testing without an MCP client: parro-client-mcp tools, then
parro-client-mcp call parro_announcements '{"limit": 5}'. PDF text needs PyMuPDF or
pypdf, photo downscaling Pillow (installed with "parro-api-client[attachments]"); without them
everything else works, and the attachment tool says what to install. Running it in Docker:
DEPLOY.md.
Logging in is OAuth2 against the ParnasSys login server. By default the client does exactly what a
browser does (the login form); tokens are stored in ~/.parro-mcp/tokens.json (mode 0600) and
refresh themselves, but a login lasts at most 8 hours: the login server's limit, however often
the client refreshes. After that, log in again. With PARRO_USERNAME and a password file set, the
client (and the MCP server) logs in again on its own when needed: one password check per 8 hours.
parro-client status (MCP: parro_auth_status) shows until when the current login lasts.
The login server locks the account after a few failed logins. When a password is rejected, the client stops logging in on its own, so a typo costs one attempt, not one per call.
statusthen showsautomatic_login_halted; fix the password and runparro-client loginonce.
Credentials: PARRO_USERNAME plus PARRO_PASSWORD_FILE (or PARRO_PASSWORD), or
login --prompt, or no password at all with login-url / login-finish. Login methods, the
lockout latch and why there is no automatic browser redirect: docs/LOGIN.md.
Every environment variable: docs/CONFIGURATION.md.
- The agenda in your own calendar app:
calendar-linkprints Parro's own subscription link (a secret), andcalendar --ics FILEwrites an iCalendar file. - Your children's privacy choices:
privacyshows per child whether you can still change them, and when and by whom they were last changed. - Your own archive:
synckeeps a local copy of everything your account can see, as files that stay readable without Parro.
All three are explained in docs/CALENDAR-AND-ARCHIVE.md.
openapi/parro.public.openapi.json describes the API as
observed from the web client: 34 operations of the Parro API and the login server's OAuth2 endpoints,
each seen in a live call or a capture of the web app. openapi/README.md
says what it covers and how it is generated; docs/API-NOTES.md lists the
facts the client relies on.
- "Try it out" works once you paste an access token into Authorize → bearerToken
(
parro-client tokenprints one). - Don't log in through Swagger UI. The code flow can't complete there, and failed password attempts count toward the account lockout.
Is this an official Parro tool? No. It is not affiliated with or endorsed by Topicus, ParnasSys or Parro. It uses the same API calls as the Parro web app, as observed from that app.
Can it post, change or delete anything in Parro? It can do five things, and only when you
ask: mark an item as read, send a text message
to a chat you are in, delete a chat message you wrote yourself, sign up or withdraw as a helper, and
answer an invitation. Assistants can do these only if you switch that
on, separately for each. Apart from your own chat messages and taking back your own helper sign-up, it cannot delete anything,
and it cannot start new chats or send attachments. Those are three fixed PUT …/read calls, three
fixed POST calls and two fixed DELETE calls; every other request to the Parro
API is a GET, and the other POST requests go to the login server (logging in, refreshing,
logging out).
Where does my password go? Only to the ParnasSys login server, the same one the web app uses.
login --prompt stores nothing but the tokens (~/.parro-mcp/tokens.json, readable only by you);
logout revokes them. With login-url the client never sees a password at all. Passwords, tokens
and download links are never written to a log.
Can a wrong password lock my account? The login server locks an account after a few failed
attempts, so the client never retries: after one rejected password it stops logging in until you
run login yourself. See docs/LOGIN.md.
What leaves my computer? Only requests to Parro, its login server and its attachment CDN. There is no telemetry. Note that with the MCP server, whatever a tool returns (school news, your children's names, documents) goes to the AI assistant you use, and so to its provider.
Does it work for every school? It was tested with one parent account. The calendar subscription link is part of the paid Parro Ouderapp, so it may not work everywhere; the rest uses the same calls as the web app. Parro can change its API at any time; if something breaks, please open an issue. Security problems: please report them privately, see SECURITY.md.
python3 -m venv .venv && .venv/bin/pip install -r requirements-test.txt
.venv/bin/pytest # no network: fake login server and API, invented family and school
.venv/bin/ruff check . && .venv/bin/mypyRepository layout, snapshots, the README pictures and making a release: docs/DEVELOPMENT.md. A walk through the code: docs/CODE-TOUR.md. How each release was checked against the real API: docs/LIVE-CHECKS.md.
Inspired by fobatai/parro-mcp, a read-only MCP server for Parro by fobatai. Its working login and API calls were the starting point for this follow-up. The client here is an independent implementation based on the OpenAPI specification in this repository.
The desktop app's icons are from Lucide (ISC licence).
- Code (
parro/,parro_gui/,parro_cli.py,parro_mcp.py,tests/,tools/): MIT. - Specification and documentation (
openapi/,docs/, the README files): Creative Commons Attribution 4.0 International (CC BY 4.0) (seeLICENSE). You may share and adapt them for any purpose, provided you give appropriate credit (link to this repository), indicate the license and note any changes you made.
"Parro", "ParnasSys" and "Topicus" are names of their respective owners. They are used here only to identify the API being described.
