How do I install SuperSaaS Slots?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does SuperSaaS Slots need an API key?

No required environment variable is listed on this record.

What transport does SuperSaaS Slots use?

SuperSaaS Slots runs locally over stdio.

When was SuperSaaS Slots last checked?

Last checked 2026-11-09. Find available appointments on public SuperSaaS resource schedules

SuperSaaS Slots MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx supersaas-slots-mcp==0.3.1

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.richieb2b-supersaas-slots-mcp -- uvx supersaas-slots-mcp==0.3.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.richieb2b-supersaas-slots-mcp": {4      "command": "uvx",5      "args": [6        "supersaas-slots-mcp==0.3.1"7      ]8    }9  }10}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.3.1
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

SuperSaaS slots MCP server

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.

Install

After publication, use Python 3.10+:

pip install supersaas-slots-mcp

For local development from the project directory:

python3 -m venv .venv
.venv/bin/python -m pip install -e .

Dependencies are declared in pyproject.toml; FastMCP is pinned to version 4.0.10. Both supersaas-slots and supersaas-slots-mcp start the server.

Connect

Configure a stdio MCP server in your MCP client:

{
  "mcpServers": {
    "supersaas-slots": {
      "command": "/absolute/path/to/supersaas-mcp/.venv/bin/supersaas-slots"
    }
  }
}

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:

{
  "mcpServers": {
    "supersaas-slots": {
      "command": "uvx",
      "args": ["supersaas-slots-mcp"]
    }
  }
}

Tool

`find_available_slots`

{
  "schedule_url": "https://www.supersaas.nl/schedule/downthehatch/SLEEP",
  "from_date": "2026-10-19",
  "through_date": "2026-10-25"
}

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.

Response

{
  "schedule_url": "https://www.supersaas.nl/schedule/downthehatch/SLEEP",
  "from_date": "2026-10-19",
  "through_date": "2026-10-25",
  "time_basis": "schedule wall time; epoch values interpreted as UTC",
  "unit": "slot",
  "duration_minutes": 180,
  "count": 1,
  "truncated": false,
  "slots": [{ "start": "2026-10-22 09:30", "end": "2026-10-22 12:30" }]
}

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:

{
  "unit": "night",
  "duration_minutes": 1440,
  "check_in": "14:00",
  "check_out": "12:00",
  "slots": [{ "start": "2026-10-05 14:00", "end": "2026-10-06 12:00" }],
  "stays": [{ "start": "2026-10-05", "end": "2026-10-10", "nights": 5 }]
}

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:

{
  "unit": "class",
  "slots": [{
    "id": 101,
    "start": "2026-10-01 19:00",
    "end": "2026-10-01 20:00",
    "title": "CardioSculpt",
    "location": "Village Hall",
    "capacity": 40,
    "booked": 32,
    "waiting": 0,
    "available": 8
  }]
}

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.

Errors

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.

Scope

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.

Development

.venv/bin/python -m unittest -v test_supersaas_mcp.py
.venv/bin/python check_release.py

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.

Release

Releases use PyPI Trusted Publishing and MCP Registry GitHub OIDC. Before the first release:

Create a 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.
Create an mcp-registry GitHub environment and allow deployment from version tags. The Registry uses GitHub OIDC, so it needs no registry token.
Keep the version in 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.
Push a matching tag, for example 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.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install SuperSaaS Slots?

Does SuperSaaS Slots need an API key?

What transport does SuperSaaS Slots use?

When was SuperSaaS Slots last checked?

Documentation

SuperSaaS slots MCP server

Install

Connect

Tool

find_available_slots

Response

Errors

Scope

Development

Release

`find_available_slots`