TheirCare MCP

A local MCP server and companion for viewing and managing TheirCare / FullyBooked bookings through an AI assistant.

Read bookings, check availability, and prepare booking/cancellation previews. Review changes, fees and terms in the companion before personally saving.

Unofficial community project. Not affiliated with, endorsed by, or supported by TheirCare or FullyBooked. Early release using the undocumented family portal; requires an existing TheirCare account.

Quick start

Install Node.js 22 or newer and Git:

git clone https://github.com/acousland/theircare-mcp.git
cd theircare-mcp
npm ci
npm start

Open http://127.0.0.1:43817.

Choose Try sample data for a fictional demonstration without an account, or sign in with your TheirCare email/password. Browse Your bookings and Find a day. Selecting dates prepares an unsaved preview. Review the conditions and accept the terms before personally clicking the final save button.

To leave sample mode, select Disconnect, then sign in. Sample mode cannot save to a real account.

Terminal commands work on macOS, Linux and Windows with supported Node installations. Automated checks run across those platforms; live account testing has been performed on macOS.

Related MCP server: Twill

Connect your AI assistant

Uses stdio MCP. No OpenAI API key, cloud server or public tunnel is needed. Your assistant needs local MCP support.

npm run config

This prints configuration with the actual Node executable and absolute server path on your machine.

Codex

Run the registration command printed by npm run config, shaped like:

codex mcp add theircare-local -- "/absolute/path/to/node" "/absolute/path/to/theircare-mcp/src/mcp.js"

Ask the assistant to check theircare_status. If tools are missing, reconnect MCP or start a new chat. Remove the registration with:

codex mcp remove theircare-local

Other local MCP clients

Add the JSON printed by npm run config to your client's local MCP settings:

{
  "mcpServers": {
    "theircare-local": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/theircare-mcp/src/mcp.js"]
    }
  }
}

The MCP server automatically starts the companion. Open its URL to sign in personally; keep passwords out of AI conversations.

What you can ask

• “What care is booked next week?”

• “Is after-school care available next Wednesday?”

• “Prepare a preview to cancel Friday's after-school care.”

The assistant should first call account_context for current child, service and care-type IDs. Never hard-code another account's IDs.

Date ranges use inclusive start / exclusive end, up to 93 days. Previews support 1–31 dates for one child, care type and calendar year.

There is no MCP tool for final saving or accepting terms. You confirm personally in the companion. One preview is active at a time, expiring after five minutes. Before saving, the adapter refreshes availability and review; changed fees/terms/state invalidate the old preview. It submits once, then checks the saved calendar. Check bookings before retrying an uncertain result.

Privacy and local operation

• Passwords go over HTTPS only to theircare.fullybookedccms.com.au, never to disk or the AI.

• Portal cookies stay in process memory. Disconnecting/stopping clears the session.

• Only information needed for child/service selection is extracted. No payment, subsidy, medical-record or contact-editing tools are exposed.

• MCP results go to your chosen AI client and may be processed by its model provider.

• The companion listens only on 127.0.0.1:43817, with Host/Origin checks and separate browser/MCP access.

• .runtime/connection.json holds a bridge credential. Git ignores it and packages exclude it. Never share .runtime.

• The browser confirmation boundary prevents saving through the provided MCP tools; it is not isolation from malicious software running as your OS user.

• Run on a trusted local computer. Do not expose through a proxy or public tunnel.

To stop and clear the session:

npm run stop

An enabled MCP client can restart the companion; remove/disable its registration to keep it stopped.

Updating

Stop the companion first, then:

git pull --ff-only
npm ci
npm start

Sign in again. Dependencies are pinned in package-lock.json.

Validation and limits

Live-verified: password sign-in, children/care types, bookings, availability, and unsaved booking/cancellation reviews with policies and terms. Test previews were discarded.

Final saving is implemented but tested only against fictional responses. No live final save was made during development. Check the official portal after any intended real change.

• Password sign-in only; passkeys, CAPTCHA and extra verification are unsupported.

• Waitlist actions have offline coverage but await live validation.

• Multi-service accounts, alternate session types, block bookings and excursions/authorisations need more validation.

• This release uses Australia/Melbourne, matching the live-tested service. Other service time zones are not supported yet.

• FullyBooked's feed marks local clock components with Z. The adapter preserves official-portal display hours and emits Melbourne offsets.

• Only TheirCare's portal hostname is supported, not all FullyBooked operators.

• The undocumented portal can change without notice.

Troubleshooting

Development

npm ci
npm run check
npm test

Tests use fictional responses and need no live account.

npm run test:mcp

The optional transport check verifies MCP initialization/tool discovery. In explicitly selected sample mode it reads fictional data and creates an unsaved sample preview. With a real account it checks status only. It never performs a final save.

See CONTRIBUTING.md, SECURITY.md and the MIT licence.

Codex registration follows the official MCP documentation.