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 · Docker image: jmolinaso/vbl-mcp · Public instance: vblmcp.valvestudio.io

See examples/ for ready-made MCP client configurations (Claude Code, Hermes, stdio-only clients via mcp-remote), a Coolify Docker Compose file, and a /vbl Agent Skill that runs the right queries from a single slash command. 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-only SameSite=Strict cookies persisted across restarts, and repeated failed logins are rate-limited. /health stays 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 via MCP_API_KEYS (hermes:key1,claude:key2); all of them require the X-API-Key header 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

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 CI

git 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:http

Claude 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.js

To 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"]
    }
  }
}

Docker

Build the image:

git clone https://github.com/jmolinasoler/vbl_mcp.git
cd vbl_mcp
docker build -t vbl-mcp .

Run it:

docker run -d --name vbl-mcp -p 3000:3000 \
  -v vbl-mcp-data:/app/data \
  -e ADMIN_USERNAME=admin -e ADMIN_PASSWORD=change-me \
  vbl-mcp

Then open http://localhost:3000/, sign in, and create your first API key from the dashboard. The /app/data volume keeps users, sessions, keys and usage metering across restarts. You can also seed keys via -e MCP_API_KEYS="hermes:change-me".

Verify:

curl http://localhost:3000/health   # health JSON
open http://localhost:3000/         # status dashboard

The image is a multi-stage build (Node 22 alpine, dev dependencies pruned, runs as the non-root node user) and declares a Docker HEALTHCHECK against /health.

Environment variables

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=Strict cookies (which is also the CSRF defence for the admin endpoints), Secure when 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_USERNAME unset 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.

# 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.

Publishing to Docker Hub

Automatically (GitHub Actions)

The repo ships a workflow (.github/workflows/docker-publish.yml) that builds a multi-arch image (linux/amd64 + linux/arm64) and pushes it to Docker Hub on every push to main and on version tags (v*). One-time setup:

1. On Docker Hub, create the repository (published as jmolinaso/vbl-mcp) and an access token (Account Settings → Personal access tokens, Read & Write).

2. On GitHub (Settings → Secrets and variables → Actions), add two repository secrets:

   • DOCKERHUB_USERNAME — your Docker Hub username

   • DOCKERHUB_TOKEN — the access token

3. Push to main (publishes :latest and :sha-…) or tag a release (git tag v0.2.0 && git push --tags publishes :0.2.0 and :0.2).

Manually

docker login
docker build -t jmolinaso/vbl-mcp:latest .
docker push jmolinaso/vbl-mcp:latest

Deploying on Coolify

Option A — from Docker Hub (recommended once published)

1. In Coolify: + New → Docker Image and enter the image name: jmolinaso/vbl-mcp:latest.

2. Ports Exposes: 3000.

3. Add ADMIN_USERNAME and ADMIN_PASSWORD so the dashboard requires a login, then create per-client API keys from it (or seed them with MCP_API_KEYS).

4. In Persistent Storage, add a volume mounted at /app/data so users, sessions, API keys and usage metering survive redeploys.

5. (Optional) In Health Checks, set the path to /health on port 3000 — or rely on the image's built-in Docker HEALTHCHECK.

6. Assign a domain and deploy. Coolify handles HTTPS via its proxy.

To pick up a new version, push the updated image and hit Redeploy (with the :latest tag Coolify re-pulls the image; pin a version tag like :0.2.0 if you prefer explicit upgrades).

Option B — build from the Git repository

1. In Coolify: + New → Application, choose Public Repository and enter https://github.com/jmolinasoler/vbl_mcp (branch main).

2. Build Pack: Dockerfile (Coolify detects the Dockerfile at the repo root automatically).

3. Continue with steps 2-6 of Option A (port 3000, ADMIN_TOKEN, persistent storage on /app/data, health check, domain).

Option C — Docker Compose

A ready-made compose file lives at examples/docker-compose.coolify.yml: pick Build Pack: Docker Compose with that file as Docker Compose Location, or paste it into + New → Docker Compose Empty. It pulls the Docker Hub image (or optionally builds from the repo), wires the domain via Coolify's SERVICE_FQDN magic variable and includes the /health container health check.

After deploying:

• https://your-domain/ — status dashboard (who is connected, tool usage).

• https://your-domain/health — health check (JSON, includes upstream VBL API reachability).

• https://your-domain/mcp — MCP Streamable HTTP endpoint for clients.

• https://your-domain/admin/users — accounts (admin only); https://your-domain/admin/keys — API keys and usage.

GUIDs

• Club: BVBL1004 (Antwerp Giants)

• Team: BVBL1004HSE 2 — team GUIDs contain two spaces; pass them exactly as returned by get_club

• Poule: BVBL26279180NAHSE11A (Top Division Men 1, season 2026-27; the 4 digits after BVBL encode 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, MatchesByWedGuid and 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.