OnlineAfspraken slots MCP

Read available slots from a public OnlineAfspraken widget URL without an account. This local MCP server reads availability only; it cannot make a booking.

Get started

You need Python 3.10 or newer and an MCP client. The commands below use a Unix shell (macOS or Linux).

Download or clone this repository.
In its directory, install the package and its dependencies:
sh
```
sh setup.sh
```
Register the server with your MCP client using one of the examples below. Replace /absolute/path/to/onlineafspraken-slots-mcp with the full path to your downloaded copy.
Start a new chat and provide a public OnlineAfspraken widget URL. For example: “Show today's available times for this widget: [paste the full widget URL here].”

You can also pass the URL of a public booking page that embeds one OnlineAfspraken widget. If the page has several widgets, use the direct URL of the one you want.

Connect your MCP client

Codex

codex mcp add onlineafspraken-slots -- /absolute/path/to/onlineafspraken-slots-mcp/run.sh
codex mcp list

Claude Code

claude mcp add --scope user --transport stdio onlineafspraken-slots -- /absolute/path/to/onlineafspraken-slots-mcp/run.sh
claude mcp list

The user scope makes the server available in all your Claude Code projects. See the Claude Code MCP documentation for other scopes.

Claude Desktop

Add this entry under mcpServers in your Claude Desktop configuration, then restart Claude Desktop:

json

{
  "mcpServers": {
    "onlineafspraken-slots": {
      "command": "/absolute/path/to/onlineafspraken-slots-mcp/run.sh"
    }
  }
}

If you already have an mcpServers object, add just the onlineafspraken-slots entry to it. The Claude Desktop local server guide explains where to manage local servers and check their connection status.

OpenCode

opencode mcp add onlineafspraken-slots --global -- /absolute/path/to/onlineafspraken-slots-mcp/run.sh
opencode mcp list

The global option makes the server available in every OpenCode project. See the OpenCode MCP documentation for project-specific configuration.

After the first PyPI release, clients that support a package runner can launch the onlineafspraken-slots-mcp command from that package instead of using a local checkout.

Tool inputs

The server exposes get_available_slots:

Input	Required	Meaning
`booking_page`	Yes	Full HTTPS URL of a public OnlineAfspraken widget or a page that embeds it.
`date_iso`	No	Date in `YYYY-MM-DD` format. Defaults to today in Europe/Amsterdam.
`room`	No	Part of an appointment type name to filter the results.

Results include the appointment type names, available start times, date, timezone, and the time the availability was checked. The room input is named for the original use case; it works with any appointment type.

Limitations

The server uses the widget's public, undocumented read endpoint. A provider change may require an update. A booking page must expose its widget URL in a script, iframe, or link for automatic discovery. Available slots can change between lookup and booking.

License

MIT

Publishing a release

For maintainers: keep the version in pyproject.toml and server.json in sync. To publish the first release, configure a pending PyPI trusted publisher with these values:

PyPI field	Value
PyPI project name	`onlineafspraken-slots-mcp`
Owner	`RichieB2B`
Repository	`onlineafspraken-slots-mcp`
Workflow	`publish-pypi.yml`
Environment	`pypi`

Then publish a GitHub release tagged v0.1.0. The release workflow builds and checks the distributions, uploads them to PyPI through trusted publishing, and publishes the matching version to the official MCP Registry through GitHub OIDC.

The official MCP Registry guide explains the publishing process. The registry checks the mcp-name marker above against the README included in the PyPI release.