Bizidashboard

MCP server exposing BiziDashboard's historical and analytical data for the Zaragoza Bizi bike-share system as tools for LLM clients.

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 build

Then point your MCP client at the built entrypoint:

{
  "mcpServers": {
    "bizidashboard": {
      "command": "node",
      "args": ["/absolute/path/to/bizidashboard-mcp/dist/index.js"]
    }
  }
}

Configuration

BiziDashboard API (outbound)

Variable	Default	Purpose
BIZI_API_BASE_URL	https://datosbizi.com	Base URL of the BiziDashboard instance to query. Override to point at another city's deployment or a local dev server.
BIZI_PUBLIC_API_KEY	(none)	Local stdio only. Optional legacy X-Public-Api-Key for elevated local calls. It is never sent by the remote HTTP MCP server.
BIZI_ACCESS_TOKEN	(none)	Optional local stdio Auth0 access token forwarded to DatosBizi. BIZI_INSTALLATION_ID is forwarded when set.

HTTP Server & OAuth (inbound, remote clients only)

The HTTP server requires OAuth-based authentication via Auth0. Before running it, you must:

1. Create an Auth0 API for the MCP resource, with exact identifier https://mcp.datosbizi.com/mcp, RS256, and scopes read:dashboard and read: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.

2. 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.com and enable On-Behalf-Of Token Exchange. It is not the ordinary Machine-to-Machine application. Keep its client secret only in the MCP deployment.

3. Configure these environment variables:

Variable	Purpose
AUTH0_DOMAIN	Required. Your Auth0 tenant domain, e.g., example.auth0.com.
MCP_AUTH0_AUDIENCE	Required in production. Exact MCP Auth0 API identifier: https://mcp.datosbizi.com/mcp. It is the audience verified for tokens received from connectors.
API_AUTH0_AUDIENCE	Required in production. Existing DatosBizi API identifier, e.g. https://api.datosbizi.com. OBO tokens are issued for this audience before the MCP calls the API.
MCP_AUTH0_CLIENT_ID	Required in production. Client ID of the special Auth0 resource-server OBO client.
MCP_AUTH0_CLIENT_SECRET	Required in production. Secret of that OBO client. Store only as a Coolify secret.
MCP_CORS_ORIGINS	Optional comma-separated browser origins allowed to call the HTTP MCP, e.g. https://datosbizi.com.
BASE_URL	(optional) The public URL of this server (e.g., https://mcp.yourdomain.com). Used to construct OAuth metadata URLs. Defaults to http://localhost:8787.
PORT	(optional) HTTP port. Default 8787.

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.

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
get_stations	Latest availability snapshot for every station.
get_rankings	Rank stations by turnover or availability.
get_alerts	Currently active low-bikes/low-anchors alerts.
get_alerts_history	Filterable/paginated alert history. Remote format=csv or limit>500 requires read:exports.
get_patterns	Weekday/weekend hourly occupancy pattern for one station.
get_heatmap	Occupancy heatmap cells for one station.
get_mobility	Hourly/daily mobility signals and transit impact.
get_history	Full historical daily demand data since first record.
get_rebalancing_report	Station diagnostics (A–F classification), risk predictions, and transfer recommendations. Remote format=csv or days>30 requires read:exports.

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
POST /mcp	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:latest

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

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