SuperSaaS Slots MCP server

SuperSaaS slots MCP server

<!-- mcp-name: io.github.RichieB2B/supersaas-slots-mcp -->

A read-only FastMCP server for public resource schedules with one resource and explicit numeric start times. It downloads the public schedule page, extracts rpid, token, bitprefs, open_times, appointment duration, buffer, and start-time constraints, then calls /ajax/resource/ in 28-day windows. Each call explicitly requests the exception list with efrom, eto, and ed=r. No account or API key is needed for the tested public page.

Licensed under the MIT License.

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 (or www.supersaas.com). FastMCP handles the stdio protocol; the availability calculation remains in supersaas_mcp.py.

Tool

findavailableslots accepts:

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

throughdate is inclusive. Optional maxresults defaults to 500; the response includes the full count and truncated flag. Optional respectbookingwindow defaults to true and applies the page's minimum and maximum advance-booking limits. Set it to false when examining historical schedule data.

Times are returned as schedule wall-clock strings (YYYY-MM-DD HH:MM). The schedule's numeric appointment and exception epochs are interpreted as UTC, matching the tested page. The server refreshes the page and AJAX data on each call, so results can change as bookings are made.

For the saved October fixture, the week of October 19 has one free slot: October 22, 09:30–12:30. Monday is closed by the low seven bits of bit_prefs (0b1111001, Sunday first). The October 13 Tuesday exception opens 09:30–12:30.

SuperSaaS selects exception rows by their start date. To catch a blocked range that began before the requested window, the AJAX query sets efrom=1970-01-01 while keeping eto at the window's end. Exception type 0 blocks all overlapping dates; type 1 adds the listed opening interval. For example, the live response contains a type 0 block from February 19 through February 28, 2027, so the week of February 22 has no available slots.

Scope

This server handles the tested resource-schedule shape: one resource, fixed duration, up to two daily opening periods, explicit numeric start times, weekday enable bits, additive opening exceptions, blocked ranges, booked appointments, and buffer time. It rejects schedules advertising clustering, synchronization, or complex linked rules. Other SuperSaaS schedule types, recurring rule patterns, per-user limits, and payment-dependent availability are not modeled. An available slot is a calculated candidate, not a booking guarantee; the booking page remains authoritative at reservation time.

Test

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

The tests use the included copies of your example files. A live read-only call against the example schedule also returned the expected October 22 slot on 2026-09-27.

Release

Shortened. The full README is on GitHub.