bizidashboard-mcp
This MCP server exposes historical and analytical data for the Zaragoza Bizi bike-share system, going beyond the official GBFS real-time feed. You can:
Get latest station snapshots (
get_stations): bikes available, free anchors, capacity, location.Rank stations (
get_rankings) by turnover or availability to identify busiest or most reliably stocked stations.List active alerts (
get_alerts) for stations low on bikes or anchors.Query alert history (
get_alerts_history) by station, type, severity, state, and time range.Get hourly occupancy patterns (
get_patterns) for weekday vs. weekend.Retrieve occupancy heatmap cells (
get_heatmap) by day and hour.Analyze mobility signals (
get_mobility): hourly demand curves, station-to-station flows, and transit impact.Access full historical daily demand data (
get_history) since BiziDashboard started recording.Generate a rebalancing report (
get_rebalancing_report) with station classifications, empty/full risk predictions, and origin-destination transfer recommendations.
Most tools support JSON or CSV output (some CSV exports or extended windows require elevated permissions), and the server can integrate with LLM clients like Claude, ChatGPT, and Gemini via local stdio or remote HTTP/OpenAPI endpoints.
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., "@bizidashboard-mcp Show me the stations with the highest turnover this week."
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.
bizidashboard-mcp
Model Context Protocol server for BiziDashboard's Zaragoza bike-share analytics: stations, history, occupancy, alerts, mobility, and rebalancing.
Unlike the official GBFS feed (which only exposes the current state of the system), BiziDashboard stores and analyzes history: rankings, occupancy patterns, mobility signals, alert history, and a station rebalancing diagnostic report. This server makes that analytical layer easy to query from Claude Desktop or any other MCP client.
Installation
Published on npm — no cloning or compiling required. Add it to your MCP client config
(e.g. claude_desktop_config.json):
{
"mcpServers": {
"bizidashboard": {
"command": "npx",
"args": ["-y", "bizidashboard-mcp"]
}
}
}From source
git clone https://github.com/gcaguilar/bizidashboard-mcp.git
cd bizidashboard-mcp
npm install
npm run buildThen point your MCP client at the built entrypoint:
{
"mcpServers": {
"bizidashboard": {
"command": "node",
"args": ["/absolute/path/to/bizidashboard-mcp/dist/index.js"]
}
}
}Related MCP server: mcp-stm-montevideo
Configuration
BiziDashboard API (outbound)
Variable | Default | Purpose |
|
| Base URL of the BiziDashboard instance to query. Override to point at another city's deployment or a local dev server. |
| (none) | Local stdio only. Optional legacy |
| (none) | Optional local stdio Auth0 access token forwarded to DatosBizi. |
HTTP Server & OAuth (inbound, remote clients only)
The HTTP server requires OAuth-based authentication via Auth0. Before running it, you must:
Create an Auth0 API for the MCP resource, with exact identifier
https://mcp.datosbizi.com/mcp, RS256, and scopesread:dashboardandread:exports. Enable Dynamic Client Registration and Resource Parameter Compatibility Profile in the tenant. Claude and ChatGPT then register their own public clients; users do not receive an OAuth secret.The API must also accept third-party (DCR) clients. In Applications → APIs → the MCP API → Settings → Default Permissions for Third Party Apps, enable User-Delegated Access and select
read:dashboardandread:exports. Without this, every connector fails at/authorizewithClient "<id>" is not authorized to access resource server. Keep the tenant below its Applications limit (10 on the Free plan): DCR then returnstoo_many_entitiesand no client registration succeeds.In Applications → APIs → the MCP API, select Add Application to create its Custom API Client. Grant that client user-delegated access to
https://api.datosbizi.comand enable On-Behalf-Of Token Exchange. It is not the ordinary Machine-to-Machine application. Keep its client secret only in the MCP deployment.Configure these environment variables:
Variable | Purpose |
| Required. Your Auth0 tenant domain, e.g., |
| Required in production. Exact MCP Auth0 API identifier: |
| Required in production. Existing DatosBizi API identifier, e.g. |
| Required in production. Client ID of the special Auth0 resource-server OBO client. |
| Required in production. Secret of that OBO client. Store only as a Coolify secret. |
| Optional comma-separated browser origins allowed to call the HTTP MCP, e.g. |
| Set to |
| Set to |
| (optional) The public URL of this server (e.g., |
| (optional) HTTP port. Default |
Do not set AUTH0_AUDIENCES, AUTH0_ACCESS_TOKEN_ALLOWED_CLIENT_IDS,
AUTH0_CLIENT_IDS, or OAUTH_PROXY_ORIGIN on this public DCR deployment.
BASE_URL is required in production and must be the HTTPS MCP URL. Set
BIZI_ALLOWED_API_HOSTS to an explicit comma-separated allowlist (normally
datosbizi.com) so authenticated tokens are never forwarded to an unintended
origin.
Running without DCR (shared client, any number of users)
DCR creates one Auth0 Application per connector installation, so a free tenant (10 Applications) runs out after a handful of users. A pre-registered or CIMD client is one per AI product for all users: each user still signs in with their own account and gets their own token, but no Application is created.
Option A — one shared public client (works today, no user-side registration).
Auth0 → Applications → Create Application → Single Page Application. Do not use Regular Web Application: that type is confidential and would force a client secret into every user's connector form.
Set Allowed Callback URLs:
https://claude.ai/api/mcp/auth_callback,https://chatgpt.com/connector_platform_oauth_redirect,http://localhost/callback,http://127.0.0.1/callback. If ChatGPT shows ahttps://chatgpt.com/connector/oauth/<id>redirect in the connector page instead, add that exact URI too (it is used when the authorization server does not advertise RFC 9207iss).Grant types: Authorization Code, Refresh Token. Authentication Method:
none(public client with PKCE). Authorize the app for the MCP API withread:dashboardandread:exports(per-app client grant, or the API's Default Permissions). Enable the login connection at domain level.Disable Dynamic Client Registration in the tenant.
Users connect with Use your own OAuth client (Claude) or the pre-defined OAuth client field (ChatGPT) and paste this
client_id; leave the secret empty.
Option B — CIMD (no fields for users to fill).
Auth0 → Settings → Advanced → enable Client ID Metadata Document (CIMD) Registration.
Applications → Create Application → Import from URL, once per AI client:
https://chatgpt.com/oauth/client.jsonand Claude's published document (Claude Code:https://claude.ai/oauth/claude-code-client-metadata).Deploy with
MCP_CIMD_ENABLED=true. Claude selects CIMD only when the metadata also advertisesnoneintoken_endpoint_auth_methods_supported, which this server does.Disable Dynamic Client Registration.
CIMD clients are third-party applications: they need an API access policy
(client grant) for the MCP API and fail if the tenant has active Rules.
ChatGPT's CIMD prefers private_key_jwt, which Auth0 only allows on Enterprise
plans — verify the import works on a free tenant, otherwise use Option A for
ChatGPT.
For local authenticated use, enable Device Authorization for a local DatosBizi
Auth0 client and run bizidashboard-mcp-login with AUTH0_DOMAIN,
AUTH0_CLIENT_ID and AUTH0_AUDIENCE. It stores tokens in
~/.config/bizidashboard-mcp/tokens.json; the stdio server refreshes them when a
refresh token is available. Set BIZI_TOKEN_FILE to override that path.
Stdio Server (Claude Desktop, no auth needed)
All BIZI_* variables above are optional; if omitted, they default to the public BiziDashboard.
The stdio server (bizidashboard-mcp) needs no authentication.
Tools
Tool | Description |
| Latest availability snapshot for every station. |
| Rank stations by turnover or availability. |
| Currently active low-bikes/low-anchors alerts. |
| Filterable/paginated alert history. Remote |
| Weekday/weekend hourly occupancy pattern for one station. |
| Occupancy heatmap cells for one station. |
| Hourly/daily mobility signals and transit impact. |
| Full historical daily demand data since first record. |
| Station diagnostics (A–F classification), risk predictions, and transfer recommendations. Remote |
Every tool remains visible to every authenticated remote user. Every tool returns the
API's JSON response as-is (or CSV text when format: "csv" is requested); nothing is
summarized or transformed. An elevated request without read:exports returns an
actionable authorization error telling the user to reconnect with that scope. Other
upstream errors (bad params, rate limits) retain their original status and message.
Remote connector (Claude / ChatGPT)
npx bizidashboard-mcp (stdio) only works for local clients like Claude
Desktop. To use this data from claude.ai remote connectors or ChatGPT,
run the HTTP server instead and expose it publicly over HTTPS. It exposes the
same nine tools through one standard MCP endpoint:
Endpoint | Protocol | Used by |
| MCP Streamable HTTP (stateless) | Claude and ChatGPT |
Every route except /healthz requires an OAuth bearer token
(Authorization Code flow with Auth0), obtained after registering as described above.
The remote server validates issuer, MCP audience, signature, expiry, azp (when
configured), and read:dashboard. It then performs an Auth0 On-Behalf-Of exchange,
so BiziDashboard receives a token for https://api.datosbizi.com, preserving the
signed-in user and their scopes without accepting an MCP token at the downstream API.
Run it on your own server
With Docker (image published to GHCR on every push to main/tag by
.github/workflows/docker-publish.yml):
docker run -d \
--name bizidashboard-mcp \
-p 8787:8787 \
-e AUTH0_DOMAIN=<your-auth0-domain> \
-e MCP_AUTH0_AUDIENCE=https://mcp.yourdomain.com/mcp \
-e API_AUTH0_AUDIENCE=https://api.datosbizi.com \
-e MCP_AUTH0_CLIENT_ID=<obo-client-id> \
-e MCP_AUTH0_CLIENT_SECRET=<obo-client-secret> \
-e BASE_URL=https://mcp.yourdomain.com \
ghcr.io/gcaguilar/bizidashboard-mcp:latestFrom source:
npm install
npm run build
AUTH0_DOMAIN=<your-auth0-domain> \
MCP_AUTH0_AUDIENCE=https://mcp.yourdomain.com/mcp \
API_AUTH0_AUDIENCE=https://api.datosbizi.com \
MCP_AUTH0_CLIENT_ID=<obo-client-id> \
MCP_AUTH0_CLIENT_SECRET=<obo-client-secret> \
npm run start:httpEither way, put it behind a reverse proxy (Caddy, nginx, Traefik, …) on your
VPS to terminate TLS on a real domain — https://mcp.yourdomain.com — since
neither client below will call a plain-HTTP or self-signed endpoint.
Register it
Claude (claude.ai → Settings → Connectors → Add custom connector): URL
https://mcp.yourdomain.com/mcp. Authentication is OAuth 2.0 Authorization Code; Claude will discover the flow automatically via/.well-known/oauth-protected-resource.ChatGPT MCP / GPT builder: use the MCP URL and let the client complete OAuth through Dynamic Client Registration. Do not embed the OBO client secret in ChatGPT or in a public page.
OpenAI plugin submission
The MCP-only plugin package is in plugins/bizidashboard-mcp. It includes the
directory metadata and starter prompts for ChatGPT/Codex. Submission copy and
review cases are in docs/openai-plugin-submission.md.
The public submission still needs a verified OpenAI publisher identity, legal
URLs, regional availability, and OAuth reviewer credentials.
Development
npm run build # compile TypeScript to dist/ (both the stdio and HTTP entrypoints)
npm run typecheck # type-check without emitting
npm test # build, then run integration tests against the live public API
npm run start:http # run the HTTP MCP server locally (needs the Auth0 MCP/OBO variables above)To build the Docker image locally: docker build -t bizidashboard-mcp .
The existing tool smoke tests hit https://datosbizi.com for real. Focused
authorization tests use no live credentials and verify that remote HTTP requests never
send BIZI_PUBLIC_API_KEY.
Available Tools
9 toolsget_alertsA
List currently active alerts (stations running low on bikes or free anchors right now).
Inputs: limit.
get_alerts_historyA
Query historical alerts (resolved and active) with filters by station, alert type, severity, and time range. This is the tool for "how often has station X run out of bikes" style questions. Requesting format=csv or a limit above 500 rows requires BIZI_PUBLIC_API_KEY to be configured.
Inputs: to, from, limit, state, +5 more.
get_heatmapB
Get occupancy heatmap cells (day x hour) for a single station.
Inputs: stationId (required).
get_historyA
Get full historical daily demand/balance data since BiziDashboard started recording this city, plus coverage metadata. This is the long-range view the official GBFS feed cannot provide since it only exposes current state.
Inputs: format.
get_mobilityA
Get mobility signals: hourly demand curve, station-to-station flow signals, and public transit impact analysis. Good for understanding usage rhythms rather than instantaneous state.
Inputs: month, demandDays, mobilityDays.
get_patternsA
Get weekday vs. weekend hourly occupancy patterns for a single station, showing typical bike availability by hour.
Inputs: stationId (required).
get_rankingsA
Rank stations by turnover (bike rotation activity) or availability. Useful for finding the busiest or most reliably stocked stations over the observed history.
Inputs: type (required), limit, format.
get_rebalancing_reportA
Get the station rebalancing diagnostic report: per-station classification (overstock, deficit, peak saturation, peak emptying, balanced, data_review), 1h/3h empty/full risk predictions, and origin-destination bike transfer recommendations. Optionally filter by district/barrio. Requesting format=csv or a days window above 30 requires BIZI_PUBLIC_API_KEY to be configured.
Inputs: days, format, district.
get_stationsA
List every Bizi Zaragoza station with its latest known availability snapshot (bikes available, free anchors, capacity, location). Reflects the most recent GBFS collection, not necessarily real time to the second.
Inputs: format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools have clearly distinct purposes, but get_patterns and get_heatmap both describe occupancy patterns for a single station, differing only in data format (weekday/weekend hourly vs day x hour heatmap). get_rankings and get_mobility are also somewhat related but descriptions clarify their distinct focuses.
All tools follow a consistent get_<noun> pattern, using snake_case throughout. The naming is predictable and makes it easy for an agent to infer the resource being accessed.
Nine tools is a well-scoped set for a bike-sharing analytics dashboard, covering current status, alerts, historical trends, mobility patterns, and rebalancing diagnostics without feeling bloated or sparse.
The tool set provides comprehensive coverage of the station analytics domain: current availability, rankings, active and historical alerts, hourly patterns, heatmaps, long-range history, mobility signals, and rebalancing recommendations. No obvious dead ends or missing core operations.
Maintenance
Related MCP Connectors
MCP server exposing the Backtest360 engine API as tools for AI agents.
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for querying Spanish government open data APIs including grants, legislation, company registry, statistics, and open data catalog. Enables LLMs to access Spanish public information on-the-fly.265MIT
- AlicenseNot gradedqualityCmaintenanceMCP server exposing Montevideo public transportation data (STM) as tools for AI assistants, enabling natural language queries about routes, stops, arrivals, and trip planning.17 npm1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server to query public open data from Recife, Brazil using natural language. It exposes tools for schema exploration and SQL query generation via Gemini 2.5 Flash, backed by a local DuckDB database.1MIT
- AlicenseBqualityDmaintenanceMCP server for grounded analysis of synthetic electric-taxi operations data, exposing tools for aggregated metrics, charging risk, and policy retrieval.3MIT