vbl-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vbl-mcp list clubs in Antwerp"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
vbl-mcp
MCP (Model Context Protocol) server for the public Basketball Vlaanderen (VBL) API — the vblcb.wisseq.eu backend used by basketbal.vlaanderen. Read-only.
Repository: github.com/jmolinasoler/vbl_mcp · Public instance: vblmcp.valvestudio.io
See examples/ for ready-made MCP client configurations (Claude Code, Hermes, stdio-only clients via mcp-remote) and a /vbl Agent Skill that runs the right queries from a single slash command. Deployment is via render.yaml, a one-click Render Blueprint. See the API key guide for provisioning, client configuration, rotation, and troubleshooting.
Official API documentation: ApiDocV2.pdf (source).
Terms of use (from the official document): the APIs may only be used to integrate match calendars, results and standings on websites of clubs affiliated with Basketbal Vlaanderen vzw. Any other party or use requires contacting info@basketbal.vlaanderen.
Features
Two transports: stdio (local MCP clients) and Streamable HTTP (
/mcp) for deployments.Status dashboard at
/(HTTP mode): uptime, active sessions with client name/IP/last activity, tool-usage counters and a recent-calls log — so you can see who is using the server. Auto-refreshes every 15 s; stats are in-memory and reset on restart.Health endpoint at
/health: JSON with uptime, session/call counters and a cached (60 s) reachability check of the upstream VBL API.Login-protected dashboard: a username/password account (seeded from
ADMIN_USERNAME/ADMIN_PASSWORD) guards the status page and the admin API. Passwords are scrypt-hashed, sessions are HTTP-onlySameSite=Strictcookies persisted across restarts, and repeated failed logins are rate-limited./healthstays public for container health checks.Multiple accounts with roles: the seeded account is an admin and is the only one that can create further accounts (dashboard Users panel or
POST /admin/users) — there is no self-service signup. A plain user holds at most 3 active API keys and only sees and revokes their own; an admin has unlimited keys and can revoke anyone's.API key management from the app: create and revoke keys from the dashboard once signed in (or via
/admin/keys). Keys can also be seeded viaMCP_API_KEYS(hermes:key1,claude:key2); all of them require theX-API-Keyheader on/mcp.Usage metering per request: every tool call records estimated tokens in/out (≈ characters ÷ 4) and duration. Aggregates per key and per tool are persisted to disk as the basis for usage-based billing; the dashboard shows per-request consumption and per-key totals.
Related MCP server: nba-mcp
Tools
Tool | VBL endpoint | Description |
|
| All clubs, with optional filter on name/city/region/stam number |
|
| Club detail: teams and their poules, website, address, venues ( |
|
| Registered members of a club (players, coaches, …) |
|
| All matches of all teams of a club |
|
| Team detail: official standings of its poules, roster ( |
|
| Calendar and results of one team |
|
| Full calendar and results of a poule (series) |
|
| Official standings of a poule (rangNr, wedPunt, ptVoor/ptTegen, …); falls back to standings computed from played matches |
|
| Full match detail (rescheduling history optional) |
|
| Digital scoresheet (DWF) lineups; |
Local development
The project is developed test-first — see the testing & TDD guide for the workflow and the test harness (fake VBL upstream, in-memory MCP client, isolated HTTP app).
npm run test:watch # red-green-refactor loop
npm run check # typecheck + full suite, same as CIgit clone https://github.com/jmolinasoler/vbl_mcp.git
cd vbl_mcp
npm install
npm run build
# stdio mode (default) — for Claude Code / Claude Desktop
npm start
# HTTP mode — dashboard on http://localhost:3000
npm run start:httpClaude Code
The repo ships a .mcp.json, so opening this directory with Claude Code registers the server automatically (stdio). To register it globally:
claude mcp add vbl -- node /path/to/vbl_mcp/dist/index.jsTo use a deployed instance over HTTP instead:
claude mcp add --transport http vbl https://your-domain.example/mcp
# with auth:
claude mcp add --transport http vbl https://your-domain.example/mcp --header "X-API-Key: <key>"Claude Desktop
{
"mcpServers": {
"vbl": {
"command": "node",
"args": ["/path/to/vbl_mcp/dist/index.js"]
}
}
}Environment variables
The server is configured entirely through the environment. On Render these are
set in the blueprint or in Dashboard → Environment; locally, export them
before npm run start:http.
Variable | Default | Purpose |
|
| HTTP listen port. Render sets this itself |
|
| Interface to bind. Every interface by default, as PaaS hosts require |
| – | Set to |
| – | Seed API keys, comma-separated and optionally labeled: |
| – | Dashboard account, created on first start. Unset = the dashboard stays public |
| – | Password for that account. Only used to create it; changing it later from the UI wins over the variable |
|
| Login session lifetime |
| – | Optional |
|
| Where users, sessions, API keys and usage metering are persisted ( |
Dashboard login
Set ADMIN_USERNAME and ADMIN_PASSWORD and the account is created on first start; from then on / asks for a login and the admin API accepts that session. The password is only read to create the account — changing it from the UI is permanent, and restarting with the old variable does not reset it.
Passwords are hashed with scrypt and a per-password salt; the plaintext is never stored.
Sessions are opaque, HTTP-only,
SameSite=Strictcookies (which is also the CSRF defence for the admin endpoints),Securewhen the request arrives over HTTPS. They live in the store, so a restart does not sign you out.Changing your password signs every browser out, including the current one.
After 10 failed attempts for a username+IP, logins are refused for 15 minutes.
Leaving
ADMIN_USERNAMEunset keeps the dashboard public, as it was before this feature, so upgrading an existing deployment cannot lock you out. The page then shows a warning banner — the dashboard exposes client IPs and usage, so configure an account on any public instance.
Accounts & roles
The seeded ADMIN_USERNAME account is an admin. Admins create every other account from the dashboard's Users panel or the API; users cannot register themselves.
admin | user | |
Create / list / delete accounts | yes | no |
API keys | unlimited | max 3 active |
Keys it can see and revoke | all, with their owner | only its own |
Sessions, client IPs, call log | yes | no |
# create a normal user (admin session or X-Admin-Token)
curl -X POST https://your-domain/admin/users \
-H "X-Admin-Token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"username":"player","password":"at-least-8-characters"}'
# add "role":"admin" for another operator
curl https://your-domain/admin/users -H "X-Admin-Token: $ADMIN_TOKEN" # list
curl -X DELETE https://your-domain/admin/users/<id> -H "X-Admin-Token: $ADMIN_TOKEN"Deleting an account signs it out and revokes its keys (usage stays for billing); an admin cannot delete itself. Accounts created before roles existed are treated as admins on upgrade, so nobody gets locked out. See the API key guide for the full permission matrix.
API keys & usage metering
Sign in and the dashboard gains a key-management panel: give the key a label (one per client) and hit Create API key — the full key is shown only once. Revoking a key immediately returns 401 to its clients. A non-admin sees its own keys and its remaining quota (3 active keys); creating a fourth returns 403 until one is revoked.
The same operations are available as an admin API, authorized by your login cookie or by X-Admin-Token if you set ADMIN_TOKEN for scripts:
# create
curl -X POST https://your-domain/admin/keys \
-H "X-Admin-Token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"label":"hermes"}'
# list with usage (requests, errors, tokens in/out, per-tool breakdown)
curl https://your-domain/admin/keys -H "X-Admin-Token: $ADMIN_TOKEN"
# revoke
curl -X DELETE https://your-domain/admin/keys/<id> -H "X-Admin-Token: $ADMIN_TOKEN"Every tool call is metered: estimated tokens in (arguments) and out (response), computed as ≈ characters ÷ 4, plus duration and error flag. Aggregates per key and per tool are persisted in DATA_DIR/store.json — GET /admin/keys is effectively the billing export (scoped to your own keys unless you are an admin). The dashboard additionally shows the last 50 calls with their individual consumption.
Deploying on Render
render.yaml at the repo root is a Render Blueprint: a Docker web
service in frankfurt on the free plan, /health as the health check, and a
generated ADMIN_PASSWORD / ADMIN_TOKEN. It is set up for testing — read
"Free instances" below before putting real clients on it.
Render is the only supported deployment target: the Dockerfile exists so
Render can build the service, not as a distributable image.
Option A — Blueprint (recommended)
In Render: + New → Blueprint, connect this repository and pick the branch.
Render reads
render.yamland shows the service. It prompts forMCP_API_KEYS— on the free plan, fill it in (see "Free instances"); with a disk attached you can leave it blank and mint keys from the dashboard.Apply. The first deploy builds the
Dockerfile.Open Environment and copy the generated
ADMIN_PASSWORD, then sign in athttps://<service>.onrender.com/asadmin.
Edit render.yaml before applying to change region or plan.
Option B — from the dashboard
+ New → Web Service, connect the repository, Language: Docker.
Health Check Path:
/health.On a paid plan, under Advanced → Add Disk, mount a disk at
/app/data(any size; 1 GB is plenty) so users, sessions, API keys and usage metering survive redeploys.Add
ADMIN_USERNAMEandADMIN_PASSWORDso the dashboard requires a login, plusDATA_DIR=/app/dataand optionallyADMIN_TOKEN/MCP_API_KEYS.Create the service. Render assigns
https://<service>.onrender.comand terminates HTTPS at its proxy.
Free instances
Render's free plan does not support persistent disks, so on free the
store.json lives on an ephemeral filesystem and every redeploy, restart or
idle spin-down wipes the dashboard users, the API keys minted from the UI and
all usage metering. What survives is what comes back from the environment:
the ADMIN_USERNAME / ADMIN_PASSWORD account is recreated at each start, and
MCP_API_KEYS is re-imported into the fresh store. So on free, set
MCP_API_KEYS if you want a client to keep working across restarts — a key
created from the dashboard will stop authenticating.
Free instances also spin down when idle, so the first MCP request after a pause waits for a cold start.
Making it persistent
Once you are past testing, in render.yaml switch plan to starter and
uncomment the disk: block (mounted at /app/data, matching DATA_DIR), then
re-apply the blueprint. Users, sessions, keys and metering then survive
redeploys, and keys minted from the dashboard become the normal way to
provision clients.
Trade-off: a disk means no zero-downtime deploys — Render stops the old instance before starting the new one — and the service cannot scale past one instance. Neither matters here: the store is a single JSON file that only one instance may own.
Notes
Render injects
PORT(10000 in the blueprint) and the app binds0.0.0.0, so no port configuration is needed beyond the variable.ADMIN_PASSWORDis only read to create the account. Once a disk is attached, changing the password from the UI is permanent and the variable never resets it.
After deploying, at https://<service>.onrender.com:
/— status dashboard (who is connected, tool usage)./health— health check (JSON, includes upstream VBL API reachability)./mcp— MCP Streamable HTTP endpoint for clients./admin/users— accounts (admin only);/admin/keys— API keys and usage.
GUIDs
Club:
BVBL1004(Antwerp Giants)Team:
BVBL1004HSE 2— team GUIDs contain two spaces; pass them exactly as returned byget_clubPoule:
BVBL26279180NAHSE11A(Top Division Men 1, season 2026-27; the 4 digits afterBVBLencode the season)Match:
BVBL26279180NAHSE11AAB
Notes
The API only serves current-season data; past seasons are purged.
Field names are Dutch (
naam= name,plaats= city,uitslag= result,gespeeld= played,tT/tU= home/away team,wedPunt= competition points,ptVoor/ptTegen= points for/against).The officially documented endpoints are the five wisseq methods in the table (
OrgDetailByGuid,OrgMatchesByGuid,RelatiesByOrgGuid,TeamDetailByGuid,TeamMatchesByGuid).OrgList,PouleMatchesByGuid,MatchesByWedGuidand the DWF endpoints live on the same backend and are used by the official website, but are not part of the PDF.Errors use standard HTTP status codes (400, 404, 500, …) per the official document.
License
MIT — © 2026 Julio Molina Soler. Note that the license covers this server's code only; usage of the VBL API itself is subject to the terms quoted at the top of this README.
Available Tools
10 toolsget_clubGet club detailA
Get details of one club by its GUID (e.g. BVBL1004): teams and the poules (competitions/series) each team plays in, website, address, venues (accomms) and board members (bestuur). Team GUIDs and poule GUIDs returned here can be used with get_team, get_team_matches and get_poule_matches.
Inputs: club_guid (required).
get_club_matchesGet club matchesA
List all matches (played and upcoming) of every team of a club, across all its competitions. Each match has home/away team, date, time, venue, poule and result (uitslag, empty if not played yet; gespeeld = J means played).
Inputs: club_guid (required).
get_club_membersGet club membersA
List the registered members (players, coaches, officials) of a club. Can be a large list; use the search parameter to filter by name. Returns relGuid, name, first name, birth date, gender and category.
Inputs: club_guid (required), search.
get_matchGet match detailA
Get full details of one match by its match GUID (e.g. BVBL26279180NAHSE11AAB, as returned by the *matches tools). Includes teams, venue, officials and planning status. Set include_history to true to also get the raw rescheduling history.
Inputs: match_guid (required), include_history.
get_match_lineupGet match lineup (DWF)A
Get the digital scoresheet participants (players and coaches of both teams, with jersey numbers) of a match. Only available once the digital match form exists — returns null for matches without DWF data (e.g. far in the future or past seasons).
Inputs: match_guid (required).
get_poule_matchesGet poule matchesA
List all matches of a poule (competition/series), e.g. the full calendar and results of 'Top Division Men 1'. Poule GUIDs come from get_club (e.g. BVBL26279180NAHSE11A).
Inputs: poule_guid (required).
get_poule_standingsGet poule standingsA
Get the official standings (rangschikking/klassement) of a poule. Returns teams ranked with games played (wedAant), competition points (wedPunt), wins/losses and points scored/conceded. Falls back to standings computed from played matches if the official ranking is not exposed for this poule.
Inputs: poule_guid (required).
get_teamGet team detailA
Get details of one team by its team GUID (e.g. 'BVBL1004HSE 2' — note team GUIDs contain spaces, pass them exactly as returned by get_club). Includes the official standings of every poule the team plays in, the player roster (spelers) and the staff list (tvlijst, e.g. coaches).
Inputs: team_guid (required).
get_team_matchesGet team matchesA
List all matches (played and upcoming) of one team across all its competitions. Each match includes date, time, venue, opponent, poule and result.
Inputs: team_guid (required).
list_clubsList clubsA
List all Basketball Vlaanderen clubs (organizations). Optionally filter by a search string (matched against name, city, region and stam number). Returns guid, naam (name), plaats (city), regioNaam (region) and stamNr for each club. Use the guid with the get_club* tools.
Inputs: search.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct entity or scope: clubs, club sub-resources, teams, poules, individual matches, and lineups. Even though three tools list matches, their scope is clearly differentiated as club-wide, team-specific, or poule-specific.
Tool names consistently follow a get_/list_ + resource pattern, with hierarchical names like get_club_members, get_team_matches, and get_poule_standings. The single use of list_clubs instead of get_clubs is a conventional exception, not an inconsistency.
Ten tools is a well-scoped size for a read-only basketball federation API. Each tool provides a meaningful slice of data without redundant overlap, covering clubs, teams, matches, standings, and match details.
The tool surface covers the complete read workflow from discovering clubs down to individual match lineups. Missing operations like create/update are not gaps for this read-only domain, and optional depth such as rescheduling history and DWF lineups is available.
Maintenance
Related MCP Connectors
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
KVK Handelsregister AI Connect: hosted MCP server for the Dutch business register.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP Server implementation that integrates the Balldontlie API, to provide information about players, teams and games for the NBA, NFL and MLB.486 npm26MIT
- AlicenseAqualityDmaintenanceMCP server for NBA live data and stats, providing read-only tools to query live scores, box scores, player info, standings, and more from NBA.com.1511 npm1MIT
- FlicenseBqualityDmaintenanceRead-only MCP server for the Palloliitto's result service API, enabling AI applications to search and inspect football & futsal data including clubs, teams, matches, competitions, and league tables.12-
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server for the PlayMetrics youth-sports club management platform, enabling AI agents to query clubs, teams, players, schedules, registrations, and payments.1MIT