The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the SuperSaaS Slots listing page.
A read-only MCP server that reports which slots are free on a public SuperSaaS schedule. It covers intraday appointments, date-only schedules such as nightly rentals, and capacity schedules with seats per class. Give it a SuperSaaS schedule URL, or a business page that links to one, such as https://www.down-the-hatch.nl/reserveren/. No account or API key is needed.
Not the official SuperSaaS MCP server. SuperSaaS offers its own server at
https://www.supersaas.com/mcp, which authenticates as your account — via OAuth or a per-account bearer token — and can read and change anything the account can: bookings, users, prices, credit balances. Use that one when the goal is managing your own schedules with an AI assistant. This package answers a different question: what is available on someone else's public schedule, or on your own as a visitor sees it, without credentials and without touching anything. It reads only pages an anonymous browser can already load, never books, and has no account of any kind. Pick by which side of the counter you are on: SuperSaaS's server is the merchant's till, this one is the window display.
Licensed under the MIT License. How the schedule data is read is documented in INTERNALS.md.
After publication, use Python 3.10+:
For local development from the project directory:
Dependencies are declared in pyproject.toml; FastMCP is pinned to version 4.0.10. Both supersaas-slots and supersaas-slots-mcp start the server.
Configure a stdio MCP server in your MCP client:
Replace the command path with the absolute path to your project directory. The client must allow this local process to make HTTPS requests to www.supersaas.nl, www.supersaas.com and www.supersaas.co.uk.
Or run it from PyPI with uvx:
find_available_slots| Parameter | Default | Notes |
|---|---|---|
schedule_url | required | A SuperSaaS /schedule/ URL on supersaas.nl, supersaas.com or supersaas.co.uk, or a third-party page linking to exactly one. www., m. and d. hosts are all accepted and reported as the canonical www. URL. |
from_date | required | YYYY-MM-DD, inclusive. |
through_date | required | YYYY-MM-DD, inclusive. Up to 366 days. |
max_results | 500 | Caps the returned slots list; count is always the full number. |
respect_booking_window | true | Apply the schedule's minimum and maximum advance-booking limits. Set false to examine historical data. |
schedule_url may be a business page instead. The server scans it for a link to a SuperSaaS schedule, follows it, and reports the origin as linked_from. If the HTML names none — single-page sites keep the link in a bundled script — it also scans the page's own JS files, limited to the same origin and to the first ten scripts.
Times are schedule wall-clock strings, YYYY-MM-DD HH:MM. truncated describes slots only, so compare it against count before treating a list as complete. Data is re-fetched on every call, so results change as other people book.
unit is slot, night, or class. Appointment schedules return slot with duration_minutes set to the appointment length. Date-only schedules such as rentals return night and add three fields:
Each slots entry is one night, from check-in on a date to check-out on the next; duration_minutes is the nominal 1440-minute night. stays merges consecutive free nights into the ranges you can actually book, so four adjacent nights become one four-night stay. Use slots when pricing per night and stays when offering a date range to the customer.
Capacity schedules, such as Jazzercise, return unit: "class" and one entry per class with an ordinary seat available:
The class id is SuperSaaS's slot ID. A class with unlimited capacity has null for capacity and available. SuperSaaS includes waiting-list places in booked, so available is capacity - booked + waiting. Classes without an ordinary seat are excluded, even when the schedule offers a waiting list. Class lengths can vary, so there is no top-level duration_minutes in this mode.
Every error names a cause, and most have a remedy:
| Error | What to do |
|---|---|
| Page asks the visitor to pick a resource | Pass one resource URL, such as .../Meeting_Rooms/Room_1 or .../Rental_Homes/House_1. |
| Page links to several schedules | The message lists them; pass the intended one directly. |
| Schedule is kept behind a login | Nothing to do — the schedule is not public. |
| Capacity schedule publishes no public slots | The schedule does not expose class data without a login. |
| This is a service schedule | A catalogue of services booked across shared staff. Nothing to do. |
| Schedule declares no start-time grid | Visitors pick their own start and end times, so there is no fixed grid. Nothing to do. |
| Schedule books in multi-day units | A two-day-or-more product. Nothing to do. |
| Schedule publishes opening hours but no start times | Nothing to do — slots are generated per request. |
| URL is not a public SuperSaaS HTTPS page | Use https:// with no credentials or custom port. |
Supported: public resource schedules with a single resource, fixed appointment duration, weekly opening hours with per-day exceptions and blocked ranges, booked appointments, buffer time, advance-booking limits, and both slot and night units. Public capacity schedules list classes with available seats, including each class's title, location, capacity, booked and waiting counts, and remaining seats.
SuperSaaS offers three schedule types; service schedules are reported as unsupported. Also not modeled: recurring rules, per-user limits, minimum-stay rules, and payment-dependent availability. An available slot is a calculated candidate, not a booking guarantee — the booking page remains authoritative at reservation time.
The tests run offline against saved copies of three real resource schedules and a Jazzercise capacity response, so they do not drift as customers book. See INTERNALS.md for what each fixture pins.
Releases use PyPI Trusted Publishing and MCP Registry GitHub OIDC. Before the first release:
pypi environment in this GitHub repository and allow deployment from version tags. In PyPI, register a pending trusted publisher for owner RichieB2B, repository supersaas-slots-mcp, workflow release.yml, and environment pypi. The PyPI project does not need to exist yet.mcp-registry GitHub environment and allow deployment from version tags. The Registry uses GitHub OIDC, so it needs no registry token.pyproject.toml, server.json (both version fields), and the FastMCP server constructor in sync. check_release.py verifies this and accepts the candidate tag with --tag v0.3.1. Commit the release before tagging it.git tag v0.3.1 && git push origin v0.3.1.The release workflow tests and builds the distribution, publishes it to PyPI, then submits server.json to the MCP Registry. The CI workflow runs tests and package checks on pushes and pull requests. A pushed release tag publishes externally; review its commit and environment settings first.